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

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