WCSLIB 4.17: wcsprintf.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# wcsprintf.h

Go to the documentation of this file.

    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 */