1
0

fscanf 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404
  1. .TH FSCANF 2
  2. .SH NAME
  3. fscanf, scanf, sscanf, vfscanf \- scan formatted input
  4. .SH SYNOPSIS
  5. .B "#include <u.h>
  6. .br
  7. .B "#include <stdio.h>"
  8. .PP
  9. .B
  10. int fscanf(FILE *f, char *format, ...)
  11. .PP
  12. .B
  13. int scanf(char *format, ... )
  14. .PP
  15. .B
  16. int sscanf(char *s, char *format, ...)
  17. .PP
  18. .B
  19. int vfscanf(FILE *stream, char *format, char *args)
  20. .SH DESCRIPTION
  21. .I Fscanf
  22. reads from the named input stream
  23. .I f
  24. (see
  25. .IR fopen (2))
  26. under control of the string pointed to by
  27. .I format
  28. that specifies the admissible input sequences and how they are to be converted
  29. for assignment, using subsequent arguments as pointers to the objects
  30. to receive the converted input.
  31. If there are insufficient arguments for the format, the behavior is undefined.
  32. If the format is exhausted while arguments remain, the excess arguments
  33. are evaluated (as always) but are otherwise ignored.
  34. .PP
  35. .I Scanf
  36. and
  37. .I sscanf
  38. are the same, but they read from
  39. .I stdin
  40. and the character string
  41. .IR s ,
  42. respectively.
  43. .I Vfscanf
  44. is like
  45. .IR scanf ,
  46. except the
  47. .I args
  48. argument is a pointer to an argument in an argument list of the
  49. calling function and the effect is as if the calling function's
  50. argument list from that point on is passed to the scanf routines.
  51. .PP
  52. The format is composed of zero or more directives:
  53. one or more white-space characters; an ordinary character (not
  54. .BR % );
  55. or a conversion specification.
  56. Each conversion specification is introduced by the character
  57. .BR %.
  58. After the
  59. .BR % ,
  60. the following appear in sequence:
  61. .PP
  62. .RS
  63. An optional assignment-suppressing character
  64. .BR * .
  65. .PP
  66. An optional decimal integer that specifies the maximum field width.
  67. .PP
  68. An optional
  69. .BR h ,
  70. .B l
  71. (ell) or
  72. .B L
  73. indicating the size of the receiving object.
  74. The conversion specifiers
  75. .BR d ,
  76. .BR i ,
  77. and
  78. .B n
  79. shall be preceded by
  80. .B h
  81. if the corresponding argument is a pointer to
  82. .B short
  83. rather than a pointer to
  84. .BR int ,
  85. or by
  86. .B l
  87. if it is a pointer to
  88. .BR long .
  89. Similarly, the conversion specifiers
  90. .BR o ,
  91. .BR u ,
  92. and
  93. .B x
  94. shall be preceded by
  95. .B h
  96. if the corresponding argument is a pointer to
  97. .B unsigned
  98. .B short
  99. rather than a pointer to
  100. .BR unsigned ,
  101. or by
  102. .B l
  103. if it is a pointer to
  104. .B unsigned
  105. .BR long .
  106. Finally, the conversion specifiers
  107. .BR e ,
  108. .BR f ,
  109. and
  110. .B g
  111. shall be preceded by
  112. .B l
  113. if the corresponding argument is a pointer to
  114. .B double
  115. rather than a pointer to
  116. .BR float ,
  117. or by
  118. .B L
  119. if it is a pointer to
  120. .B long
  121. .BR double .
  122. If an
  123. .BR h ,
  124. .BR l ,
  125. or
  126. .B L
  127. appears with any other conversion specifier, the behavior is undefined.
  128. .PP
  129. A character that specifies the type of conversion to be applied.
  130. The valid conversion specifiers are described below.
  131. .RE
  132. .PP
  133. .I Fscanf
  134. executes each directive of the format in turn.
  135. If a directive fails, as detailed below,
  136. .I fscanf
  137. returns.
  138. Failures are described as input failures (due to the unavailability
  139. of input),
  140. or matching failures (due to inappropriate input).
  141. .PP
  142. A directive composed of white space is executed by reading input up
  143. to the first non-white-space character (which remains unread),
  144. or until no more characters can be read.
  145. .PP
  146. A directive that is an ordinary character is executed by reading
  147. the next character from the stream.
  148. If if differs from the one comprising the directive,
  149. the directive fails, and the differing and subsequent characters
  150. remain unread.
  151. .PP
  152. A directive that is a conversion specification defines a set of
  153. matching input sequences, as described below for each specifier.
  154. A conversion specification is executed in the following steps:
  155. .PP
  156. Input white-space characters (as specified by
  157. .IR isspace ,
  158. see
  159. .IR ctype (2))
  160. are skipped, unless the specification includes a
  161. .BR [ ,
  162. .BR c ,
  163. or
  164. .B n
  165. specifier.
  166. .PP
  167. An input item is read from the stream,
  168. unless the specification includes an
  169. .B n
  170. specifier.
  171. An input item is defined as the longest sequence of input characters
  172. (up to any specified maximum field width) which is an initial
  173. subsequence of a matching sequence.
  174. The first character, if any, after the input item remains unread.
  175. If the length of the input item is zero, the execution of
  176. the directive fails: this condition is a matching failure,
  177. unless an error prevented input from the stream,
  178. in which case it is an input failure.
  179. .PP
  180. Except in the case of a
  181. .B %
  182. specifier, the input item (or, in the case of a
  183. .B %n
  184. directive, the count of input characters)
  185. is converted to a type appropriate to the conversion specifier.
  186. If the input item is not a matching sequence, the execution of
  187. the directive fails: this condition is a matching failure.
  188. Unless assignment suppression was indicated by a
  189. .BR * ,
  190. the result of the conversion is placed in the object pointed to by the
  191. first argument following the
  192. .I format
  193. argument that has not already received a conversion result.
  194. If this object does not have an appropriate type,
  195. or if the result of the conversion cannot be represented
  196. in the space provided, the behavior is undefined.
  197. .PP
  198. The following conversion specifiers are valid:
  199. .TP 6
  200. .B d
  201. Matches an optionally signed decimal integer,
  202. whose format is the same as expected for the subject sequence
  203. of the
  204. .I strtol
  205. (see
  206. .IR atof (2))
  207. function with 10 for the
  208. .B base
  209. argument.
  210. The corresponding argument shall be a pointer to
  211. .BR int .
  212. .TP
  213. .B i
  214. Matches an optionally signed decimal integer,
  215. whose format is the same as expected for the subject sequence
  216. of the
  217. .I strtol
  218. function with 0 for the
  219. .B base
  220. argument.
  221. The corresponding argument shall be a pointer to
  222. .BR int .
  223. .TP
  224. .B o
  225. Matches an optionally signed octal integer,
  226. whose format is the same as expected for the subject sequence
  227. of the
  228. .I strtoul
  229. (see
  230. .IR atof (2))
  231. function with 8 for the
  232. .B base
  233. argument.
  234. The corresponding argument shall be a pointer to
  235. .B unsigned
  236. .BR int .
  237. .TP
  238. .B u
  239. Matches an optionally signed decimal integer,
  240. whose format is the same as expected for the subject sequence
  241. of the
  242. .I strtoul
  243. function with 10 for the
  244. .B base
  245. argument.
  246. The corresponding argument shall be a pointer to
  247. .B unsigned
  248. .BR int .
  249. .TP
  250. .B x
  251. Matches an optionally signed hexadecimal integer,
  252. whose format is the same as expected for the subject sequence
  253. of the
  254. .I strtoul
  255. function with 16 for the
  256. .B base
  257. argument.
  258. The corresponding argument shall be a pointer to
  259. .B unsigned
  260. .BR int .
  261. .TP
  262. .BR e , f , g
  263. Matches an optionally signed floating-point number, whose format is
  264. the same as expected for the subject string of the
  265. .I strtod
  266. (see
  267. .IR atof (2))
  268. function.
  269. The corresponding argument shall be a pointer to
  270. .BR float .
  271. .TP
  272. .B s
  273. Matches a sequence of non-white-space characters.
  274. The corresponding argument shall be a pointer to the initial
  275. character of an array large enough to accept the sequence
  276. and a terminating NUL (0) character, which will be added automatically.
  277. .TP
  278. .B [
  279. Matches a nonempty sequence of characters from a set of expected
  280. characters (the
  281. .IR scanset ).
  282. The corresponding argument shall be a pointer to the initial
  283. character of an array large enough to accept the sequence and a terminating
  284. NUL character, which will be added automatically.
  285. The conversion specifier includes all subsequent characters in the
  286. .I format
  287. string, up to and including the matching right brace
  288. .RB ( ] ).
  289. The characters between the brackets (the
  290. .IR scanlist )
  291. comprise the scanset, unless the character after the left bracket
  292. is a circumflex
  293. .RB ( ^ ),
  294. in which case the scanset contains all characters that do not appear
  295. in the scanlist between the circumflex and the right bracket.
  296. As a special case, if the conversion specifier begins with
  297. .B []
  298. or
  299. .BR [^] ,
  300. the right bracket character is in the scanlist and the next
  301. right bracket character is the matching right bracket
  302. that ends the specification.
  303. If a
  304. .B -
  305. character is in the scanlist and is not the first, nor the second
  306. where the first character is a
  307. .BR ^ ,
  308. nor the last character, the behavior is implementation-defined
  309. (in Plan 9: the scanlist includes all characters in the
  310. .SM ASCII
  311. (sic)
  312. range between the two characters on either side of the
  313. .BR - ).
  314. .TP
  315. .B c
  316. Matches a sequence of characters of the number specified by the field width
  317. (1 if no field width is present in the directive).
  318. The corresponding argument shall be a pointer to the initial character
  319. of an array large enough to accept the sequence.
  320. No NUL character is added.
  321. .TP
  322. .B P
  323. Matches an implementation-defined set of sequences,
  324. which should be the same as the set of sequences that may be
  325. produced by the
  326. .B %P
  327. conversion of the
  328. .IR fprintf (2)
  329. function
  330. (in Plan 9, a hexadecimal number).
  331. The corresponding argument shall be a pointer to a pointer to
  332. .BR void .
  333. The interpretation of the input item is implementation defined;
  334. however, for any input item other than a value converted earlier
  335. during the same program execution, the behavior of the
  336. .B %P
  337. conversion is undefined.
  338. .TP
  339. .B n
  340. No input is consumed.
  341. The corresponding argument shall be a pointer to integer into which
  342. is written the number of characters read from the input stream so far
  343. by this call to
  344. .IR fscanf .
  345. Execution of a
  346. .B %n
  347. directive does not increment the assignment count returned at the
  348. completion of
  349. .IR fscanf .
  350. .TP
  351. .B %
  352. Matches a single
  353. .BR % ;
  354. no conversion or assignment occurs.
  355. The complete conversion specification shall be
  356. .BR %% .
  357. .PD
  358. .PP
  359. If a conversion specification is invalid, the behavior is undefined.
  360. .PP
  361. The conversion specifiers
  362. .BR E ,
  363. .BR G ,
  364. and
  365. .B X
  366. are also valid and behave the same as, respectively,
  367. .BR e ,
  368. .BR g ,
  369. and
  370. .BR x .
  371. .PP
  372. If end-of-file is encountered during input, conversion is terminated.
  373. If end-of-file occurs before any characters matching the current
  374. directive have been read (other than leading white space,
  375. where permitted), execution of the current directive terminates with
  376. an input failure;
  377. otherwise, unless execution of the current directive is terminated
  378. with a matching failure, execution of the following directive
  379. (if any) is terminated with an input failure.
  380. .PP
  381. If conversion terminates on a conflicting input character,
  382. the offending input character is left unread in the input stream.
  383. Trailing white space (including newline characters) is left unread
  384. unless matched by a directive.
  385. The success of literal matches and suppressed assignments is not
  386. directly determinable other than via the
  387. .B %n
  388. directive.
  389. .PP
  390. The return value from
  391. .I fscanf
  392. is the number of input items assigned, which can be fewer than
  393. provided for, or even zero, in the event of an early matching failure.
  394. However, if an input failure occurs before any conversion,
  395. .B EOF
  396. is returned.
  397. .SH SOURCE
  398. .B /sys/src/libstdio
  399. .SH "SEE ALSO"
  400. .IR fopen (2),
  401. .IR fgetc (2)
  402. .SH BUGS
  403. Does not know about
  404. .SM UTF.