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

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