X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/1c15e88899094343f75aeba04122cd96a96b428e..af359dea2e5ab3e937b62107ecd6a51d78189ed7:/usr/src/lib/libc/stdio/scanf.3

diff --git a/usr/src/lib/libc/stdio/scanf.3 b/usr/src/lib/libc/stdio/scanf.3
index 00c5d8d7bd..ff88e476b0 100644
--- a/usr/src/lib/libc/stdio/scanf.3
+++ b/usr/src/lib/libc/stdio/scanf.3
@@ -1,257 +1,420 @@
-.\"	@(#)scanf.3	6.2 (Berkeley) 4/1/89
+.\" Copyright (c) 1990, 1991 The Regents of the University of California.
+.\" All rights reserved.
 .\"
-.TH SCANF 3  "April 1, 1989"
-.AT 3
-.SH NAME
-scanf, fscanf, sscanf \- formatted input conversion
-.SH SYNOPSIS
-.B #include <stdio.h>
-.PP
-.B scanf(format
-[ , pointer ] . . .
-.B )
-.br
-.B char *format;
-.PP
-.B fscanf(stream, format
-[ , pointer ] . . .
-.B )
-.br
-.SM
-.B FILE
-.B *stream;
-.br
-.B char *format;
-.PP
-.B sscanf(s, format
-[ , pointer ] . . .
-.B )
-.br
-.B char *s, *format;
-.SH DESCRIPTION
-.I Scanf
-reads from the standard input stream
-.BR stdin .
-.I Fscanf
-reads from the named input
-.IR stream .
-.I Sscanf
-reads from the character string
-.IR s .
-Each function reads characters, interprets
-them according to a format, and stores the results in its arguments.
-Each expects as arguments
-a control string
-.IR format ,
-described below,
-and a set of
-.I pointer
-arguments
-indicating where the converted input should be stored.
-.PP
+.\" This code is derived from software contributed to Berkeley by
+.\" Chris Torek and the American National Standards Committee X3,
+.\" on Information Processing Systems.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by the University of
+.\"	California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     @(#)scanf.3	6.11 (Berkeley) 6/29/91
+.\"
+.Dd June 29, 1991
+.Dt SCANF 3
+.Os
+.Sh NAME
+.Nm scanf ,
+.Nm fscanf ,
+.Nm sscanf ,
+.Nm vscanf ,
+.Nm vsscanf ,
+.Nm vfscanf
+.Nd input format conversion
+.Sh SYNOPSIS
+.Fd #include <stdio.h>
+.Ft int
+.Fn scanf "const char *format" ...
+.Ft int
+.Fn fscanf "FILE *stream" "const char *format" ...
+.Ft int
+.Fn sscanf "const char *str" "const char *format" ...
+.Fd #include <stdarg.h>
+.Ft int
+.Fn vscanf "const char *format" "va_list ap"
+.Ft int
+.Fn vsscanf "const char *str" "const char *format" "va_list ap"
+.Ft int
+.Fn vfscanf "FILE *stream" "const char *format" "va_list ap"
+.Sh DESCRIPTION
+The
+.Fn scanf
+family of functions scans input according to a
+.Fa format
+as described below.
+This format may contain
+.Em conversion specifiers ;
+the results from such conversions, if any,
+are stored through the
+.Em pointer
+arguments.
 The
