WCSLIB  5.18
wcsprintf.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 5.18 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2018, Mark Calabretta
5 
6  This file is part of WCSLIB.
7 
8  WCSLIB is free software: you can redistribute it and/or modify it under the
9  terms of the GNU Lesser General Public License as published by the Free
10  Software Foundation, either version 3 of the License, or (at your option)
11  any later version.
12 
13  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16  more details.
17 
18  You should have received a copy of the GNU Lesser General Public License
19  along with WCSLIB. If not, see http://www.gnu.org/licenses.
20 
21  Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22 
23  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24  http://www.atnf.csiro.au/people/Mark.Calabretta
25  $Id: wcsprintf.h,v 5.18 2018/01/10 08:32:14 mcalabre Exp $
26 *=============================================================================
27 *
28 * WCSLIB 5.18 - C routines that implement the FITS World Coordinate System
29 * (WCS) standard. Refer to the README file provided with WCSLIB for an
30 * overview of the library.
31 *
32 *
33 * Summary of the wcsprintf routines
34 * ---------------------------------
35 * Routines in this suite allow diagnostic output from celprt(), linprt(),
36 * prjprt(), spcprt(), tabprt(), wcsprt(), and wcserr_prt() to be redirected to
37 * a file or captured in a string buffer. Those routines all use wcsprintf()
38 * for output. Likewise wcsfprintf() is used by wcsbth() and wcspih(). Both
39 * functions may be used by application programmers to have other output go to
40 * the same place.
41 *
42 *
43 * wcsprintf() - Print function used by WCSLIB diagnostic routines
44 * ---------------------------------------------------------------
45 * wcsprintf() is used by celprt(), linprt(), prjprt(), spcprt(), tabprt(),
46 * wcsprt(), and wcserr_prt() for diagnostic output which by default goes to
47 * stdout. However, it may be redirected to a file or string buffer via
48 * wcsprintf_set().
49 *
50 * Given:
51 * format char* Format string, passed to one of the printf(3) family
52 * of stdio library functions.
53 *
54 * ... mixed Argument list matching format, as per printf(3).
55 *
56 * Function return value:
57 * int Number of bytes written.
58 *
59 *
60 * wcsfprintf() - Print function used by WCSLIB diagnostic routines
61 * ----------------------------------------------------------------
62 * wcsfprintf() is used by wcsbth(), and wcspih() for diagnostic output which
63 * they send to stderr. However, it may be redirected to a file or string
64 * buffer via wcsprintf_set().
65 *
66 * Given:
67 * stream FILE* The output stream if not overridden by a call to
68 * wcsprintf_set().
69 *
70 * format char* Format string, passed to one of the printf(3) family
71 * of stdio library functions.
72 *
73 * ... mixed Argument list matching format, as per printf(3).
74 *
75 * Function return value:
76 * int Number of bytes written.
77 *
78 *
79 * wcsprintf_set() - Set output disposition for wcsprintf() and wcsfprintf()
80 * -------------------------------------------------------------------------
81 * wcsprintf_set() sets the output disposition for wcsprintf() which is used by
82 * the celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and
83 * wcserr_prt() routines, and for wcsfprintf() which is used by wcsbth() and
84 * wcspih().
85 *
86 * Given:
87 * wcsout FILE* Pointer to an output stream that has been opened for
88 * writing, e.g. by the fopen() stdio library function,
89 * or one of the predefined stdio output streams - stdout
90 * and stderr. If zero (NULL), output is written to an
91 * internally-allocated string buffer, the address of
92 * which may be obtained by wcsprintf_buf().
93 *
94 * Function return value:
95 * int Status return value:
96 * 0: Success.
97 *
98 *
99 * wcsprintf_buf() - Get the address of the internal string buffer
100 * ---------------------------------------------------------------
101 * wcsprintf_buf() returns the address of the internal string buffer created
102 * when wcsprintf_set() is invoked with its FILE* argument set to zero.
103 *
104 * Function return value:
105 * const char *
106 * Address of the internal string buffer. The user may
107 * free this buffer by calling wcsprintf_set() with a
108 * valid FILE*, e.g. stdout. The free() stdlib library
109 * function must NOT be invoked on this const pointer.
110 *
111 *
112 * WCSPRINTF_PTR() macro - Print addresses in a consistent way
113 * -----------------------------------------------------------
114 * WCSPRINTF_PTR() is a preprocessor macro used to print addresses in a
115 * consistent way.
116 *
117 * On some systems the "%p" format descriptor renders a NULL pointer as the
118 * string "0x0". On others, however, it produces "0" or even "(nil)". On
119 * some systems a non-zero address is prefixed with "0x", on others, not.
120 *
121 * The WCSPRINTF_PTR() macro ensures that a NULL pointer is always rendered as
122 * "0x0" and that non-zero addresses are prefixed with "0x" thus providing
123 * consistency, for example, for comparing the output of test programs.
124 *
125 *===========================================================================*/
126 
127 #ifndef WCSLIB_WCSPRINTF
128 #define WCSLIB_WCSPRINTF
129 
130 #include <stdio.h>
131 
132 #ifdef __cplusplus
133 extern "C" {
134 #endif
135 
136 #define WCSPRINTF_PTR(str1, ptr, str2) \
137  if (ptr) { \
138  wcsprintf("%s%#lx%s", (str1), (unsigned long)(ptr), (str2)); \
139  } else { \
140  wcsprintf("%s0x0%s", (str1), (str2)); \
141  }
142 
143 int wcsprintf_set(FILE *wcsout);
144 int wcsprintf(const char *format, ...);
145 int wcsfprintf(FILE *stream, const char *format, ...);
146 const char *wcsprintf_buf(void);
147 
148 #ifdef __cplusplus
149 }
150 #endif
151 
152 #endif /* WCSLIB_WCSPRINTF */
int wcsfprintf(FILE *stream, const char *format,...)
Print function used by WCSLIB diagnostic routines.
int wcsprintf(const char *format,...)
Print function used by WCSLIB diagnostic routines.
int wcsprintf_set(FILE *wcsout)
Set output disposition for wcsprintf() and wcsfprintf().
const char * wcsprintf_buf(void)
Get the address of the internal string buffer.