00001 /*============================================================================ 00002 00003 WCSLIB 4.15 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, 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.15 2012/09/26 14:26:05 cal103 Exp $ 00026 *============================================================================= 00027 * 00028 * WCSLIB 4.15 - 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 * 00037 * 00038 * wcsprintf() - Print function used by WCSLIB diagnostic routines 00039 * --------------------------------------------------------------- 00040 * wcsprintf() is used by the celprt(), linprt(), prjprt(), spcprt(), tabprt(), 00041 * wcsprt(), and wcserr_prt() routines. Its output may be redirected to a file 00042 * or string buffer via wcsprintf_set(). By default output goes to stdout. 00043 * 00044 * Given: 00045 * format char* Format string, passed to one of the printf(3) family 00046 * of stdio library functions. 00047 * 00048 * ... mixed Argument list matching format, as per printf(3). 00049 * 00050 * Function return value: 00051 * int Number of bytes written. 00052 * 00053 * 00054 * wcsprintf_set() - Set output disposition for wcsprintf() 00055 * -------------------------------------------------------- 00056 * wcsprintf_set() sets the output disposition for wcsprintf() which is used by 00057 * the celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and 00058 * wcserr_prt() routines. 00059 * 00060 * Output goes to stdout by default if wcsprintf_set() has not been called. 00061 * 00062 * Given: 00063 * wcsout FILE* Pointer to an output stream that has been opened for 00064 * writing, e.g. by the fopen() stdio library function, 00065 * or one of the predefined stdio output streams - stdout 00066 * and stderr. If zero (NULL), output is written to an 00067 * internally-allocated string buffer, the address of 00068 * which may be obtained by wcsprintf_buf(). 00069 * 00070 * Function return value: 00071 * int Status return value: 00072 * 0: Success. 00073 * 00074 * 00075 * wcsprintf_buf() - Get the address of the internal string buffer 00076 * --------------------------------------------------------------- 00077 * wcsprintf_buf() returns the address of the internal string buffer created 00078 * when wcsprintf_set() is invoked with its FILE* argument set to zero. 00079 * 00080 * Function return value: 00081 * const char * 00082 * Address of the internal string buffer. The user may 00083 * free this buffer by calling wcsprintf_set() with a 00084 * valid FILE*, e.g. stdout. The free() stdlib library 00085 * function must NOT be invoked on this const pointer. 00086 * 00087 * 00088 * WCSPRINTF_PTR() macro - Print addresses in a consistent way 00089 * ----------------------------------------------------------- 00090 * WCSPRINTF_PTR() is a preprocessor macro used to print addresses in a 00091 * consistent way. 00092 * 00093 * On some systems the "%p" format descriptor renders a NULL pointer as the 00094 * string "0x0". On others, however, it produces "0" or even "(nil)". On 00095 * some systems a non-zero address is prefixed with "0x", on others, not. 00096 * 00097 * The WCSPRINTF_PTR() macro ensures that a NULL pointer is always rendered as 00098 * "0x0" and that non-zero addresses are prefixed with "0x" thus providing 00099 * consistency, for example, for comparing the output of test programs. 00100 * 00101 *===========================================================================*/ 00102 00103 #ifndef WCSLIB_WCSPRINTF 00104 #define WCSLIB_WCSPRINTF 00105 00106 #ifdef __cplusplus 00107 extern "C" { 00108 #endif 00109 00110 #define WCSPRINTF_PTR(str1, ptr, str2) \ 00111 if (ptr) { \ 00112 wcsprintf("%s%#lx%s", (str1), (unsigned long)(ptr), (str2)); \ 00113 } else { \ 00114 wcsprintf("%s0x0%s", (str1), (str2)); \ 00115 } 00116 00117 int wcsprintf_set(FILE *wcsout); 00118 int wcsprintf(const char *format, ...); 00119 const char *wcsprintf_buf(void); 00120 00121 #ifdef __cplusplus 00122 } 00123 #endif 00124 00125 #endif /* WCSLIB_WCSPRINTF */