Mercurial > hg > Members > kono > nitros9-code

comparison docs/ccguide/scanf.refentry @ 605:96ad5be1860b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
All refentries finished.
author roug
date Fri, 15 Nov 2002 21:49:51 +0000
parents c49be44efba2
children 8a16d38f3d94
comparison
equal deleted inserted replaced
604:1d37d3a84a7c 605:96ad5be1860b
37 37
38 <refsect1><title>Description</title> 38 <refsect1><title>Description</title>
39 <para> 39 <para>
40 Placeholder 40 Placeholder
41 </para> 41 </para>
42 <para>
43 Fscanf performs conversions from the file "fp", scanf from the
44 standard input, and sscanf from the string pointed to by
45 "string".
46 </para>
47 <para>
48 Each function expects a control string containing conversion
49 specifications, and zero or more pointers to objects into which
50 the converted values are stored.
51 </para>
52 <para>
53 The control string may contain three types of fields:
54 <orderedlist numeration="loweralpha" spacing="compact">
55 <listitem><para>
56 Space, tab characters, or "\n" which match any of
57 the three in the input.
58 </para></listitem>
59 <listitem><para>
60 Characters not among the above and not "%" which must
61 match characters in the input.
62 </para></listitem>
63 <listitem><para>
64 A "%" followed by an optional "*" indicates
65 suppression of assignment, an optional field width
66 maximum and a conversion character indicating the
67 type expected.
68 </para></listitem>
69 </orderedlist>
70 </para>
71 <para>
72 A conversion character controls the conversion to be applied
73 to the next field and indicates the type of the corresponding
74 pointer argument. A field consists of consecutive non-space
75 characters and ends at either a character inappropiate for the
76 conversion or when a specified field is exhausted.
77 When one field is finished, white-space characters are passed
78 over until the next field is found.
79 </para>
80 <informaltable frame="none">
81 <tgroup cols="2">
82 <colspec colwidth="0.5in">
83 <colspec colwidth="3.5in">
84 <tbody>
85 <row>
86 <entry>d</entry>
87 <entry>A decimal string is to be converted to an integer.</entry>
88 </row>
89 <row>
90 <entry>o</entry>
91 <entry>An octal string; the coresponding argument should
92 point to an integer.</entry>
93 </row>
94 <row>
95 <entry>x</entry>
96 <entry>A hexadecimal string for conversion to an integer.</entry>
97 </row>
98 <row>
99 <entry>s</entry>
100 <entry>A string of non-space characters is expected and
101 will be copied to the buffer pointed to by the
102 corresponding argument and a null ("\0") appended.
103 The user must ensure that the buffer is large
104 enough. The input string is considered terminated
105 by a space, tab of ("\n").</entry>
106 </row>
107 <row>
108 <entry>c</entry>
109 <entry>A character is expected and is copied into the byte
110 pointed to by the argument. The white-space
111 skipping is suppressed for this conversion. If a
112 field width is given, the argument is assumed to
113 point to a character array and the number of
114 characters indicated is copied to it. NOTE to ensure
115 that the next non-white-space character is read use
116 "%1s" and that TWO bytes are pointed to by the
117 argument.</entry>
118 </row>
119 <row>
120 <entry>e,f</entry>
121 <entry>A floating point representation is expected on the
122 input and the argument must be a pointer to a float.
123 Any of the usual ways of writing floating point
124 numbers are recognized.</entry>
125 </row>
126 <row>
127 <entry>[</entry>
128 <entry>This denotes the start of a set of match characters;
129 the inclusion or exclusion of which delimits the
130 input field. The white-space skipping is
131 suppressed. The corresponding argument should be a
132 pointer to a character array. If the first
133 character in the match string is not "^",
134 characters are copied from the input as long as they
135 can be found in the match string. If the first
136 character is the "^", copying continues while characters
137 cannot be found in the match string. The match
138 string is delimited by a "]".</entry>
139 </row>
140 <row>
141 <entry>D,O,X</entry>
142 <entry>Similar to d,o,x above, but the corresponding
143 argument is considered to point to a long integer.</entry>
144 </row>
145 <row>
146 <entry>E,F</entry>
147 <entry>Similar to e,f above, but the corresponding
148 should point to a double.</entry>
149 </row>
150 <row>
151 <entry>%</entry>
152 <entry>A match for "%" is sought; no conversion takes place.</entry>
153 </row>
154 </tbody>
155 </tgroup>
156 </informaltable>
157 <para>
158 Each of the functions returns a count of the number of
159 fields successfully matched and assigned.
160 </para>
161 </refsect1>
162
163 <refsect1><title>Caveats</title>
164 <para>
165 The returned count of matches/assigments does not include
166 character matches and assigments suppressed by "*". The
167 arguments must ALL be pointers. It is a common error to call
168 scanf with the value of an item rather than a pointer to it.
169 </para>
42 </refsect1> 170 </refsect1>
43 171
44 <refsect1><title>Diagnostics</title> 172 <refsect1><title>Diagnostics</title>
45 <para> 173 <para>
46 These functions return EOF on end of input or error and a count 174 These functions return EOF on end of input or error and a count
49 </para> 177 </para>
50 </refsect1> 178 </refsect1>
51 179
52 <refsect1><title>See Also</title> 180 <refsect1><title>See Also</title>
53 <para> 181 <para>
54 <link linkend="atof">atoi(), atof()</link>, 182 <link linkend="atof">Atoi(), atof()</link>,
55 <link linkend="getc">getc()</link>, 183 <link linkend="getc">getc()</link>,
56 <link linkend="printf">printf()</link> 184 <link linkend="printf">printf()</link>
57 Kernighan and Ritchie pp 147-150 185 Kernighan and Ritchie pp 147-150
58 </para> 186 </para>
59 </refsect1> 187 </refsect1>