annotate docs/ccguide/scanf.refentry @ 2798:b70d93f8d7ce lwtools-port

Updated coco1/modules/makefile and coco3/modules/makefile to help resolve issues with i(x) and s(x) descriptors. Updated level1/coco1/modules/makefile & level2/coco3/modules/makefile so that correct values would be sent to assembler when building superdesc.asm for s(x).dd and i(x).dd descriptors.
author drencor-xeen
date Mon, 28 Jan 2013 16:13:05 -0600 (2013-01-28)
parents 8a16d38f3d94
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
1 <refentry id="scanf">
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
2 <refnamediv>
574
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
3 <refname>Scanf</refname>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
4 <refname>Fscanf</refname>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
5 <refname>Sscanf</refname>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
6 <refpurpose>input string interpretation</refpurpose>
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
7 </refnamediv>
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
8
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
9 <refsynopsisdiv>
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
10 <funcsynopsis>
468
60b821f18853 A little here and there.
roug
parents: 466
diff changeset
11 <funcsynopsisinfo>
60b821f18853 A little here and there.
roug
parents: 466
diff changeset
12 #include &lt;stdio.h&gt;
60b821f18853 A little here and there.
roug
parents: 466
diff changeset
13 </funcsynopsisinfo>
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
14 <funcprototype>
574
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
15 <funcdef><function>fscanf</function></funcdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
16 <paramdef>FILE *<parameter>fp</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
17 <paramdef>char *<parameter>control</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
18 <paramdef>char *<parameter>pointer...</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
19 </funcprototype>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
20
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
21 <funcprototype>
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
22 <funcdef><function>scanf</function></funcdef>
574
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
23 <paramdef>char *<parameter>control</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
24 <paramdef>char *<parameter>pointer...</parameter></paramdef>
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
25 </funcprototype>
574
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
26
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
27 <funcprototype>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
28 <funcdef><function>sscanf</function></funcdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
29 <paramdef>char *<parameter>string</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
30 <paramdef>char *<parameter>control</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
31 <paramdef>char *<parameter>pointer...</parameter></paramdef>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
32 </funcprototype>
c49be44efba2 All function prototypes are added.
roug
parents: 552
diff changeset
33
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
34 </funcsynopsis>
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
35
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
36 </refsynopsisdiv>
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
37
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
38 <refsect1><title>Description</title>
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
39 <para>
640
8a16d38f3d94 Convert to Docbook XML format
roug
parents: 605
diff changeset
40 These functions perform the complement to "printf()" etc.
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
41 </para>
605
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
42 <para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
43 Fscanf performs conversions from the file "fp", scanf from the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
44 standard input, and sscanf from the string pointed to by
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
45 "string".
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
46 </para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
47 <para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
48 Each function expects a control string containing conversion
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
49 specifications, and zero or more pointers to objects into which
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
50 the converted values are stored.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
51 </para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
52 <para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
53 The control string may contain three types of fields:
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
54 <orderedlist numeration="loweralpha" spacing="compact">
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
55 <listitem><para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
56 Space, tab characters, or "\n" which match any of
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
57 the three in the input.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
58 </para></listitem>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
59 <listitem><para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
60 Characters not among the above and not "%" which must
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
61 match characters in the input.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
62 </para></listitem>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
63 <listitem><para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
64 A "%" followed by an optional "*" indicates
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
65 suppression of assignment, an optional field width
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
66 maximum and a conversion character indicating the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
67 type expected.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
68 </para></listitem>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
69 </orderedlist>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
70 </para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
71 <para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
72 A conversion character controls the conversion to be applied
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
73 to the next field and indicates the type of the corresponding
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
74 pointer argument. A field consists of consecutive non-space
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
75 characters and ends at either a character inappropiate for the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
76 conversion or when a specified field is exhausted.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
77 When one field is finished, white-space characters are passed
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
78 over until the next field is found.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
79 </para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
80 <informaltable frame="none">
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
81 <tgroup cols="2">
640
8a16d38f3d94 Convert to Docbook XML format
roug
parents: 605
diff changeset
82 <colspec colwidth="0.5in"/>
8a16d38f3d94 Convert to Docbook XML format
roug
parents: 605
diff changeset
83 <colspec colwidth="3.5in"/>
605
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
84 <tbody>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
85 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
86 <entry>d</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
87 <entry>A decimal string is to be converted to an integer.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
88 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
89 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
90 <entry>o</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
91 <entry>An octal string; the coresponding argument should
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
92 point to an integer.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
93 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
94 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
95 <entry>x</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
96 <entry>A hexadecimal string for conversion to an integer.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
97 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
98 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
99 <entry>s</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
100 <entry>A string of non-space characters is expected and
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
101 will be copied to the buffer pointed to by the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
102 corresponding argument and a null ("\0") appended.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
103 The user must ensure that the buffer is large
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
104 enough. The input string is considered terminated
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
105 by a space, tab of ("\n").</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
106 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
107 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
108 <entry>c</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
109 <entry>A character is expected and is copied into the byte
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
110 pointed to by the argument. The white-space
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
111 skipping is suppressed for this conversion. If a
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
112 field width is given, the argument is assumed to
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
113 point to a character array and the number of
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
114 characters indicated is copied to it. NOTE to ensure
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
115 that the next non-white-space character is read use
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
116 "%1s" and that TWO bytes are pointed to by the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
117 argument.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
118 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
119 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
120 <entry>e,f</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
121 <entry>A floating point representation is expected on the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
122 input and the argument must be a pointer to a float.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
123 Any of the usual ways of writing floating point
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
124 numbers are recognized.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
125 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
126 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
127 <entry>[</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
128 <entry>This denotes the start of a set of match characters;
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
129 the inclusion or exclusion of which delimits the
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
130 input field. The white-space skipping is
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
131 suppressed. The corresponding argument should be a
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
132 pointer to a character array. If the first
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
133 character in the match string is not "^",
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
134 characters are copied from the input as long as they
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
135 can be found in the match string. If the first
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
136 character is the "^", copying continues while characters
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
137 cannot be found in the match string. The match
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
138 string is delimited by a "]".</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
139 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
140 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
141 <entry>D,O,X</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
142 <entry>Similar to d,o,x above, but the corresponding
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
143 argument is considered to point to a long integer.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
144 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
145 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
146 <entry>E,F</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
147 <entry>Similar to e,f above, but the corresponding
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
148 should point to a double.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
149 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
150 <row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
151 <entry>%</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
152 <entry>A match for "%" is sought; no conversion takes place.</entry>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
153 </row>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
154 </tbody>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
155 </tgroup>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
156 </informaltable>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
157 <para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
158 Each of the functions returns a count of the number of
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
159 fields successfully matched and assigned.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
160 </para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
161 </refsect1>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
162
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
163 <refsect1><title>Caveats</title>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
164 <para>
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
165 The returned count of matches/assigments does not include
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
166 character matches and assigments suppressed by "*". The
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
167 arguments must ALL be pointers. It is a common error to call
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
168 scanf with the value of an item rather than a pointer to it.
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
169 </para>
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
170 </refsect1>
542
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
171
552
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
172 <refsect1><title>Diagnostics</title>
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
173 <para>
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
174 These functions return EOF on end of input or error and a count
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
175 which is shorter than expected for unexpected or unmatched
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
176 items.
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
177 </para>
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
178 </refsect1>
fcb97f0ba24b All diagnostics added.
roug
parents: 542
diff changeset
179
542
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
180 <refsect1><title>See Also</title>
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
181 <para>
605
96ad5be1860b All refentries finished.
roug
parents: 574
diff changeset
182 <link linkend="atof">Atoi(), atof()</link>,
542
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
183 <link linkend="getc">getc()</link>,
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
184 <link linkend="printf">printf()</link>
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
185 Kernighan and Ritchie pp 147-150
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
186 </para>
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
187 </refsect1>
73319ee6a57e All "See Also" implemented
roug
parents: 468
diff changeset
188
466
bea58398bb15 Skeletons for the C Compiler User's Guide, 1983
roug
parents:
diff changeset
189 </refentry>