WCSLIB: wcsprintf.h Source File

WCSLIB 7.11

wcsprintf.h
Go to the documentation of this file.
1/*============================================================================
2 WCSLIB 7.11 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2022, 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 7.11 2022/04/26 06:13:52 mcalabre Exp $
23*=============================================================================
24*
25* WCSLIB 7.11 - 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
131extern "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
wcsprintf
int wcsprintf(const char *format,...)
Print function used by WCSLIB diagnostic routines.
wcsprintf_set
int wcsprintf_set(FILE *wcsout)
Set output disposition for wcsprintf() and wcsfprintf().
wcsfprintf
int wcsfprintf(FILE *stream, const char *format,...)
Print function used by WCSLIB diagnostic routines.
wcsprintf_buf
const char * wcsprintf_buf(void)
Get the address of the internal string buffer.