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