- Main Page
- Related Pages
- Data Structures
- Files

# wcsprintf.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.13 - 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   Correspondence concerning WCSLIB may be directed to:
    00022     Internet email: mcalabre@atnf.csiro.au
    00023     Postal address: Dr. Mark Calabretta
    00024                     Australia Telescope National Facility, CSIRO
    00025                     PO Box 76
    00026                     Epping NSW 1710
    00027                     AUSTRALIA
    00028
    00029   Author: Mark Calabretta, Australia Telescope National Facility
    00030   http://www.atnf.csiro.au/~mcalabre/index.html
    00031   $Id: wcsprintf.h,v 4.13.1.1 2012/03/14 07:40:37 cal103 Exp cal103 $
    00032 *=============================================================================
    00033 *
    00034 * WCSLIB 4.13 - C routines that implement the FITS World Coordinate System
    00035 * (WCS) standard.
    00036 *
    00037 * Summary of the wcsprintf routines
    00038 * ---------------------------------
    00039 * These routines allow diagnostic output from celprt(), linprt(), prjprt(),
    00040 * spcprt(), tabprt(), wcsprt(), and wcserr_prt() to be redirected to a file or
    00041 * captured in a string buffer.  Those routines all use wcsprintf() for output.
    00042 *
    00043 *
    00044 * wcsprintf() - Print function used by WCSLIB diagnostic routines
    00045 * ---------------------------------------------------------------
    00046 * wcsprintf() is used by the celprt(), linprt(), prjprt(), spcprt(), tabprt(),
    00047 * wcsprt(), and wcserr_prt() routines.  Its output may be redirected to a file
    00048 * or string buffer via wcsprintf_set().  By default output goes to stdout.
    00049 *
    00050 * Given:
    00051 *   format    char*     Format string, passed to one of the printf(3) family
    00052 *                       of stdio library functions.
    00053 *
    00054 *   ...       mixed     Argument list matching format, as per printf(3).
    00055 *
    00056 * Function return value:
    00057 *             int       Number of bytes written.
    00058 *
    00059 *
    00060 * wcsprintf_set() - Set output disposition for wcsprintf()
    00061 * --------------------------------------------------------
    00062 * wcsprintf_set() sets the output disposition for wcsprintf() which is used by
    00063 * the celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and
    00064 * wcserr_prt() routines.
    00065 *
    00066 * Output goes to stdout by default if wcsprintf_set() has not been called.
    00067 *
    00068 * Given:
    00069 *   wcsout    FILE*     Pointer to an output stream that has been opened for
    00070 *                       writing, e.g. by the fopen() stdio library function,
    00071 *                       or one of the predefined stdio output streams - stdout
    00072 *                       and stderr.  If zero (NULL), output is written to an
    00073 *                       internally-allocated string buffer, the address of
    00074 *                       which may be obtained by wcsprintf_buf().
    00075 *
    00076 * Function return value:
    00077 *             int       Status return value:
    00078 *                         0: Success.
    00079 *
    00080 *
    00081 * wcsprintf_buf() - Get the address of the internal string buffer
    00082 * ---------------------------------------------------------------
    00083 * wcsprintf_buf() returns the address of the internal string buffer created
    00084 * when wcsprintf_set() is invoked with its FILE* argument set to zero.
    00085 *
    00086 * Function return value:
    00087 *             const char *
    00088 *                       Address of the internal string buffer.  The user may
    00089 *                       free this buffer by calling wcsprintf_set() with a
    00090 *                       valid FILE*, e.g. stdout.  The free() stdlib library
    00091 *                       function must NOT be invoked on this const pointer.
    00092 *
    00093 *
    00094 * WCSPRINTF_PTR() macro - Print addresses in a consistent way
    00095 * -----------------------------------------------------------
    00096 * WCSPRINTF_PTR() is a preprocessor macro used to print addresses in a
    00097 * consistent way.
    00098 *
    00099 * On some systems the "%p" format descriptor renders a NULL pointer as the
    00100 * string "0x0".  On others, however, it produces "0" or even "(nil)".  On
    00101 * some systems a non-zero address is prefixed with "0x", on others, not.
    00102 *
    00103 * The WCSPRINTF_PTR() macro ensures that a NULL pointer is always rendered as
    00104 * "0x0" and that non-zero addresses are prefixed with "0x" thus providing
    00105 * consistency, for example, for comparing the output of test programs.
    00106 *
    00107 *===========================================================================*/
    00108
    00109 #ifndef WCSLIB_WCSPRINTF
    00110 #define WCSLIB_WCSPRINTF
    00111
    00112 #ifdef __cplusplus
    00113 extern "C" {
    00114 #endif
    00115
    00116 #define WCSPRINTF_PTR(str1, ptr, str2) \
    00117   if (ptr) { \
    00118     wcsprintf("%s%#lx%s", (str1), (unsigned long)(ptr), (str2)); \
    00119   } else { \
    00120     wcsprintf("%s0x0%s", (str1), (str2)); \
    00121   }
    00122
    00123 int wcsprintf_set(FILE *wcsout);
    00124 int wcsprintf(const char *format, ...);
    00125 const char *wcsprintf_buf(void);
    00126
    00127 #ifdef __cplusplus
    00128 }
    00129 #endif
    00130
    00131 #endif /* WCSLIB_WCSPRINTF */