WCSLIB  7.3.1
wcsprintf.h
Go to the documentation of this file.
1 /*============================================================================
2  WCSLIB 7.3 - an implementation of the FITS WCS standard.
3  Copyright (C) 1995-2020, 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  Direct correspondence concerning WCSLIB to mark@calabretta.id.au
21 
22  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
23  http://www.atnf.csiro.au/people/Mark.Calabretta
24  $Id: wcsprintf.h,v 7.3.1.2 2020/08/17 11:19:09 mcalabre Exp mcalabre $
25 *=============================================================================
26 *
27 * WCSLIB 7.3 - C routines that implement the FITS World Coordinate System
28 * (WCS) standard. Refer to the README file provided with WCSLIB for an
29 * overview of the library.
30 *
31 *
32 * Summary of the wcsprintf routines
33 * ---------------------------------
34 * Routines in this suite allow diagnostic output from celprt(), linprt(),
35 * prjprt(), spcprt(), tabprt(), wcsprt(), and wcserr_prt() to be redirected to
36 * a file or captured in a string buffer. Those routines all use wcsprintf()
37 * for output. Likewise wcsfprintf() is used by wcsbth() and wcspih(). Both
38 * functions may be used by application programmers to have other output go to
39 * the same place.
40 *
41 *
42 * wcsprintf() - Print function used by WCSLIB diagnostic routines
43 * ---------------------------------------------------------------
44 * wcsprintf() is used by celprt(), linprt(), prjprt(), spcprt(), tabprt(),
45 * wcsprt(), and wcserr_prt() for diagnostic output which by default goes to
46 * stdout. However, it may be redirected to a file or string buffer via
47 * wcsprintf_set().
48 *
49 * Given:
50 * format char* Format string, passed to one of the printf(3) family
51 * of stdio library functions.
52 *
53 * ... mixed Argument list matching format, as per printf(3).
54 *
55 * Function return value:
56 * int Number of bytes written.
57 *
58 *
59 * wcsfprintf() - Print function used by WCSLIB diagnostic routines
60 * ----------------------------------------------------------------
61 * wcsfprintf() is used by wcsbth(), and wcspih() for diagnostic output which
62 * they send to stderr. However, it may be redirected to a file or string
63 * buffer via wcsprintf_set().
64 *
65 * Given:
66 * stream FILE* The output stream if not overridden by a call to
67 * wcsprintf_set().
68 *
69 * format char* Format string, passed to one of the printf(3) family
70 * of stdio library functions.
71 *
72 * ... mixed Argument list matching format, as per printf(3).
73 *
74 * Function return value:
75 * int Number of bytes written.
76 *
77 *
78 * wcsprintf_set() - Set output disposition for wcsprintf() and wcsfprintf()
79 * -------------------------------------------------------------------------
80 * wcsprintf_set() sets the output disposition for wcsprintf() which is used by
81 * the celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and
82 * wcserr_prt() routines, and for wcsfprintf() which is used by wcsbth() and
83 * wcspih().
84 *
85 * Given:
86 * wcsout FILE* Pointer to an output stream that has been opened for
87 * writing, e.g. by the fopen() stdio library function,
88 * or one of the predefined stdio output streams - stdout
89 * and stderr. If zero (NULL), output is written to an
90 * internally-allocated string buffer, the address of
91 * which may be obtained by wcsprintf_buf().
92 *
93 * Function return value:
94 * int Status return value:
95 * 0: Success.
96 *
97 *
98 * wcsprintf_buf() - Get the address of the internal string buffer
99 * ---------------------------------------------------------------
100 * wcsprintf_buf() returns the address of the internal string buffer created
101 * when wcsprintf_set() is invoked with its FILE* argument set to zero.
102 *
103 * Function return value:
104 * const char *
105 * Address of the internal string buffer. The user may
106 * free this buffer by calling wcsprintf_set() with a
107 * valid FILE*, e.g. stdout. The free() stdlib library
108 * function must NOT be invoked on this const pointer.
109 *
110 *
111 * WCSPRINTF_PTR() macro - Print addresses in a consistent way
112 * -----------------------------------------------------------
113 * WCSPRINTF_PTR() is a preprocessor macro used to print addresses in a
114 * consistent way.
115 *
116 * On some systems the "%p" format descriptor renders a NULL pointer as the
117 * string "0x0". On others, however, it produces "0" or even "(nil)". On
118 * some systems a non-zero address is prefixed with "0x", on others, not.
119 *
120 * The WCSPRINTF_PTR() macro ensures that a NULL pointer is always rendered as
121 * "0x0" and that non-zero addresses are prefixed with "0x" thus providing
122 * consistency, for example, for comparing the output of test programs.
123 *
124 *===========================================================================*/
125 
126 #ifndef WCSLIB_WCSPRINTF
127 #define WCSLIB_WCSPRINTF
128 
129 #include <inttypes.h>
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%#" PRIxPTR "%s", (str1), (uintptr_t)(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.