00001 /*============================================================================ 00002 00003 WCSLIB 4.17 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2013, Mark Calabretta 00005 00006 This file is part of WCSLIB. 00007 00008 WCSLIB is free software: you can redistribute it and/or modify it under the 00009 terms of the GNU Lesser General Public License as published by the Free 00010 Software Foundation, either version 3 of the License, or (at your option) 00011 any later version. 00012 00013 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY 00014 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 00015 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for 00016 more details. 00017 00018 You should have received a copy of the GNU Lesser General Public License 00019 along with WCSLIB. If not, see http://www.gnu.org/licenses. 00020 00021 Direct correspondence concerning WCSLIB to mark@calabretta.id.au 00022 00023 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO. 00024 http://www.atnf.csiro.au/people/Mark.Calabretta 00025 $Id: wcsprintf.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * WCSLIB 4.17 - C routines that implement the FITS World Coordinate System 00029 * (WCS) standard. 00030 * 00031 * Summary of the wcsprintf routines 00032 * --------------------------------- 00033 * These routines allow diagnostic output from celprt(), linprt(), prjprt(), 00034 * spcprt(), tabprt(), wcsprt(), and wcserr_prt() to be redirected to a file or 00035 * captured in a string buffer. Those routines all use wcsprintf() for output. 00036 * Likewise wcsfprintf() is used by wcsbth() and wcspih(). Both functions may 00037 * be used by application programmers to have other output go to the same 00038 * place. 00039 * 00040 * 00041 * wcsprintf() - Print function used by WCSLIB diagnostic routines 00042 * --------------------------------------------------------------- 00043 * wcsprintf() is used by celprt(), linprt(), prjprt(), spcprt(), tabprt(), 00044 * wcsprt(), and wcserr_prt() for diagnostic output which by default goes to 00045 * stdout. However, it may be redirected to a file or string buffer via 00046 * wcsprintf_set(). 00047 * 00048 * Given: 00049 * format char* Format string, passed to one of the printf(3) family 00050 * of stdio library functions. 00051 * 00052 * ... mixed Argument list matching format, as per printf(3). 00053 * 00054 * Function return value: 00055 * int Number of bytes written. 00056 * 00057 * 00058 * wcsfprintf() - Print function used by WCSLIB diagnostic routines 00059 * ---------------------------------------------------------------- 00060 * wcsfprintf() is used by wcsbth(), and wcspih() for diagnostic output which 00061 * they send to stderr. However, it may be redirected to a file or string 00062 * buffer via wcsprintf_set(). 00063 * 00064 * Given: 00065 * stream FILE* The output stream if not overridden by a call to 00066 * wcsprintf_set(). 00067 * 00068 * format char* Format string, passed to one of the printf(3) family 00069 * of stdio library functions. 00070 * 00071 * ... mixed Argument list matching format, as per printf(3). 00072 * 00073 * Function return value: 00074 * int Number of bytes written. 00075 * 00076 * 00077 * wcsprintf_set() - Set output disposition for wcsprintf() and wcsfprintf() 00078 * ------------------------------------------------------------------------- 00079 * wcsprintf_set() sets the output disposition for wcsprintf() which is used by 00080 * the celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and 00081 * wcserr_prt() routines, and for wcsfprintf() which is used by wcsbth() and 00082 * wcspih(). 00083 * 00084 * Given: 00085 * wcsout FILE* Pointer to an output stream that has been opened for 00086 * writing, e.g. by the fopen() stdio library function, 00087 * or one of the predefined stdio output streams - stdout 00088 * and stderr. If zero (NULL), output is written to an 00089 * internally-allocated string buffer, the address of 00090 * which may be obtained by wcsprintf_buf(). 00091 * 00092 * Function return value: 00093 * int Status return value: 00094 * 0: Success. 00095 * 00096 * 00097 * wcsprintf_buf() - Get the address of the internal string buffer 00098 * --------------------------------------------------------------- 00099 * wcsprintf_buf() returns the address of the internal string buffer created 00100 * when wcsprintf_set() is invoked with its FILE* argument set to zero. 00101 * 00102 * Function return value: 00103 * const char * 00104 * Address of the internal string buffer. The user may 00105 * free this buffer by calling wcsprintf_set() with a 00106 * valid FILE*, e.g. stdout. The free() stdlib library 00107 * function must NOT be invoked on this const pointer. 00108 * 00109 * 00110 * WCSPRINTF_PTR() macro - Print addresses in a consistent way 00111 * ----------------------------------------------------------- 00112 * WCSPRINTF_PTR() is a preprocessor macro used to print addresses in a 00113 * consistent way. 00114 * 00115 * On some systems the "%p" format descriptor renders a NULL pointer as the 00116 * string "0x0". On others, however, it produces "0" or even "(nil)". On 00117 * some systems a non-zero address is prefixed with "0x", on others, not. 00118 * 00119 * The WCSPRINTF_PTR() macro ensures that a NULL pointer is always rendered as 00120 * "0x0" and that non-zero addresses are prefixed with "0x" thus providing 00121 * consistency, for example, for comparing the output of test programs. 00122 * 00123 *===========================================================================*/ 00124 00125 #ifndef WCSLIB_WCSPRINTF 00126 #define WCSLIB_WCSPRINTF 00127 00128 #include <stdio.h> 00129 00130 #ifdef __cplusplus 00131 extern "C" { 00132 #endif 00133 00134 #define WCSPRINTF_PTR(str1, ptr, str2) \ 00135 if (ptr) { \ 00136 wcsprintf("%s%#lx%s", (str1), (unsigned long)(ptr), (str2)); \ 00137 } else { \ 00138 wcsprintf("%s0x0%s", (str1), (str2)); \ 00139 } 00140 00141 int wcsprintf_set(FILE *wcsout); 00142 int wcsprintf(const char *format, ...); 00143 int wcsfprintf(FILE *stream, const char *format, ...); 00144 const char *wcsprintf_buf(void); 00145 00146 #ifdef __cplusplus 00147 } 00148 #endif 00149 00150 #endif /* WCSLIB_WCSPRINTF */