(split) LDP: Update original to LDP v3.50.

[linuxjm/LDP_man-pages.git] / original / man3 / scanf.3

diff --git a/original/man3/scanf.3 b/original/man3/scanf.3
index 1e6f32d..62695f3 100644 (file)
--- a/original/man3/scanf.3
+++ b/original/man3/scanf.3
@@ -5,6 +5,7 @@
 .\" Chris Torek and the American National Standards Committee X3,
 .\" on Information Processing Systems.
 .\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
@@ -32,6 +33,7 @@
 .\" 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.
+.\" %%%LICENSE_END
 .\"
 .\"     @(#)scanf.3    6.14 (Berkeley) 1/8/93
 .\"
@@ -47,7 +49,7 @@
 .\"     Add ERRORS section.
 .\"     Document the 'a' and 'm' modifiers for dynamic string allocation.
 .\"
-.TH SCANF 3  2011-09-28 "GNU" "Linux Programmer's Manual"
+.TH SCANF 3  2013-01-30 "GNU" "Linux Programmer's Manual"
 .SH NAME
 scanf, fscanf, sscanf, vscanf, vsscanf, vfscanf \- input format conversion
 .SH SYNOPSIS
@@ -198,8 +200,12 @@ included in the count of successful assignments returned by
 .BR scanf ().
 .TP
 \(bu
-An optional \(aqa\(aq character.
-This is used with string conversions, and relieves the caller of the
+An optional \(aqm\(aq character.
+This is used with string conversions
+.RI ( %s ,
+.IR %c ,
+.IR %[ ),
+and relieves the caller of the
 need to allocate a corresponding buffer to hold the input: instead,
 .BR scanf ()
 allocates a buffer of sufficient size,
@@ -211,9 +217,6 @@ variable (this variable does not need to be initialized before the call).
 The caller should subsequently
 .BR free (3)
 this buffer when it is no longer required.
-This is a GNU extension;
-C99 employs the \(aqa\(aq character as a conversion specifier (and
-it can also be used as such in the GNU implementation).
 .TP
 \(bu
 An optional decimal integer which specifies the
@@ -525,7 +528,7 @@ Probably it is wise
 not to make any assumptions on the effect of
 .B %n
 conversions on the return value.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 These functions return the number of input items
 successfully matched and assigned,
 which can be fewer than provided for,
@@ -572,7 +575,7 @@ Out of memory.
 .B ERANGE
 The result of an integer conversion would exceed the size
 that can be stored in the corresponding integer type.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
 The functions
 .BR fscanf (),
 .BR scanf (),
@@ -604,51 +607,13 @@ documentation of
 .I libc (glibc-1.08)
 for a more concise description.
 .SH NOTES
-The GNU C library supports a nonstandard extension that causes
-the library to dynamically allocate a string of sufficient size
-for input strings for the
-.B %s
-and
-\fB%a[\fP\fIrange\fP\fB]\fP
-conversion specifiers.
-.\" This feature seems to be present at least as far back as glibc 2.0.
-To make use of this feature, specify
+The GNU C library supported the dynamic allocation conversion specifier
+(as a nonstandard extension) via the
 .B a
-as a length modifier (thus
-.B %as
-or
-\fB%a[\fP\fIrange\fP\fB]\fP).
-The caller must
-.BR free (3)
-the returned string, as in the following example:
-.in +4n
-.nf
-
-char *p;
-int n;
-
-errno = 0;
-n = scanf("%a[a-z]", &p);
-if (n == 1) {
-    printf("read: %s\\n", p);
-    free(p);
-} else if (errno != 0) {
-    perror("scanf");
-} else {
-    fprintf(stderr, "No matching characters\\n");
-}
-.fi
-.in
+character.  This feature
+seems to be present at least as far back as glibc 2.0.
 .PP
-As shown in the above example, it is only necessary to call
-.BR free (3)
-if the
-.BR scanf ()
-call successfully read a string.
-.PP
-The
-.B a
-modifier is not available if the program is compiled with
+It is not available if the program is compiled with
 .I "gcc -std=c99"
 or
 .IR "gcc -D_ISOC99_SOURCE"
@@ -678,7 +643,7 @@ floating-point conversion specifier (and is unaffected by
 .IR "gcc -std=c99"
 etc.)
 .IP *
-It is specified in the upcoming revision of the POSIX.1 standard.
+It is specified in the POSIX.1-2008 standard.
 .SH BUGS
 All functions are fully C89 conformant, but provide the
 additional specifiers
@@ -714,7 +679,41 @@ The usage of
 is not the same as on 4.4BSD,
 as it may be used in float conversions equivalently to
 .BR L .
-.SH "SEE ALSO"
+.SH EXAMPLE
+To use the dynamic allocation conversion specifier, specify
+.B m
+as a length modifier (thus
+.B %ms
+or
+\fB%m[\fP\fIrange\fP\fB]\fP).
+The caller must
+.BR free (3)
+the returned string, as in the following example:
+.in +4n
+.nf
+
+char *p;
+int n;
+
+errno = 0;
+n = scanf("%m[a-z]", &p);
+if (n == 1) {
+    printf("read: %s\\n", p);
+    free(p);
+} else if (errno != 0) {
+    perror("scanf");
+} else {
+    fprintf(stderr, "No matching characters\\n");
+}
+.fi
+.in
+.PP
+As shown in the above example, it is only necessary to call
+.BR free (3)
+if the
+.BR scanf ()
+call successfully read a string.
+.SH SEE ALSO
 .BR getc (3),
 .BR printf (3),
 .BR setlocale (3),