logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

fwscanf.3p (24525B)


  1. '\" et
  2. .TH FWSCANF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. fwscanf,
  12. swscanf,
  13. wscanf
  14. \(em convert formatted wide-character input
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <stdio.h>
  19. #include <wchar.h>
  20. .P
  21. int fwscanf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...);
  22. int swscanf(const wchar_t *restrict \fIws\fP,
  23. const wchar_t *restrict \fIformat\fP, ...);
  24. int wscanf(const wchar_t *restrict \fIformat\fP, ...);
  25. .fi
  26. .SH DESCRIPTION
  27. The functionality described on this reference page is aligned with the
  28. ISO\ C standard. Any conflict between the requirements described here and the
  29. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  30. .P
  31. The
  32. \fIfwscanf\fR()
  33. function shall read from the named input
  34. .IR stream .
  35. The
  36. \fIwscanf\fR()
  37. function shall read from the standard input stream
  38. .IR stdin .
  39. The
  40. \fIswscanf\fR()
  41. function shall read from the wide-character string
  42. .IR ws .
  43. Each function reads wide characters, interprets them according to a
  44. format, and stores the results in its arguments. Each expects, as
  45. arguments, a control wide-character string
  46. .IR format
  47. described below, and a set of
  48. .IR pointer
  49. arguments indicating where the converted input should be stored. The
  50. result is undefined if there are insufficient arguments for the
  51. format. If the
  52. .IR format
  53. is exhausted while arguments remain, the excess arguments are
  54. evaluated but are otherwise ignored.
  55. .P
  56. Conversions can be applied to the
  57. .IR n th
  58. argument after the
  59. .IR format
  60. in the argument list, rather than to the next unused argument. In this
  61. case, the conversion specifier wide character
  62. .BR %
  63. (see below) is replaced by the sequence
  64. .BR \(dq%n$\(dq ,
  65. where
  66. .IR n
  67. is a decimal integer in the range [1,{NL_ARGMAX}].
  68. This feature provides for the definition of
  69. .IR format
  70. wide-character strings that select arguments in an order appropriate
  71. to specific languages. In
  72. .IR format
  73. wide-character strings containing the \fR"%\fIn\fR$"\fR form of
  74. conversion specifications,
  75. it is unspecified whether numbered arguments in the argument list can
  76. be referenced from the
  77. .IR format
  78. wide-character string more than once.
  79. .P
  80. The
  81. .IR format
  82. can contain either form of a conversion specification\(emthat is,
  83. .BR %
  84. or \fR"%\fIn\fR$"\fR\(em but the two forms cannot normally be mixed
  85. within a single
  86. .IR format
  87. wide-character string. The only exception to this is that
  88. .BR %%
  89. or
  90. .BR %*
  91. can be mixed with the \fR"%\fIn\fR$"\fR form. When numbered argument
  92. specifications are used, specifying the
  93. .IR N th
  94. argument requires that all the leading arguments, from the first to
  95. the (\c
  96. .IR N \-1)th,
  97. are pointers.
  98. .P
  99. The
  100. \fIfwscanf\fR()
  101. function in all its forms allows for detection of a language-dependent
  102. radix character in the input string, encoded as a wide-character
  103. value. The radix character is defined in the current locale (category
  104. .IR LC_NUMERIC ).
  105. In the POSIX locale, or in a locale where the radix character is not
  106. defined, the radix character shall default to a
  107. <period>
  108. (\c
  109. .BR '.' ).
  110. .P
  111. The
  112. .IR format
  113. is a wide-character string composed of zero or more directives. Each
  114. directive is composed of one of the following:
  115. one or more white-space wide characters (\c
  116. <space>,
  117. <tab>,
  118. <newline>,
  119. <vertical-tab>,
  120. or
  121. <form-feed>);
  122. an ordinary wide character (neither
  123. .BR '%'
  124. nor a white-space character); or a conversion specification.
  125. It is unspecified whether an encoding error occurs if the
  126. format string contains
  127. .BR wchar_t
  128. values that do not correspond to members of the character
  129. set of the current locale and the specified semantics do not
  130. require that value to be processed by
  131. \fIwcrtomb\fR().
  132. .P
  133. Each conversion specification is introduced by the
  134. .BR '%'
  135. or by the character sequence \fR"%\fIn\fR$"\fR,
  136. after which the following appear in sequence:
  137. .IP " *" 4
  138. An optional assignment-suppressing character
  139. .BR '*' .
  140. .IP " *" 4
  141. An optional non-zero decimal integer that specifies the maximum field
  142. width.
  143. .IP " *" 4
  144. An optional assignment-allocation character
  145. .BR 'm' .
  146. .IP " *" 4
  147. An optional length modifier that specifies the size of the receiving
  148. object.
  149. .IP " *" 4
  150. A conversion specifier wide character that specifies the type of
  151. conversion to be applied. The valid conversion specifiers are described
  152. below.
  153. .P
  154. The
  155. \fIfwscanf\fR()
  156. functions shall execute each directive of the format in turn. If a
  157. directive fails, as detailed below, the function shall return. Failures
  158. are described as input failures (due to the unavailability of input
  159. bytes) or matching failures (due to inappropriate input).
  160. .P
  161. A directive composed of one or more white-space wide characters is
  162. executed by reading input until no more valid input can be read, or up
  163. to the first wide character which is not a white-space wide character,
  164. which remains unread.
  165. .P
  166. A directive that is an ordinary wide character shall be executed as
  167. follows. The next wide character is read from the input and compared
  168. with the wide character that comprises the directive; if the comparison
  169. shows that they are not equivalent, the directive shall fail, and the
  170. differing and subsequent wide characters remain unread. Similarly, if
  171. end-of-file, an encoding error, or a read error prevents a wide
  172. character from being read, the directive shall fail.
  173. .P
  174. A directive that is a conversion specification defines a set of
  175. matching input sequences, as described below for each conversion wide
  176. character. A conversion specification is executed in the following
  177. steps.
  178. .P
  179. Input white-space wide characters (as specified by
  180. .IR "\fIiswspace\fR\^(\|)")
  181. shall be skipped, unless the conversion specification includes a
  182. .BR [ ,
  183. .BR c ,
  184. or
  185. .BR n
  186. conversion specifier.
  187. .P
  188. An item shall be read from the input, unless the conversion
  189. specification includes an
  190. .BR n
  191. conversion specifier wide character. An input item is defined as the
  192. longest sequence of input wide characters, not exceeding any specified
  193. field width, which is an initial subsequence of a matching sequence.
  194. The first wide character, if any, after the input item shall remain
  195. unread. If the length of the input item is zero, the execution of the
  196. conversion specification shall fail; this condition is a matching
  197. failure, unless end-of-file, an encoding error, or a read error
  198. prevented input from the stream, in which case it is an input failure.
  199. .P
  200. Except in the case of a
  201. .BR %
  202. conversion specifier, the input item (or, in the case of a
  203. .BR %n
  204. conversion specification, the count of input wide characters) shall be
  205. converted to a type appropriate to the conversion wide character. If
  206. the input item is not a matching sequence, the execution of the
  207. conversion specification shall fail; this condition is a matching
  208. failure. Unless assignment suppression was indicated by a
  209. .BR '*' ,
  210. the result of the conversion shall be placed in the object pointed to
  211. by the first argument following the
  212. .IR format
  213. argument that has not already received a conversion result if the
  214. conversion specification is introduced by
  215. .BR % ,
  216. or in the
  217. .IR n th
  218. argument if introduced by the wide-character sequence
  219. \fR"%\fIn\fR$"\fR.
  220. If this object does not have an appropriate type, or if the result
  221. of the conversion cannot be represented in the space provided, the
  222. behavior is undefined.
  223. .P
  224. The
  225. .BR %c ,
  226. .BR %s ,
  227. and
  228. .BR %[
  229. conversion specifiers shall accept an optional assignment-allocation
  230. character
  231. .BR 'm' ,
  232. which shall cause a memory buffer to be allocated to hold the
  233. wide-character string converted including a terminating null wide
  234. character. In such a case, the argument corresponding to the conversion
  235. specifier should be a reference to a pointer value that will receive a
  236. pointer to the allocated buffer. The system shall allocate a buffer as if
  237. \fImalloc\fR()
  238. had been called. The application shall be responsible for freeing the
  239. memory after usage. If there is insufficient memory to allocate a buffer,
  240. the function shall set
  241. .IR errno
  242. to
  243. .BR [ENOMEM]
  244. and a conversion error shall result. If the function returns EOF, any
  245. memory successfully allocated for parameters using assignment-allocation
  246. character
  247. .BR 'm'
  248. by this call shall be freed before the function returns.
  249. .br
  250. .P
  251. The length modifiers and their meanings are:
  252. .IP "\fRhh\fR" 8
  253. Specifies that a following
  254. .BR d ,
  255. .BR i ,
  256. .BR o ,
  257. .BR u ,
  258. .BR x ,
  259. .BR X ,
  260. or
  261. .BR n
  262. conversion specifier applies to an argument with type pointer to
  263. .BR "signed char"
  264. or
  265. .BR "unsigned char" .
  266. .IP "\fRh\fR" 8
  267. Specifies that a following
  268. .BR d ,
  269. .BR i ,
  270. .BR o ,
  271. .BR u ,
  272. .BR x ,
  273. .BR X ,
  274. or
  275. .BR n
  276. conversion specifier applies to an argument with type pointer to
  277. .BR "short"
  278. or
  279. .BR "unsigned short" .
  280. .IP "\fRl\fR\ (ell)" 8
  281. Specifies that a following
  282. .BR d ,
  283. .BR i ,
  284. .BR o ,
  285. .BR u ,
  286. .BR x ,
  287. .BR X ,
  288. or
  289. .BR n
  290. conversion specifier applies to an argument with type pointer to
  291. .BR "long"
  292. or
  293. .BR "unsigned long" ;
  294. that a following
  295. .BR a ,
  296. .BR A ,
  297. .BR e ,
  298. .BR E ,
  299. .BR f ,
  300. .BR F ,
  301. .BR g ,
  302. or
  303. .BR G
  304. conversion specifier applies to an argument with type pointer to
  305. .BR double ;
  306. or that a following
  307. .BR c ,
  308. .BR s ,
  309. or
  310. .BR [
  311. conversion specifier applies to an argument with type pointer to
  312. .BR wchar_t .
  313. If the
  314. .BR 'm'
  315. assignment-allocation character is specified, the conversion applies
  316. to an argument with the type pointer to a pointer to
  317. .BR wchar_t .
  318. .IP "\fRll\fR\ (ell-ell)" 8
  319. .br
  320. Specifies that a following
  321. .BR d ,
  322. .BR i ,
  323. .BR o ,
  324. .BR u ,
  325. .BR x ,
  326. .BR X ,
  327. or
  328. .BR n
  329. conversion specifier applies to an argument with type pointer to
  330. .BR "long long"
  331. or
  332. .BR "unsigned long long" .
  333. .IP "\fRj\fR" 8
  334. Specifies that a following
  335. .BR d ,
  336. .BR i ,
  337. .BR o ,
  338. .BR u ,
  339. .BR x ,
  340. .BR X ,
  341. or
  342. .BR n
  343. conversion specifier applies to an argument with type pointer to
  344. .BR intmax_t
  345. or
  346. .BR uintmax_t .
  347. .IP "\fRz\fR" 8
  348. Specifies that a following
  349. .BR d ,
  350. .BR i ,
  351. .BR o ,
  352. .BR u ,
  353. .BR x ,
  354. .BR X ,
  355. or
  356. .BR n
  357. conversion specifier applies to an argument with type pointer to
  358. .BR size_t
  359. or the corresponding signed integer type.
  360. .IP "\fRt\fR" 8
  361. Specifies that a following
  362. .BR d ,
  363. .BR i ,
  364. .BR o ,
  365. .BR u ,
  366. .BR x ,
  367. .BR X ,
  368. or
  369. .BR n
  370. conversion specifier applies to an argument with type pointer to
  371. .BR ptrdiff_t
  372. or the corresponding
  373. .BR unsigned
  374. type.
  375. .IP "\fRL\fR" 8
  376. Specifies that a following
  377. .BR a ,
  378. .BR A ,
  379. .BR e ,
  380. .BR E ,
  381. .BR f ,
  382. .BR F ,
  383. .BR g ,
  384. or
  385. .BR G
  386. conversion specifier applies to an argument with type pointer to
  387. .BR "long double" .
  388. .P
  389. If a length modifier appears with any conversion specifier other than
  390. as specified above, the behavior is undefined.
  391. .P
  392. The following conversion specifier wide characters are valid:
  393. .IP "\fRd\fP" 8
  394. Matches an optionally signed decimal integer, whose format is the same
  395. as expected for the subject sequence of
  396. \fIwcstol\fR()
  397. with the value 10 for the
  398. .IR base
  399. argument. In the absence of a size modifier, the application shall ensure
  400. that the corresponding argument is a pointer to
  401. .BR int .
  402. .IP "\fRi\fP" 8
  403. Matches an optionally signed integer, whose format is the same as
  404. expected for the subject sequence of
  405. \fIwcstol\fR()
  406. with 0 for the
  407. .IR base
  408. argument. In the absence of a size modifier, the application shall
  409. ensure that the corresponding argument is a pointer to
  410. .BR int .
  411. .IP "\fRo\fP" 8
  412. Matches an optionally signed octal integer, whose format is the same as
  413. expected for the subject sequence of
  414. \fIwcstoul\fR()
  415. with the value 8 for the
  416. .IR base
  417. argument. In the absence of a size modifier, the application shall
  418. ensure that the corresponding argument is a pointer to
  419. .BR unsigned .
  420. .IP "\fRu\fP" 8
  421. Matches an optionally signed decimal integer, whose format is the same
  422. as expected for the subject sequence of
  423. \fIwcstoul\fR()
  424. with the value 10 for the
  425. .IR base
  426. argument. In the absence of a size modifier, the application shall
  427. ensure that the corresponding argument is a pointer to
  428. .BR unsigned .
  429. .IP "\fRx\fP" 8
  430. Matches an optionally signed hexadecimal integer, whose format is the
  431. same as expected for the subject sequence of
  432. \fIwcstoul\fR()
  433. with the value 16 for the
  434. .IR base
  435. argument. In the absence of a size modifier, the application shall
  436. ensure that the corresponding argument is a pointer to
  437. .BR unsigned .
  438. .IP "\fRa\fR,\ \fRe\fP,\ \fRf\fP,\ \fRg\fP" 8
  439. .br
  440. Matches an optionally signed floating-point number, infinity, or NaN
  441. whose format is the same as expected for the subject sequence of
  442. \fIwcstod\fR().
  443. In the absence of a size modifier, the application shall ensure that
  444. the corresponding argument is a pointer to
  445. .BR float .
  446. .RS 8
  447. .P
  448. If the
  449. \fIfwprintf\fR()
  450. family of functions generates character string representations for
  451. infinity and NaN (a symbolic entity encoded in floating-point
  452. format) to support IEEE\ Std\ 754\(hy1985, the
  453. \fIfwscanf\fR()
  454. family of functions shall recognize them as input.
  455. .RE
  456. .IP "\fRs\fP" 8
  457. Matches a sequence of non-white-space wide characters. If no
  458. .BR l
  459. (ell) qualifier is present, characters from the input field shall be
  460. converted as if by repeated calls to the
  461. \fIwcrtomb\fR()
  462. function, with the conversion state described by an
  463. .BR mbstate_t
  464. object initialized to zero before the first wide character is
  465. converted. If the
  466. .BR 'm'
  467. assignment-allocation character is not specified, the application shall
  468. ensure that the corresponding argument is a pointer to a character array
  469. large enough to accept the sequence and the terminating null character,
  470. which shall be added automatically.
  471. Otherwise, the application shall ensure that the corresponding
  472. argument is a pointer to a pointer to a
  473. .BR wchar_t .
  474. .RS 8
  475. .P
  476. If the
  477. .BR l
  478. (ell) qualifier is present and the
  479. .BR 'm'
  480. assignment-allocation character is not specified, the application shall
  481. ensure that the corresponding argument is a pointer to an array of
  482. .BR wchar_t
  483. large enough to accept the sequence and the terminating null wide
  484. character, which shall be added automatically.
  485. If the
  486. .BR l
  487. (ell) qualifier is present and the
  488. .BR 'm'
  489. assignment-allocation character is present, the application shall
  490. ensure that the corresponding argument is a pointer to a pointer
  491. to a
  492. .BR wchar_t .
  493. .RE
  494. .IP "\fR[\fR" 8
  495. Matches a non-empty sequence of wide characters from a set of expected
  496. wide characters (the
  497. .IR scanset ).
  498. If no
  499. .BR l
  500. (ell) qualifier is present, wide characters from the input field shall
  501. be converted as if by repeated calls to the
  502. \fIwcrtomb\fR()
  503. function, with the conversion state described by an
  504. .BR mbstate_t
  505. object initialized to zero before the first wide character is
  506. converted. If the
  507. .BR 'm'
  508. assignment-allocation character is not specified, the application shall
  509. ensure that the corresponding argument is a pointer to a character array
  510. large enough to accept the sequence and the terminating null character,
  511. which shall be added automatically.
  512. Otherwise, the application shall ensure that the corresponding
  513. argument is a pointer to a pointer to a
  514. .BR wchar_t .
  515. .RS 8
  516. .P
  517. If an
  518. .BR l
  519. (ell) qualifier is present and the
  520. .BR 'm'
  521. assignment-allocation character is not specified, the application shall
  522. ensure that the corresponding argument is a pointer to an array of
  523. .BR wchar_t
  524. large enough to accept the sequence and the terminating null
  525. wide character.
  526. If an
  527. .BR l
  528. (ell) qualifier is present and the
  529. .BR 'm'
  530. assignment-allocation character is specified, the application shall
  531. ensure that the corresponding argument is a pointer to a pointer
  532. to a
  533. .BR wchar_t .
  534. .P
  535. The conversion specification includes all subsequent wide characters in
  536. the
  537. .IR format
  538. string up to and including the matching
  539. <right-square-bracket>
  540. (\c
  541. .BR ']' ).
  542. The wide characters between the square brackets (the
  543. .IR scanlist )
  544. comprise the scanset, unless the wide character after the
  545. <left-square-bracket>
  546. is a
  547. <circumflex>
  548. (\c
  549. .BR '\(ha' ),
  550. in which case the scanset contains all wide characters that do not
  551. appear in the scanlist between the
  552. <circumflex>
  553. and the
  554. <right-square-bracket>.
  555. If the conversion specification begins with
  556. .BR \(dq[\|]\(dq
  557. or
  558. .BR \(dq[\(ha]\(dq ,
  559. the
  560. <right-square-bracket>
  561. is included in the scanlist and the next
  562. <right-square-bracket>
  563. is the matching
  564. <right-square-bracket>
  565. that ends the conversion specification; otherwise, the first
  566. <right-square-bracket>
  567. is the one that ends the conversion specification. If a
  568. .BR '\-'
  569. is in the scanlist and is not the first wide character, nor the second
  570. where the first wide character is a
  571. .BR '\(ha' ,
  572. nor the last wide character, the behavior is implementation-defined.
  573. .RE
  574. .IP "\fRc\fP" 8
  575. Matches a sequence of wide characters of exactly the number specified
  576. by the field width (1 if no field width is present in the conversion
  577. specification).
  578. .RS 8
  579. .P
  580. If no
  581. .BR l
  582. (ell) length modifier is present, characters from the input field shall
  583. be converted as if by repeated calls to the
  584. \fIwcrtomb\fR()
  585. function, with the conversion state described by an
  586. .BR mbstate_t
  587. object initialized to zero before the first wide character is
  588. converted. No null character is added. If the
  589. .BR 'm'
  590. assignment-allocation character is not specified, the application
  591. shall ensure that the corresponding argument is a pointer to the
  592. initial element of a character array large enough to accept the sequence.
  593. Otherwise, the application shall ensure that the corresponding
  594. argument is a pointer to a pointer to a
  595. .BR char .
  596. .P
  597. No null wide character is added. If an
  598. .BR l
  599. (ell) length modifier is present and the
  600. .BR 'm'
  601. assignment-allocation character is not specified, the application shall
  602. ensure that the corresponding argument shall be a pointer to the initial
  603. element of an array of
  604. .BR wchar_t
  605. large enough to accept the sequence.
  606. If an
  607. .BR l
  608. (ell) qualifier is present and the
  609. .BR 'm'
  610. assignment-allocation character is specified, the application shall
  611. ensure that the corresponding argument is a pointer to a pointer
  612. to a
  613. .BR wchar_t .
  614. .RE
  615. .IP "\fRp\fP" 8
  616. Matches an implementation-defined set of sequences, which shall be
  617. the same as the set of sequences that is produced by the
  618. .BR %p
  619. conversion specification of the corresponding
  620. \fIfwprintf\fR()
  621. functions. The application shall ensure that the corresponding argument
  622. is a pointer to a pointer to
  623. .BR void .
  624. The interpretation of the input item is implementation-defined. If
  625. the input item is a value converted earlier during the same program
  626. execution, the pointer that results shall compare equal to that value;
  627. otherwise, the behavior of the
  628. .BR %p
  629. conversion is undefined.
  630. .IP "\fRn\fP" 8
  631. No input is consumed. The application shall ensure that the
  632. corresponding argument is a pointer to the integer into which is to be
  633. written the number of wide characters read from the input so far by
  634. this call to the
  635. \fIfwscanf\fR()
  636. functions. Execution of a
  637. .BR %n
  638. conversion specification shall not increment the assignment count
  639. returned at the completion of execution of the function. No argument
  640. shall be converted, but one shall be consumed. If the conversion
  641. specification includes an assignment-suppressing wide character or a
  642. field width, the behavior is undefined.
  643. .IP "\fRC\fP" 8
  644. Equivalent to
  645. .BR lc .
  646. .IP "\fRS\fP" 8
  647. Equivalent to
  648. .BR ls .
  649. .IP "\fR%\fR" 8
  650. Matches a single
  651. .BR '%'
  652. wide character; no conversion or assignment shall occur. The complete
  653. conversion specification shall be
  654. .BR %% .
  655. .P
  656. If a conversion specification is invalid, the behavior is undefined.
  657. .P
  658. The conversion specifiers
  659. .BR A ,
  660. .BR E ,
  661. .BR F ,
  662. .BR G ,
  663. and
  664. .BR X
  665. are also valid and shall be equivalent to, respectively,
  666. .BR a ,
  667. .BR e ,
  668. .BR f ,
  669. .BR g ,
  670. and
  671. .BR x .
  672. .P
  673. If end-of-file is encountered during input, conversion is terminated.
  674. If end-of-file occurs before any wide characters matching the current
  675. conversion specification (except for
  676. .BR %n )
  677. have been read (other than leading white-space, where permitted),
  678. execution of the current conversion specification shall terminate with
  679. an input failure. Otherwise, unless execution of the current conversion
  680. specification is terminated with a matching failure, execution of the
  681. following conversion specification (if any) shall be terminated with an
  682. input failure.
  683. .P
  684. Reaching the end of the string in
  685. \fIswscanf\fR()
  686. shall be equivalent to encountering end-of-file for
  687. \fIfwscanf\fR().
  688. .P
  689. If conversion terminates on a conflicting input, the offending input
  690. shall be left unread in the input. Any trailing white space (including
  691. <newline>)
  692. shall be left unread unless matched by a conversion specification. The
  693. success of literal matches and suppressed assignments is only directly
  694. determinable via the
  695. .BR %n
  696. conversion specification.
  697. .P
  698. The
  699. \fIfwscanf\fR()
  700. and
  701. \fIwscanf\fR()
  702. functions may mark the last data access timestamp of the file
  703. associated with
  704. .IR stream
  705. for update. The last data access timestamp shall be marked for update
  706. by the first successful execution of
  707. \fIfgetwc\fR(),
  708. \fIfgetws\fR(),
  709. \fIfwscanf\fR(),
  710. \fIgetwc\fR(),
  711. \fIgetwchar\fR(),
  712. \fIvfwscanf\fR(),
  713. \fIvwscanf\fR(),
  714. or
  715. \fIwscanf\fR()
  716. using
  717. .IR stream
  718. that returns data not supplied by a prior call to
  719. \fIungetwc\fR().
  720. .SH "RETURN VALUE"
  721. Upon successful completion, these functions shall return the number of
  722. successfully matched and assigned input items; this number can be zero
  723. in the event of an early matching failure. If the input ends before
  724. the first conversion (if any) has completed, and without a
  725. matching failure having occurred, EOF shall be returned. If an
  726. error occurs before the first conversion (if any) has completed,
  727. and without a matching failure having occurred, EOF shall be returned
  728. and
  729. .IR errno
  730. shall be set to indicate the error.
  731. If a read error occurs, the error indicator for the stream shall be set.
  732. .SH ERRORS
  733. For the conditions under which the
  734. \fIfwscanf\fR()
  735. functions shall fail and may fail, refer to
  736. .IR "\fIfgetwc\fR\^(\|)".
  737. .P
  738. In addition, the
  739. \fIfwscanf\fR()
  740. function shall fail if:
  741. .TP
  742. .BR EILSEQ
  743. Input byte sequence does not form a valid character.
  744. .TP
  745. .BR ENOMEM
  746. Insufficient storage space is available.
  747. .P
  748. In addition, the
  749. \fIfwscanf\fR()
  750. function may fail if:
  751. .TP
  752. .BR EINVAL
  753. There are insufficient arguments.
  754. .LP
  755. .IR "The following sections are informative."
  756. .SH "EXAMPLES"
  757. The call:
  758. .sp
  759. .RS 4
  760. .nf
  761. int i, n; float x; char name[50];
  762. n = wscanf(L"%d%f%s", &i, &x, name);
  763. .fi
  764. .P
  765. .RE
  766. .P
  767. with the input line:
  768. .sp
  769. .RS 4
  770. .nf
  771. 25 54.32E-1 Hamster
  772. .fi
  773. .P
  774. .RE
  775. .P
  776. assigns to
  777. .IR n
  778. the value 3, to
  779. .IR i
  780. the value 25, to
  781. .IR x
  782. the value 5.432, and
  783. .IR name
  784. contains the string
  785. .BR \(dqHamster\(dq .
  786. .P
  787. The call:
  788. .sp
  789. .RS 4
  790. .nf
  791. int i; float x; char name[50];
  792. (void) wscanf(L"%2d%f%*d %[0123456789]", &i, &x, name);
  793. .fi
  794. .P
  795. .RE
  796. .P
  797. with input:
  798. .sp
  799. .RS 4
  800. .nf
  801. 56789 0123 56a72
  802. .fi
  803. .P
  804. .RE
  805. .P
  806. assigns 56 to
  807. .IR i ,
  808. 789.0 to
  809. .IR x ,
  810. skips 0123, and places the string
  811. .BR \(dq56\e0\(dq
  812. in
  813. .IR name .
  814. The next call to
  815. \fIgetchar\fR()
  816. shall return the character
  817. .BR 'a' .
  818. .SH "APPLICATION USAGE"
  819. In format strings containing the
  820. .BR '%'
  821. form of conversion specifications, each argument in the argument
  822. list is used exactly once.
  823. .P
  824. For functions that allocate memory as if by
  825. \fImalloc\fR(),
  826. the application should release such memory when it is no longer
  827. required by a call to
  828. \fIfree\fR().
  829. For
  830. \fIfwscanf\fR(),
  831. this is memory allocated via use of the
  832. .BR 'm'
  833. assignment-allocation character.
  834. .SH RATIONALE
  835. None.
  836. .SH "FUTURE DIRECTIONS"
  837. None.
  838. .SH "SEE ALSO"
  839. .IR "Section 2.5" ", " "Standard I/O Streams",
  840. .IR "\fIgetwc\fR\^(\|)",
  841. .IR "\fIfwprintf\fR\^(\|)",
  842. .IR "\fIsetlocale\fR\^(\|)",
  843. .IR "\fIwcstod\fR\^(\|)",
  844. .IR "\fIwcstol\fR\^(\|)",
  845. .IR "\fIwcstoul\fR\^(\|)",
  846. .IR "\fIwcrtomb\fR\^(\|)"
  847. .P
  848. The Base Definitions volume of POSIX.1\(hy2017,
  849. .IR "Chapter 7" ", " "Locale",
  850. .IR "\fB<inttypes.h>\fP",
  851. .IR "\fB<stdio.h>\fP",
  852. .IR "\fB<wchar.h>\fP"
  853. .\"
  854. .SH COPYRIGHT
  855. Portions of this text are reprinted and reproduced in electronic form
  856. from IEEE Std 1003.1-2017, Standard for Information Technology
  857. -- Portable Operating System Interface (POSIX), The Open Group Base
  858. Specifications Issue 7, 2018 Edition,
  859. Copyright (C) 2018 by the Institute of
  860. Electrical and Electronics Engineers, Inc and The Open Group.
  861. In the event of any discrepancy between this version and the original IEEE and
  862. The Open Group Standard, the original IEEE and The Open Group Standard
  863. is the referee document. The original Standard can be obtained online at
  864. http://www.opengroup.org/unix/online.html .
  865. .PP
  866. Any typographical or formatting errors that appear
  867. in this page are most likely
  868. to have been introduced during the conversion of the source files to
  869. man page format. To report such errors, see
  870. https://www.kernel.org/doc/man-pages/reporting_bugs.html .