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