WCSLIB: wcsprintf.h Source File

WCSLIB 4.25.1

- Main Page
- Related Pages
- Data Structures
- Files

- File List
- Globals

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