printf.h

Go to the documentation of this file.
00001 // Copyright (C) 2006-2007 Benedikt Böhm <hollow@gentoo.org>
00002 //
00003 // This program is free software; you can redistribute it and/or
00004 // modify it under the terms of the GNU General Public License
00005 // as published by the Free Software Foundation; either version 2
00006 // of the License, or (at your option) any later version.
00007 //
00008 // This program is distributed in the hope that it will be useful,
00009 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00011 // GNU General Public License for more details.
00012 //
00013 // You should have received a copy of the GNU General Public License
00014 // along with this program; if not, write to the Free Software
00015 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
00016 
00017 /*!
00018  * @defgroup printf Formatted output conversion
00019  *
00020  * The  functions in the printf() family produce output according to a format as
00021  * described below.
00022  *
00023  * The functions printf() and vprintf() write output to stdout, the standard
00024  * output stream; dprintf() and vdprintf() write output to the file descriptor
00025  * fd; asprintf() and vasprintf() allocate a string long enough to hold the
00026  * output; snprintf() and vsnprintf() write to the character string str.
00027  *
00028  * The functions vprintf(), vdprintf(), vasprintf() and vsnprintf() are
00029  * equivalent to the functions printf(), dprintf(), asprintf() and snprintf(),
00030  * respectively, except that they are called with a va_list instead  of a
00031  * variable number of arguments. These functions do not call the va_end macro.
00032  * Consequently, the value of ap is undefined after the call. The application
00033  * should call va_end(ap) itself afterwards.
00034  *
00035  * @section format Format of the format string
00036  *
00037  * The format string is composed of zero or more directives: ordinary characters
00038  * (not %), which are copied unchanged to the output stream; and conversion
00039  * specifications, each of which results in fetching zero or more subsequent
00040  * arguments.  Each conversion specification is introduced by the character %,
00041  * and ends with a conversion specifier. In between there may be (in this order)
00042  * zero or more flags, an optional minimum field width, an optional precision
00043  * and an optional length modifier.
00044  *
00045  * @subsection flags The flag characters
00046  *
00047  * The character % is followed by zero or more of the following flags:
00048  *
00049  * - #<br>
00050  *   The value should be converted to an ``alternate form''. For o conversions,
00051  *   the first character of the output string is made zero (by prefixing a 0 if
00052  *   it was not zero already). For x conversions, the result has the
00053  *   string `0x' prepended to it. For other conversions, the result is
00054  *   undefined.
00055  * - 0<br>
00056  *   The value should be zero padded. For d, i, o, u, x, and f conversions, the
00057  *   converted value is padded on the left with zeros rather than blanks. If the
00058  *   0 and - flags both appear, the 0 flag is ignored. If a precision is given
00059  *   with a numeric conversion (d, i, o, u, x, and X), the 0 flag is ignored.
00060  *   For other conversions, the behavior is undefined.
00061  * - -<br>
00062  *   The converted value is to be left adjusted on the field boundary. (The
00063  *   default is right justification.) Except for n conversions, the converted
00064  *   value is padded on the right with blanks, rather than on the left with
00065  *   blanks or zeros. A - overrides a 0 if both are given.
00066  * - ' '<br>
00067  *   (a space) A blank should be left before a positive number (or empty string)
00068  *   produced by a signed conversion.
00069  * - +<br>
00070  *   A sign (+ or -) should always be placed before a number produced by a
00071  *   signed conversion. By default a sign is used only for negative numbers.
00072  *   A + overrides a space if both are used.
00073  *
00074  * @subsection width The field width
00075  *
00076  * An optional decimal digit string (with non-zero first digit) specifying a
00077  * minimum field width. If the converted value has fewer characters than the
00078  * field width, it will be padded with spaces on the left (or right, if the
00079  * left-adjustment flag has been given). Instead of a decimal digit string one
00080  * may write `*' to specify that the field width is given in the next argument,
00081  * which must be of type int. A negative field width is taken as a `-' flag
00082  * followed by a positive field width. In no case does a non-existent or small
00083  * field width cause truncation of a field; if the result of a conversion is
00084  * wider than the field width, the field is expanded to contain the conversion
00085  * result.
00086  *
00087  * @subsection length The length modifier
00088  *
00089  * Here, `integer conversion' stands for d, i, o, u, or x conversion.
00090  *
00091  * - hh<br>
00092  *   A following integer conversion corresponds to a signed char or unsigned
00093  *   char argument, or a following n conversion corresponds to a pointer to a
00094  *   signed char argument.
00095  * - h<br>
00096  *   A following integer conversion corresponds to a short int or unsigned short
00097  *   int argument, or a following n conversion corresponds to a pointer to a
00098  *   short int argument.
00099  * - l<br>
00100  *   (ell) A following integer conversion corresponds to a long int or unsigned
00101  *    long int argument.
00102  * - ll<br>
00103  *   (ell-ell). A following integer conversion corresponds to a long long int or
00104  *   unsigned long long int argument.
00105  *
00106  * Note however that internally, hh, h, and l are handled as long int, ll as
00107  * long long int, respectively.
00108  *
00109  * @subsection conversion The conversion specifier
00110  *
00111  * A character that specifies the type of conversion to be applied. The
00112  * conversion specifiers and their meanings are:
00113  *
00114  * - d,i<br>
00115  *   The int argument is converted to signed decimal notation. The precision, if
00116  *   any, gives the minimum number of digits that must appear; if the converted
00117  *   value requires fewer digits, it is padded on the left with zeros. The
00118  *   default precision is 1. When 0 is printed with an explicit precision 0,
00119  *   the output is empty.
00120  * - o,u,x,X<br>
00121  *   The unsigned int argument is converted to unsigned octal (o), unsigned
00122  *   decimal (u), or unsigned hexadecimal (x) notation. The letters abcdef are
00123  *   used for x conversions. The precision, if any, gives the minimum number of
00124  *   digits that must appear; if the converted value requires fewer digits, it
00125  *   is padded on the left with zeros. The default precision is 1. When 0 is
00126  *   printed with an explicit precision 0, the output is empty.
00127  * - c<br>
00128  *   The int argument is converted to an unsigned char, and the resulting
00129  *   character is written.
00130  * - s<br>
00131  *   The const char * argument is expected to be a pointer to an array of
00132  *   character type (pointer to a string). Characters from the array are written
00133  *   up to (but not including) a terminating null byte ('\\0'); if a precision is
00134  *   specified, no more than the number specified are written. If a precision is
00135  *   given, no null byte need be present; if the precision is not specified, or
00136  *   is greater than the size of the array, the array must contain a terminating
00137  *   null byte.
00138  * - p<br>
00139  *   The void * pointer argument is printed in hexadecimal.
00140  * - n<br>
00141  *   The number of characters written so far is stored into the integer
00142  *   indicated by the int * pointer argument. No argument is converted.
00143  * - %<br>
00144  *   A `%' is written. No argument is converted. The complete conversion
00145  *   specification is `%%'.
00146  *
00147  * @section conform Note on conformance
00148  *
00149  * This printf implementation is not fully C99 or SUS compliant, though most
00150  * common features are implemented in a completely self-contained way, to make
00151  * integration within other applications as easy as possible.
00152  *
00153  * @see fmt
00154  *
00155  * @{
00156  */
00157 
00158 #ifndef _LUCID_PRINTF_H
00159 #define _LUCID_PRINTF_H
00160 
00161 #include <stdarg.h>
00162 
00163 /*!
00164  * @brief write conversion to string using va_list
00165  *
00166  * @param[out] str  buffer to store conversion
00167  * @param[in]  size size of str
00168  * @param[in]  fmt  format string
00169  * @param[in]  ap   variable number of arguments
00170  *
00171  * @return number of bytes (that would have been) written
00172  *
00173  * @note Every conversion happens in this functions. All other printf functions
00174  *       are just convenient wrappers.
00175  */
00176 int _lucid_vsnprintf(char *str, int size, const char *fmt, va_list ap);
00177 
00178 /*!
00179  * @brief write conversion to string using variable number of arguments
00180  *
00181  * @param[out] str  buffer to store conversion
00182  * @param[in]  size size of str
00183  * @param[in]  fmt  format string
00184  * @param[in]  ...  variable number of arguments
00185  *
00186  * @return number of bytes (that would have been) written
00187  */
00188 int _lucid_snprintf (char *str, int size, const char *fmt, /*args*/ ...);
00189 
00190 /*!
00191  * @brief write conversion to allocated string using va_list
00192  *
00193  * @param[out] ptr  pointer to string to store conversion
00194  * @param[in]  fmt  format string
00195  * @param[in]  ap   variable number of arguments
00196  *
00197  * @return number of bytes (that would have been) written
00198  *
00199  * @see malloc(3)
00200  * @see free(3)
00201  */
00202 int _lucid_vasprintf(char **ptr, const char *fmt, va_list ap);
00203 
00204 /*!
00205  * @brief write conversion to allocated string using variable number of arguments
00206  *
00207  * @param[out] ptr  pointer to string to store conversion
00208  * @param[in]  fmt  format string
00209  * @param[in]  ...  variable number of arguments
00210  *
00211  * @return number of bytes (that would have been) written
00212  *
00213  * @see malloc(3)
00214  * @see free(3)
00215  */
00216 int _lucid_asprintf(char **ptr, const char *fmt, /*args*/ ...);
00217 
00218 /*!
00219  * @brief write conversion to file descriptor using va_list
00220  *
00221  * @param[in] fd   open file descriptor
00222  * @param[in] fmt  format string
00223  * @param[in] ap   variable number of arguments
00224  *
00225  * @return number of bytes (that would have been) written
00226  */
00227 int _lucid_vdprintf(int fd, const char *fmt, va_list ap);
00228 
00229 /*!
00230  * @brief write conversion to file descriptor using variable number of arguments
00231  *
00232  * @param[in] fd   open file descriptor
00233  * @param[in] fmt  format string
00234  * @param[in] ...  variable number of arguments
00235  *
00236  * @return number of bytes (that would have been) written
00237  */
00238 int _lucid_dprintf(int fd, const char *fmt, /*args*/ ...);
00239 
00240 /*!
00241  * @brief write conversion to stdout using va_list
00242  *
00243  * @param[in] fmt  format string
00244  * @param[in] ap   variable number of arguments
00245  *
00246  * @return number of bytes (that would have been) written
00247  */
00248 int _lucid_vprintf(const char *fmt, va_list ap);
00249 
00250 /*!
00251  * @brief write conversion to stdout using variable number of arguments
00252  *
00253  * @param[in] fmt  format string
00254  * @param[in] ...  variable number of arguments
00255  *
00256  * @return number of bytes (that would have been) written
00257  */
00258 int _lucid_printf(const char *fmt, /*args*/ ...);
00259 
00260 #ifdef _LUCID_PRINTF_MACROS
00261 #define vsnprintf _lucid_vsnprintf
00262 #define snprintf  _lucid_snprintf
00263 #define vasprintf _lucid_vasprintf
00264 #define asprintf  _lucid_asprintf
00265 #define vdprintf  _lucid_vdprintf
00266 #define dprintf   _lucid_dprintf
00267 #define vprintf   _lucid_vprintf
00268 #define printf    _lucid_printf
00269 #endif
00270 
00271 #endif
00272 
00273 /*! @} printf */

Generated on Tue Jun 19 20:38:26 2007 for lucid by  doxygen 1.5.2