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