-control string
-usually contains
-conversion specifications, which are used to direct interpretation
-of input sequences.
-The control string may contain:
-.TP 4
-1.
-Blanks, tabs or newlines,
-which match optional white space in the input.
-.TP 4
-2.
-An ordinary character (not %) which must match
-the next character of the input stream.
-.TP 4
-3.
-Conversion specifications, consisting of the
+.Fn scanf
+function
+reads input from the standard input stream
+.Em stdin ,
+.Fn fscanf
+reads input from the stream pointer
+.Fa stream ,
+and
+.Fn sscanf
+reads its input from the character string pointed to by
+.Fa str .
+The
+.Fn vfscanf
+function
+is analogous to
+.Xr vfprintf 3
+and reads input from the stream pointer
+.Fa stream
+using a variable argument list of pointers (see
+.Xr stdarg 3 ) .
+The
+.Fn vscanf
+function scans a variable argument list from the standard input and
+the
+.Fn vsscanf
+function scans it from a string;
+these are analogous to
+the
+.Fn vprintf
+and
+.Fn vsprintf
+functions respectively.
+Each successive
+.Em pointer
+argument must correspond properly with
+each successive conversion specifier
+(but see `suppression' below).
+All conversions are introduced by the
+.Cm %
+(percent sign) character.
+The
+.Fa format
+string
+may also contain other characters.
+White space (such as blanks, tabs, or newlines) in the
+.Fa format
+string match any amount of white space, including none, in the input.
+Everything else
+matches only itself.
+Scanning stops
+when an input character does not match such a format character.
+Scanning also stops
+when an input conversion cannot be made (see below).
+.Sh CONVERSIONS
+Following the
+.Cm %
+character introducing a conversion
+there may be a number of
+.Em flag
+characters, as follows:
+.Bl -tag -width indent
+.It Cm *
+Suppresses assignment.
+The conversion that follows occurs as usual, but no pointer is used;
+the result of the conversion is simply discarded.
+.It Cm h
+Indicates that the conversion will be one of
+.Cm dioux
+or
+.Cm n
+and the next pointer is a pointer to a
+.Em short  int
+(rather than
+.Em int ) .
+.It Cm l
+Indicates either that the conversion will be one of
+.Cm dioux
+or
+.Cm n
+and the next pointer is a pointer to a
+.Em long  int
+(rather than
+.Em int ) ,
+or that the conversion will be one of
+.Cm efg
+and the next pointer is a pointer to
+.Em double
+(rather than
+.Em float ) .
+.It Cm L
+Indicates that the conversion will be
+.Cm efg
+and the next pointer is a pointer to
+.Em long double .
+(This type is not implemented; the
+.Cm L
+flag is currently ignored.)
+.El
+.Pp
+In addition to these flags,
+there may be an optional maximum field width,
+expressed as a decimal integer,
+between the
+.Cm %
+and the conversion.
+If no width is given,
+a default of `infinity' is used (with one exception, below);
+otherwise at most this many characters are scanned
+in processing the conversion.
+Before conversion begins,
+most conversions skip white space;
+this white space is not counted against the field width.
+.Pp
+The following conversions are available:
+.Bl -tag -width XXXX
+.It Cm %
+Matches a literal `%'.
+That is, `%\&%' in the format string
+matches a single input `%' character.
+No conversion is done, and assignment does not occur.
+.It Cm d
+Matches an optionally signed decimal integer;
+the next pointer must be a pointer to
+.Em int .
+.It Cm D
+Equivalent to
+.Xr ld ;
+this exists only for backwards compatibility.
+.It Cm i
+Matches an optionally signed integer;
+the next pointer must be a pointer to
+.Em int .
+The integer is read in base 16 if it begins
+with
+.Ql 0x
+or
+.Ql 0X ,
+in base 8 if it begins with
+.Ql 0 ,
+and in base 10 otherwise.
+Only characters that correspond to the base are used.
+.It Cm o
+Matches an octal integer;
+the next pointer must be a pointer to
+.Em unsigned int .
+.It Cm O
+Equivalent to
+.Xr lo ;
+this exists for backwards compatibility.
+.It Cm u
+Matches an optionally signed decimal integer;
+the next pointer must be a pointer to
+.Em unsigned int .
+.It Cm x
+Matches an optionally a signed hexadecimal integer;
+the next pointer must be a pointer to
+.Em unsigned int .
+.It Cm X
+Equivalent to
+.Cm lx ;
+this violates the
+.St -ansiC ,
+but is backwards compatible with previous
+.Ux
+systems.
+.It Cm f
+Matches an optionally signed floating-point number;
+the next pointer must be a pointer to
+.Em float .
+.It Cm e
+Equivalent to
+.Cm f .
+.It Cm g
+Equivalent to
+.Cm f .
+.It Cm E
+Equivalent to
+.Cm lf ;
+this violates the
+.St -ansiC ,
+but is backwards compatible with previous
+.Ux
+systems.
+.It Cm F
+Equivalent to
+.Cm lf ;
+this exists only for backwards compatibility.
+.It Cm s
+Matches a sequence of non-white-space characters;
+the next pointer must be a pointer to
+.Em char ,
+and the array must be large enough to accept all the sequence and the
+terminating
+.Dv NUL
+character.
+The input string stops at white space
+or at the maximum field width, whichever occurs first.
+.It Cm c
+Matches a sequence of
+.Em width
+count
+characters (default 1);
+the next pointer must be a pointer to
+.Em char ,
+and there must be enough room for all the characters
+(no terminating
+.Dv NUL
+is added).
+The usual skip of leading white space is suppressed.
+To skip white space first, use an explicit space in the format.
+.It Cm \&[
+Matches a nonempty sequence of characters from the specified set
+of accepted characters;
+the next pointer must be a pointer to
+.Em char ,
+and there must be enough room for all the characters in the string,
+plus a terminating
+.Dv NUL
+character.
+The usual skip of leading white space is suppressed.
+The string is to be made up of characters in
+(or not in)
+a particular set;
+the set is defined by the characters between the open bracket
+.Cm [
 character
-.BR % ,
-an optional assignment suppressing character
-.BR * ,
-an optional numerical maximum field width, and a conversion
+and a close bracket
+.Cm ]
 character.
-.PP
-A conversion specification directs the conversion of the
-next input field; the result
-is placed in the variable pointed to by the corresponding argument,
-unless assignment suppression was
-indicated by
-.BR * .
-An input field is defined as a string of non-space characters;
-it extends to the next inappropriate character or until the field
-width, if specified, is exhausted.
-.PP
-The conversion character indicates the interpretation of the
-input field; the corresponding pointer argument must
-usually be of a restricted type.
-The following conversion characters are legal:
-.TP 4
-.B  %
-a single `%' is expected
-in the input at this point;
-no assignment is done.
-.TP 4
-.B  d
-a decimal integer is expected;
-the corresponding argument should be an integer pointer.
-.TP 4
-.B  o
-an octal integer is expected;
-the corresponding argument should be a integer pointer.
-.TP 4
-.B  x
-a hexadecimal integer is expected;
-the corresponding argument should be an integer pointer.
-.ti -0.2i
-.TP 4
-.B  s
-a character string is expected;
-the corresponding argument should be a character pointer
-pointing to an array of characters large enough to accept the
-string and a terminating `\e0', which will be added.
-The input field is terminated by a space character
-or a newline.
-.TP 4
-.B  c
-a character is expected; the
-corresponding argument should be a character pointer.
-The normal skip over space characters is suppressed
-in this case;
-to read the next non-space character, try
-`%1s'.
-If a field width is given, the corresponding argument
-should refer to a character array, and the
-indicated number of characters is read.
-.TP 4
-\z\fBe\v'1'f\v'-1'\fR
-a
-floating point number is expected;
-the next field is converted accordingly and stored through the
-corresponding argument, which should be a pointer to a
-.IR float .
-The input format for
-floating point numbers is
-an optionally signed
-string of digits
-possibly containing a decimal point, followed by an optional
-exponent field consisting of an E or e followed by an optionally signed integer.
-.TP 4
-.B  [
-indicates a string not to be delimited by space characters.
-The left bracket is followed by a set of characters and a right
-bracket; the characters between the brackets define a set
-of characters making up the string.
-If the first character
-is not circumflex (\|^\|), the input field
-is all characters until the first character not in the set between
-the brackets; if the first character
-after the left bracket is ^, the input field is all characters
-until the first character which is in the remaining set of characters
-between the brackets.
-The corresponding argument must point to a character array.
-.PP
-The conversion characters
-.BR d ,
-.B o
+The set
+.Em excludes
+those characters
+if the first character after the open bracket is a circumflex
+.Cm ^ .
+To include a close bracket in the set,
+make it the first character after the open bracket
+or the circumflex;
+any other position will end the set.
+The hyphen character
+.Cm -
+is also special;
+when placed between two other characters,
+it adds all intervening characters to the set.
+To include a hyphen,
+make it the last character before the final close bracket.
+For instance,
+.Ql [^]0-9-]
+means the set `everything except close bracket, zero through nine,
+and hyphen'.
+The string ends with the appearance of a character not in the
+(or, with a circumflex, in) set
+or when the field width runs out.
+.It Cm p
+Matches a pointer value (as printed by
+.Ql %p
+in
+.Xr printf 3 ) ;
+the next pointer must be a pointer to
+.Em void .
+.It Cm n
+Nothing is expected;
+instead, the number of characters consumed thus far from the input
+is stored through the next pointer,
+which must be a pointer to
+.Em int .
+This is
+.Em not
+a conversion, although it can be suppressed with the
+.Cm *
+flag.
+.El
+.Pp
+For backwards compatibility,
+other conversion characters (except
+.Ql \e0 )
+are taken as if they were
+.Ql %d
+or, if uppercase,
+.Ql %ld ,
+and a `conversion' of
+.Ql %\e0
+causes an immediate return of
+.Dv EOF .
+The
+.Cm F
 and
-.B x
-may be capitalized or preceded by
-.B l
-to indicate that a pointer to
-.B long
-rather than to
-.B int
-is in the argument list.
-Similarly, the conversion characters
-.B e
-or
-.B f
-may be capitalized or
-preceded by
-.B l
-to indicate a pointer to 
-.B double
-rather than to 
-.BR float .
-The conversion characters
-.BR d ,
-.B o
+.Cm X
+conversions will be changed in the future
+to conform to the
+.Tn ANSI
+C standard,
+after which they will act like
+.Cm f
 and
-.B x
-may be preceded by
-.B h
-to indicate a pointer to
-.B short
-rather than to
-.BR int .
-.PP
-The
-.I scanf
-functions return the number of successfully matched and assigned input
-items.
-This can be used to decide how many input items were found.
-The constant
-.SM
-.B EOF
-is returned upon end of input; note that this is different
-from 0, which means that no conversion was done;
-if conversion was intended, it was frustrated by an
-inappropriate character in the input.
-.PP
-For example, the call
-.IP "" 10
-int i; float x; char name[50];
-.br
-scanf("%d%f%s", &i, &x, name);
-.PP
-with the input line
-.IP
-25   54.32E\(mi1  thompson
-.PP
-will assign to
-.I i
-the value
-25,
-.I x
-the value 5.432, and
-.I name
-will contain
-.IR `thompson\e0' .
-Or,
-.IP
-int i; float x; char name[50];
-.br
-scanf("%2d%f%*d%[1234567890]", &i, &x, name);
-.PP
-with input
-.IP
-56789 0123 56a72
-.PP
-will assign 56 to
-.IR i ,
-789.0 to
-.IR x ,
-skip `0123',
-and place the string `56\e0' in
-.IR name .
-The next call to
-.I getchar
-will return `a'.
-.SH "SEE ALSO"
-atof(3),
-getc(3),
-printf(3)
-.SH DIAGNOSTICS
-The 
-.I scanf
-functions return
-.SM
-.B EOF
-on end of input,
-and a short count for missing or illegal data items.
-.SH BUGS
-The success of literal matches and suppressed
-assignments is not directly
-determinable.
+.Cm x
+respectively.
+.Pp
+.Sh RETURN VALUES
+These
+functions
+return
+the number of input items assigned, which can be fewer than provided
+for, or even zero, in the event of a matching failure.
+Zero
+indicates that, while there was input available,
+no conversions were assigned;
+typically this is due to an invalid input character,
+such as an alphabetic character for a
+.Ql %d
+conversion.
+The value
+.Dv EOF
+is returned if an input failure occurs before any conversion such as an
+end-of-file occurs. If an error or end-of-file occurs after conversion
+has begun,
+the number of conversions which were successfully completed is returned.
+.Sh SEE ALSO
+.Xr strtol 3 ,
+.Xr strtoul 3 ,
+.Xr getc 3 ,
+.Xr printf 3
+.Sh STANDARDS
+The functions
+.Fn fscanf ,
+.Fn scanf ,
+and
+.Fn sscanf
+conform to
+.St -ansiC .
+.Sh HISTORY
+The functions
+.Fn vscanf ,
+.Fn vsscanf
+and
+.Fn vfscanf
+are new to this release.
+.Sh BUGS
+The current situation with
+.Cm %F
+and
+.Cm %X
+conversions is unfortunate.
+.Pp
+All of the backwards compatibility formats will be removed in the future.