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 scanf Formatted input conversion 00019 * 00020 * The scanf() family of functions scans input according to format as described 00021 * below. This format may contain conversion specifications; the results from 00022 * such conversions, if any, are stored in the locations pointed to by the 00023 * pointer arguments that follow format. Each pointer argument must be of a type 00024 * that is appropriate for the value returned by the corresponding conversion 00025 * specification. 00026 * 00027 * If the number of conversion specifications in format exceeds the number of 00028 * pointer arguments, the results are undefined. If the number of pointer 00029 * arguments exceeds the number of conversion specifications, then the excess 00030 * pointer arguments are evaluated, but are otherwise ignored. 00031 * 00032 * The format string consists of a sequence of directives which describe how to 00033 * process the sequence of input characters. If processing of a directive fails, 00034 * no further input is read, and scanf() returns. A "failure" can be either of 00035 * the following: input failure, meaning that input characters were unavailable, 00036 * or matching failure, meaning that the input was inappropriate (see below). 00037 * 00038 * A directive is one of the following: 00039 * 00040 * - A sequence of white-space characters (space, tab, newline, etc; see 00041 * isspace(3)). This directive matches any amount of white space, including 00042 * none, in the input. 00043 * 00044 * - An ordinary character (i.e., one other than white space or '%'). This 00045 * character must exactly match the next character of input. 00046 * 00047 * - A conversion specification, which commences with a '%' (percent) character. 00048 * A sequence of characters from the input is converted according to this 00049 * specification, and the result is placed in the corresponding pointer 00050 * argument. If the next item of input does not match the the conversion 00051 * specification, the conversion fails — this is a matching failure. 00052 * 00053 * @section format Format of the format string 00054 * 00055 * Each conversion specification in format begins with either the character 00056 * '%' followed by: 00057 * 00058 * - An optional '*' assignment-suppression character: scanf() reads input as 00059 * directed by the conversion specification, but discards the input. No 00060 * corresponding pointer argument is required, and this specification is not 00061 * included in the count of successful assignments returned by scanf(). 00062 * 00063 * - An optional decimal integer which specifies the maximum field width. 00064 * Reading of characters stops either when this maximum is reached or when a 00065 * non-matching character is found, whichever happens first. Most conversions 00066 * discard initial whitespace characters (the exceptions are noted below), 00067 * and these discarded characters don't count towards the maximum field 00068 * width. String input conversions store a null terminator ('\\0') to mark the 00069 * end of the input; the maximum field width does not include this 00070 * terminator. 00071 * 00072 * - An optional type modifier character. For example, the l type modifier is 00073 * used with integer conversions such as %d to specify that the 00074 * corresponding pointer argument refers to a long int rather than a pointer 00075 * to an int. 00076 * 00077 * - A conversion specifier that specifies the type of input conversion to be 00078 * performed. 00079 * 00080 * @subsection conversions Conversions 00081 * 00082 * The following type modifier characters can appear in a conversion 00083 * specification: 00084 * 00085 * - hh<br> 00086 * A following integer conversion corresponds to a signed char or unsigned 00087 * char argument, or a following n conversion corresponds to a pointer to a 00088 * signed char argument. 00089 * - h<br> 00090 * A following integer conversion corresponds to a short int or unsigned short 00091 * int argument, or a following n conversion corresponds to a pointer to a 00092 * short int argument. 00093 * - l<br> 00094 * (ell) A following integer conversion corresponds to a long int or unsigned 00095 * long int argument. 00096 * - ll<br> 00097 * (ell-ell). A following integer conversion corresponds to a long long int or 00098 * unsigned long long int argument. 00099 * 00100 * The following conversion specifiers are available: 00101 * 00102 * - %<br> 00103 * Matches a literal '%'. That is, %% in the format string matches a single 00104 * input '%' character. No conversion is done, and assignment does not occur. 00105 * - d<br> 00106 * Matches an optionally signed decimal integer; the next pointer must be a 00107 * pointer to int. 00108 * - i<br> 00109 * Matches an optionally signed integer; the next pointer must be a pointer 00110 * to int. The integer is read in base 16 if it begins with 0x or 0X, in base 00111 * 8 if it begins with 0, and in base 10 otherwise. Only characters that 00112 * correspond to the base are used. 00113 * - o<br> 00114 * Matches an unsigned octal integer; the next pointer must be a pointer to 00115 * unsigned int. 00116 * - u<br> 00117 * Matches an unsigned decimal integer; the next pointer must be a pointer to 00118 * unsigned int. 00119 * - x,X<br> 00120 * Matches an unsigned hexadecimal integer; the next pointer must be a 00121 * pointer to unsigned int. 00122 * - s<br> 00123 * Matches a sequence of non-white-space characters; the next pointer must be 00124 * a pointer to character array that is long enough to hold the input 00125 * sequence and the terminating null character ('\\0'), which is added 00126 * automatically. The input string stops at white space or at the maximum 00127 * field width, whichever occurs first. 00128 * - c<br> 00129 * Matches a sequence of characters whose length is specified by the maximum 00130 * field width (default 1); the next pointer must be a pointer to char, and 00131 * there must be enough room for all the characters (no terminating null byte 00132 * is added). The usual skip of leading white space is suppressed. To skip 00133 * white space first, use an explicit space in the format. 00134 * - p<br> 00135 * Matches a pointer value (as printed by %p in printf(3); the next pointer 00136 * must be a pointer to a pointer to void. 00137 * - n<br> 00138 * Nothing is expected; instead, the number of characters consumed thus far 00139 * from the input is stored through the next pointer, which must be a pointer 00140 * to int. This is not a conversion, although it can be suppressed with the * 00141 * assignment-suppression character. 00142 * 00143 * @{ 00144 */ 00145 00146 #ifndef _LUCID_SCANF_H 00147 #define _LUCID_SCANF_H 00148 00149 #include <stdarg.h> 00150 00151 /*! 00152 * @brief read conversion from string using va_list 00153 * 00154 * @param[in] str source string 00155 * @param[in] fmt format string 00156 * @param[out] ap variable number of arguments 00157 * 00158 * @return Number of converted arguments 00159 * 00160 * @note Every conversion happens in this functions. All other scanf functions 00161 * are just convenient wrappers. 00162 */ 00163 int _lucid_vsscanf(const char *str, const char *fmt, va_list ap); 00164 00165 /*! 00166 * @brief read conversion from string using variable number of arguments 00167 * 00168 * @param[in] str source string 00169 * @param[in] fmt format string 00170 * @param[out] ... variable number of arguments 00171 * 00172 * @return Number of converted arguments 00173 */ 00174 int _lucid_sscanf(const char *str, const char *fmt, /*args*/ ...); 00175 00176 #ifdef _LUCID_SCANF_MACROS 00177 #define vsscanf _lucid_vsscanf 00178 #define sscanf _lucid_sscanf 00179 #endif 00180 00181 #endif 00182 00183 /*! @} printf */