printf.h

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

Generated on Sun Dec 3 17:45:53 2006 for lucid by  doxygen 1.5.1