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

fwprintf.3p (26282B)


  1. '\" et
  2. .TH FWPRINTF "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. fwprintf,
  12. swprintf,
  13. wprintf
  14. \(em print formatted wide-character output
  15. .SH SYNOPSIS
  16. .LP
  17. .nf
  18. #include <stdio.h>
  19. #include <wchar.h>
  20. .P
  21. int fwprintf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...);
  22. int swprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP,
  23. const wchar_t *restrict \fIformat\fP, ...);
  24. int wprintf(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. \fIfwprintf\fR()
  33. function shall place output on the named output
  34. .IR stream .
  35. The
  36. \fIwprintf\fR()
  37. function shall place output on the standard output stream
  38. .IR stdout .
  39. The
  40. \fIswprintf\fR()
  41. function shall place output followed by the null wide character in
  42. consecutive wide characters starting at *\fIws\fP; no more than
  43. .IR n
  44. wide characters shall be written, including a terminating null wide
  45. character, which is always added (unless
  46. .IR n
  47. is zero).
  48. .P
  49. Each of these functions shall convert, format, and print its arguments
  50. under control of the
  51. .IR format
  52. wide-character string. The
  53. .IR format
  54. is composed of zero or more directives:
  55. .IR "ordinary wide-characters" ,
  56. which are simply copied to the output stream, and
  57. .IR "conversion specifications" ,
  58. each of which results in the fetching of zero or more arguments. The
  59. results are undefined if there are insufficient arguments for the
  60. .IR format .
  61. If the
  62. .IR format
  63. is exhausted while arguments remain, the excess arguments are evaluated
  64. but are otherwise ignored.
  65. .P
  66. Conversions can be applied to the
  67. .IR n th
  68. argument after the
  69. .IR format
  70. in the argument list, rather than to the next unused argument. In this
  71. case, the conversion specifier wide character
  72. .BR %
  73. (see below) is replaced by the
  74. sequence
  75. .BR \(dq%n$\(dq ,
  76. where
  77. .IR n
  78. is a decimal integer in the range [1,{NL_ARGMAX}],
  79. giving the position of the argument in the argument list. This feature
  80. provides for the definition of
  81. .IR format
  82. wide-character strings that select arguments in an order appropriate to
  83. specific languages (see the EXAMPLES section).
  84. .P
  85. The
  86. .IR format
  87. can contain either numbered argument specifications (that is,
  88. \fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument
  89. conversion specifications (that is,
  90. .BR %
  91. and
  92. .BR * ),
  93. but not both. The only exception to this is that
  94. .BR %%
  95. can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing
  96. numbered and unnumbered argument specifications in a
  97. .IR format
  98. wide-character string are undefined. When numbered argument
  99. specifications are used, specifying the
  100. .IR N th
  101. argument requires that all the leading arguments, from the first to the
  102. (\fIN\fP\-1)th, are specified in the
  103. .IR format
  104. wide-character string.
  105. .P
  106. In
  107. .IR format
  108. wide-character strings containing the \fR"%\fIn\fR$"\fR form of
  109. conversion specification, numbered arguments in the argument list can
  110. be referenced from the
  111. .IR format
  112. wide-character string as many times as required.
  113. .P
  114. In
  115. .IR format
  116. wide-character strings containing the
  117. .BR %
  118. form of conversion specification, each argument in the argument list
  119. shall be used exactly once. It is unspecified whether an encoding
  120. error occurs if the format string contains
  121. .BR wchar_t
  122. values that do not correspond to members of the character
  123. set of the current locale and the specified semantics do not
  124. require that value to be processed by
  125. \fIwcrtomb\fR().
  126. .P
  127. All forms of the
  128. \fIfwprintf\fR()
  129. function allow for the insertion of a locale-dependent radix
  130. character in the output string, output as a wide-character value. The
  131. radix character is defined in the current locale (category
  132. .IR LC_NUMERIC ).
  133. In the POSIX locale, or in a locale where the radix character is not
  134. defined, the radix character shall default to a
  135. <period>
  136. (\c
  137. .BR '.' ).
  138. .br
  139. .P
  140. Each conversion specification is introduced by the
  141. .BR '%'
  142. wide character
  143. or by the wide-character sequence \fR"%\fIn\fR$"\fR,
  144. after which the following appear in sequence:
  145. .IP " *" 4
  146. Zero or more
  147. .IR flags
  148. (in any order), which modify the meaning of the conversion
  149. specification.
  150. .IP " *" 4
  151. An optional minimum
  152. .IR "field width" .
  153. If the converted value has fewer wide characters than the field width,
  154. it shall be padded with
  155. <space>
  156. characters by default on the left; it shall be padded on the right,
  157. if the left-adjustment flag (\c
  158. .BR '\-' ),
  159. described below, is given to the field width. The field width takes the
  160. form of an
  161. <asterisk>
  162. (\c
  163. .BR '*' ),
  164. described below, or a decimal integer.
  165. .IP " *" 4
  166. An optional
  167. .IR precision
  168. that gives the minimum number of digits to appear for the
  169. .BR d ,
  170. .BR i ,
  171. .BR o ,
  172. .BR u ,
  173. .BR x ,
  174. and
  175. .BR X
  176. conversion specifiers; the number of digits to appear after the radix
  177. character for the
  178. .BR a ,
  179. .BR A ,
  180. .BR e ,
  181. .BR E ,
  182. .BR f ,
  183. and
  184. .BR F
  185. conversion specifiers; the maximum number of significant digits for the
  186. .BR g
  187. and
  188. .BR G
  189. conversion specifiers; or the maximum number of wide characters to be
  190. printed from a string in the
  191. .BR s
  192. conversion specifiers. The precision takes the form of a
  193. <period>
  194. (\c
  195. .BR '.' )
  196. followed either by an
  197. <asterisk>
  198. (\c
  199. .BR '*' ),
  200. described below, or an optional decimal digit string, where a null
  201. digit string is treated as 0. If a precision appears with any other
  202. conversion wide character, the behavior is undefined.
  203. .IP " *" 4
  204. An optional length modifier that specifies the size of the argument.
  205. .IP " *" 4
  206. A
  207. .IR "conversion specifier"
  208. wide character that indicates the type of conversion to be applied.
  209. .P
  210. A field width, or precision, or both, may be indicated by an
  211. <asterisk>
  212. (\c
  213. .BR '*' ).
  214. In this case an argument of type
  215. .BR int
  216. supplies the field width or precision. Applications shall ensure that
  217. arguments specifying field width, or precision, or both appear in that
  218. order before the argument, if any, to be converted. A negative field
  219. width is taken as a
  220. .BR '\-'
  221. flag followed by a positive field width. A negative precision is taken
  222. as if the precision were omitted.
  223. In
  224. .IR format
  225. wide-character strings containing the \fR"%\fIn\fR$"\fR form
  226. of a conversion specification, a field width or precision may be
  227. indicated by the sequence \fR"*\fIm\fR$"\fR, where
  228. .IR m
  229. is a decimal integer in the range [1,{NL_ARGMAX}] giving the position
  230. in the argument list (after the
  231. .IR format
  232. argument) of an integer argument containing the field width or
  233. precision, for example:
  234. .sp
  235. .RS 4
  236. .nf
  237. wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); \*?
  238. .fi
  239. .P
  240. .RE
  241. .P
  242. The flag wide characters and their meanings are:
  243. .IP "\fR\(aq\fR" 8
  244. (The
  245. <apostrophe>.)
  246. The integer portion of the result of a decimal conversion (\c
  247. .BR %i ,
  248. .BR %d ,
  249. .BR %u ,
  250. .BR %f ,
  251. .BR %F ,
  252. .BR %g ,
  253. or
  254. .BR %G )
  255. shall be formatted with thousands' grouping wide characters. For other
  256. conversions, the behavior is undefined. The numeric grouping wide
  257. character is used.
  258. .IP "\fR\-\fR" 8
  259. The result of the conversion shall be left-justified within the field.
  260. The conversion shall be right-justified if this flag is not specified.
  261. .IP "\fR+\fR" 8
  262. The result of a signed conversion shall always begin with a sign (\c
  263. .BR '+'
  264. or
  265. .BR '\-' ).
  266. The conversion shall begin with a sign only when a negative value is
  267. converted if this flag is not specified.
  268. .IP <space> 8
  269. If the first wide character of a signed conversion is not a sign, or if
  270. a signed conversion results in no wide characters, a
  271. <space>
  272. shall be prefixed to the result. This means that if the
  273. <space>
  274. and
  275. .BR '+'
  276. flags both appear, the
  277. <space>
  278. flag shall be ignored.
  279. .IP "\fR#\fR" 8
  280. Specifies that the value is to be converted to an alternative form.
  281. For
  282. .BR o
  283. conversion, it shall increase the precision, if and only if necessary,
  284. to force the first digit of the result to be zero (if the value
  285. and precision are both 0, a single 0 is printed). For
  286. .BR x
  287. or
  288. .BR X
  289. conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed
  290. to it. For
  291. .BR a ,
  292. .BR A ,
  293. .BR e ,
  294. .BR E ,
  295. .BR f ,
  296. .BR F ,
  297. .BR g ,
  298. and
  299. .BR G
  300. conversion specifiers, the result shall always contain a radix
  301. character, even if no digits follow it. Without this flag, a radix
  302. character appears in the result of these conversions only if a digit
  303. follows it. For
  304. .BR g
  305. and
  306. .BR G
  307. conversion specifiers, trailing zeros shall
  308. .IR not
  309. be removed from the result as they normally are. For other conversion
  310. specifiers, the behavior is undefined.
  311. .IP "\fR0\fR" 8
  312. For
  313. .BR d ,
  314. .BR i ,
  315. .BR o ,
  316. .BR u ,
  317. .BR x ,
  318. .BR X ,
  319. .BR a ,
  320. .BR A ,
  321. .BR e ,
  322. .BR E ,
  323. .BR f ,
  324. .BR F ,
  325. .BR g ,
  326. and
  327. .BR G
  328. conversion specifiers, leading zeros (following any indication of sign
  329. or base) are used to pad to the field width rather than performing
  330. space padding, except when converting an infinity or NaN. If the
  331. .BR '0'
  332. and
  333. .BR '\-'
  334. flags both appear, the
  335. .BR '0'
  336. flag shall be ignored. For
  337. .BR d ,
  338. .BR i ,
  339. .BR o ,
  340. .BR u ,
  341. .BR x ,
  342. and
  343. .BR X
  344. conversion specifiers, if a precision is specified, the
  345. .BR '0'
  346. flag shall be ignored.
  347. If the
  348. .BR '0'
  349. and
  350. <apostrophe>
  351. flags both appear, the grouping wide characters are inserted before
  352. zero padding. For other conversions, the behavior is undefined.
  353. .P
  354. The length modifiers and their meanings are:
  355. .IP "\fRhh\fR" 8
  356. Specifies that a following
  357. .BR d ,
  358. .BR i ,
  359. .BR o ,
  360. .BR u ,
  361. .BR x ,
  362. or
  363. .BR X
  364. conversion specifier applies to a
  365. .BR "signed char"
  366. or
  367. .BR "unsigned char"
  368. argument (the argument will have been promoted according to the integer
  369. promotions, but its value shall be converted to
  370. .BR "signed char"
  371. or
  372. .BR "unsigned char"
  373. before printing); or that a following
  374. .BR n
  375. conversion specifier applies to a pointer to a
  376. .BR "signed char"
  377. argument.
  378. .IP "\fRh\fR" 8
  379. Specifies that a following
  380. .BR d ,
  381. .BR i ,
  382. .BR o ,
  383. .BR u ,
  384. .BR x ,
  385. or
  386. .BR X
  387. conversion specifier applies to a
  388. .BR "short"
  389. or
  390. .BR "unsigned short"
  391. argument (the argument will have been promoted according to the integer
  392. promotions, but its value shall be converted to
  393. .BR "short"
  394. or
  395. .BR "unsigned short"
  396. before printing); or that a following
  397. .BR n
  398. conversion specifier applies to a pointer to a
  399. .BR "short"
  400. argument.
  401. .IP "\fRl\fR\ (ell)" 8
  402. Specifies that a following
  403. .BR d ,
  404. .BR i ,
  405. .BR o ,
  406. .BR u ,
  407. .BR x ,
  408. or
  409. .BR X
  410. conversion specifier applies to a
  411. .BR "long"
  412. or
  413. .BR "unsigned long"
  414. argument; that a following
  415. .BR n
  416. conversion specifier applies to a pointer to a
  417. .BR "long"
  418. argument; that a following
  419. .BR c
  420. conversion specifier applies to a
  421. .BR wint_t
  422. argument; that a following
  423. .BR s
  424. conversion specifier applies to a pointer to a
  425. .BR wchar_t
  426. argument; or has no effect on a following
  427. .BR a ,
  428. .BR A ,
  429. .BR e ,
  430. .BR E ,
  431. .BR f ,
  432. .BR F ,
  433. .BR g ,
  434. or
  435. .BR G
  436. conversion specifier.
  437. .IP "\fRll\fR\ (ell-ell)" 8
  438. .br
  439. Specifies that a following
  440. .BR d ,
  441. .BR i ,
  442. .BR o ,
  443. .BR u ,
  444. .BR x ,
  445. or
  446. .BR X
  447. conversion specifier applies to a
  448. .BR "long long"
  449. or
  450. .BR "unsigned long long"
  451. argument; or that a following
  452. .BR n
  453. conversion specifier applies to a pointer to a
  454. .BR "long long"
  455. argument.
  456. .IP "\fRj\fR" 8
  457. Specifies that a following
  458. .BR d ,
  459. .BR i ,
  460. .BR o ,
  461. .BR u ,
  462. .BR x ,
  463. or
  464. .BR X
  465. conversion specifier applies to an
  466. .BR intmax_t
  467. or
  468. .BR uintmax_t
  469. argument; or that a following
  470. .BR n
  471. conversion specifier applies to a pointer to an
  472. .BR intmax_t
  473. argument.
  474. .IP "\fRz\fR" 8
  475. Specifies that a following
  476. .BR d ,
  477. .BR i ,
  478. .BR o ,
  479. .BR u ,
  480. .BR x ,
  481. or
  482. .BR X
  483. conversion specifier applies to a
  484. .BR size_t
  485. or the corresponding signed integer type argument; or that a following
  486. .BR n
  487. conversion specifier applies to a pointer to a signed integer type
  488. corresponding to a
  489. .BR size_t
  490. argument.
  491. .IP "\fRt\fR" 8
  492. Specifies that a following
  493. .BR d ,
  494. .BR i ,
  495. .BR o ,
  496. .BR u ,
  497. .BR x ,
  498. or
  499. .BR X
  500. conversion specifier applies to a
  501. .BR ptrdiff_t
  502. or the corresponding
  503. .BR unsigned
  504. type argument; or that a following
  505. .BR n
  506. conversion specifier applies to a pointer to a
  507. .BR ptrdiff_t
  508. argument.
  509. .IP "\fRL\fR" 8
  510. Specifies that a following
  511. .BR a ,
  512. .BR A ,
  513. .BR e ,
  514. .BR E ,
  515. .BR f ,
  516. .BR F ,
  517. .BR g ,
  518. or
  519. .BR G
  520. conversion specifier applies to a
  521. .BR "long double"
  522. argument.
  523. .br
  524. .P
  525. If a length modifier appears with any conversion specifier other than
  526. as specified above, the behavior is undefined.
  527. .P
  528. The conversion specifiers and their meanings are:
  529. .IP "\fRd\fR,\ \fRi\fR" 8
  530. The
  531. .BR int
  532. argument shall be converted to a signed decimal in the style
  533. \fR"[\-]\fIdddd"\fR. The precision specifies the minimum number of
  534. digits to appear; if the value being converted can be represented in
  535. fewer digits, it shall be expanded with leading zeros. The default
  536. precision shall be 1. The result of converting zero with an explicit
  537. precision of zero shall be no wide characters.
  538. .IP "\fRo\fP" 8
  539. The
  540. .BR unsigned
  541. argument shall be converted to unsigned octal format in the style
  542. .BR \(dqdddd\(dq .
  543. The precision specifies the minimum number of digits to appear; if the
  544. value being converted can be represented in fewer digits, it shall be
  545. expanded with leading zeros. The default precision shall be 1. The
  546. result of converting zero with an explicit precision of zero shall be
  547. no wide characters.
  548. .IP "\fRu\fP" 8
  549. The
  550. .BR unsigned
  551. argument shall be converted to unsigned decimal format in the style
  552. .BR \(dqdddd\(dq .
  553. The precision specifies the minimum number of digits to appear; if the
  554. value being converted can be represented in fewer digits, it shall be
  555. expanded with leading zeros. The default precision shall be 1. The
  556. result of converting zero with an explicit precision of zero shall be
  557. no wide characters.
  558. .IP "\fRx\fP" 8
  559. The
  560. .BR unsigned
  561. argument shall be converted to unsigned hexadecimal format in the style
  562. .BR \(dqdddd\(dq ;
  563. the letters
  564. .BR \(dqabcdef\(dq
  565. are used. The precision specifies the minimum number of digits to
  566. appear; if the value being converted can be represented in fewer
  567. digits, it shall be expanded with leading zeros. The default precision
  568. shall be 1. The result of converting zero with an explicit precision of
  569. zero shall be no wide characters.
  570. .IP "\fRX\fP" 8
  571. Equivalent to the
  572. .BR x
  573. conversion specifier, except that letters
  574. .BR \(dqABCDEF\(dq
  575. are used instead of
  576. .BR \(dqabcdef\(dq .
  577. .IP "\fRf\fR,\ \fRF\fR" 8
  578. The
  579. .BR double
  580. argument shall be converted to decimal notation in the style
  581. \fR"[\-]\fIddd.ddd"\fR, where the number of digits after the radix
  582. character shall be equal to the precision specification. If the
  583. precision is missing, it shall be taken as 6; if the precision is
  584. explicitly zero and no
  585. .BR '#'
  586. flag is present, no radix character shall appear. If a radix character
  587. appears, at least one digit shall appear before it. The value shall be
  588. rounded in an implementation-defined manner to the appropriate number
  589. of digits.
  590. .RS 8
  591. .P
  592. A
  593. .BR double
  594. argument representing an infinity shall be converted in one of the
  595. styles
  596. .BR \(dq[-]inf\(dq
  597. or
  598. .BR \(dq[-]infinity\(dq ;
  599. which style is implementation-defined. A
  600. .BR double
  601. argument representing a NaN shall be converted in one of the styles
  602. .BR \(dq[-]nan\(dq
  603. or \fR"[\-]nan(\fIn-char-sequence\fR)"\fR; which style, and the
  604. meaning of any \fIn-char-sequence\fR, is implementation-defined. The
  605. .BR F
  606. conversion specifier produces
  607. .BR \(dqINF\(dq ,
  608. .BR \(dqINFINITY\(dq ,
  609. or
  610. .BR \(dqNAN\(dq
  611. instead of
  612. .BR \(dqinf\(dq ,
  613. .BR \(dqinfinity\(dq ,
  614. or
  615. .BR \(dqnan\(dq ,
  616. respectively.
  617. .RE
  618. .IP "\fRe\fR,\ \fRE\fR" 8
  619. The
  620. .BR double
  621. argument shall be converted in the style
  622. \fR"[\-]\fId.ddd\fRe\fR\(+-dd"\fR, where there shall be one digit
  623. before the radix character (which is non-zero if the argument is
  624. non-zero) and the number of digits after it shall be equal to the
  625. precision; if the precision is missing, it shall be taken as 6; if the
  626. precision is zero and no
  627. .BR '#'
  628. flag is present, no radix character shall appear. The value shall be
  629. rounded in an implementation-defined manner to the appropriate number
  630. of digits. The
  631. .BR E
  632. conversion wide character shall produce a number with
  633. .BR 'E'
  634. instead of
  635. .BR 'e'
  636. introducing the exponent. The exponent shall always contain at least
  637. two digits. If the value is zero, the exponent shall be zero.
  638. .RS 8
  639. .P
  640. A
  641. .BR double
  642. argument representing an infinity or NaN shall be converted in the
  643. style of an
  644. .BR f
  645. or
  646. .BR F
  647. conversion specifier.
  648. .RE
  649. .IP "\fRg\fR,\ \fRG\fR" 8
  650. The
  651. .BR double
  652. argument representing a floating-point number shall be converted in the
  653. style
  654. .BR f
  655. or
  656. .BR e
  657. (or in the style
  658. .BR F
  659. or
  660. .BR E
  661. in the case of a
  662. .BR G
  663. conversion specifier), depending on the value converted and the precision.
  664. Let
  665. .BR P
  666. equal the precision if non-zero, 6 if the precision is omitted, or 1 if the
  667. precision is zero. Then, if a conversion with style
  668. .BR E
  669. would have an exponent of
  670. .IR X :
  671. .RS 8
  672. .IP -- 4
  673. If
  674. .BR P >\c
  675. .IR X \(>=\-4,
  676. the conversion shall be with style
  677. .BR f
  678. (or
  679. .BR F )
  680. and precision
  681. .BR P \-(\c
  682. .IR X +1).
  683. .IP -- 4
  684. Otherwise, the conversion shall be with style
  685. .BR e
  686. (or
  687. .BR E )
  688. and precision
  689. .BR P \-1.
  690. .P
  691. Finally, unless the
  692. .BR '#'
  693. flag is used, any trailing zeros shall be removed from the fractional
  694. portion of the result and the decimal-point character shall be removed
  695. if there is no fractional portion remaining.
  696. .P
  697. A
  698. .BR double
  699. argument representing an infinity or NaN shall be converted in the
  700. style of an
  701. .BR f
  702. or
  703. .BR F
  704. conversion specifier.
  705. .RE
  706. .IP "\fRa\fR,\ \fRA\fR" 8
  707. A
  708. .BR double
  709. argument representing a floating-point number shall be converted in
  710. the style \fR"[\-]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there
  711. shall be one hexadecimal digit (which is non-zero if the argument is a
  712. normalized floating-point number and is otherwise unspecified) before
  713. the decimal-point wide character and the number of hexadecimal digits
  714. after it shall be equal to the precision; if the precision is missing
  715. and FLT_RADIX is a power of 2, then the precision shall be sufficient
  716. for an exact representation of the value; if the precision is missing
  717. and FLT_RADIX is not a power of 2, then the precision shall be sufficient
  718. to distinguish values of type
  719. .BR double ,
  720. except that trailing zeros may be omitted; if the precision is zero and
  721. the
  722. .BR '#'
  723. flag is not specified, no decimal-point wide character shall appear.
  724. The letters
  725. .BR \(dqabcdef\(dq
  726. are used for
  727. .BR a
  728. conversion and the letters
  729. .BR \(dqABCDEF\(dq
  730. for
  731. .BR A
  732. conversion. The
  733. .BR A
  734. conversion specifier produces a number with
  735. .BR 'X'
  736. and
  737. .BR 'P'
  738. instead of
  739. .BR 'x'
  740. and
  741. .BR 'p' .
  742. The exponent shall always contain at least one digit, and only as many
  743. more digits as necessary to represent the decimal exponent of 2. If the
  744. value is zero, the exponent shall be zero.
  745. .RS 8
  746. .P
  747. A
  748. .BR double
  749. argument representing an infinity or NaN shall be converted in the
  750. style of an
  751. .BR f
  752. or
  753. .BR F
  754. conversion specifier.
  755. .RE
  756. .IP "\fRc\fP" 8
  757. If no
  758. .BR l
  759. (ell) qualifier is present, the
  760. .BR int
  761. argument shall be converted to a wide character as if by calling the
  762. \fIbtowc\fR()
  763. function and the resulting wide character shall be written. Otherwise,
  764. the
  765. .BR wint_t
  766. argument shall be converted to
  767. .BR wchar_t ,
  768. and written.
  769. .IP "\fRs\fP" 8
  770. If no
  771. .BR l
  772. (ell) qualifier is present, the application shall ensure that the
  773. argument is a pointer to a character array containing a character
  774. sequence beginning in the initial shift state. Characters from the
  775. array shall be converted as if by repeated calls to the
  776. \fImbrtowc\fR()
  777. function, with the conversion state described by an
  778. .BR mbstate_t
  779. object initialized to zero before the first character is converted, and
  780. written up to (but not including) the terminating null wide character.
  781. If the precision is specified, no more than that many wide characters
  782. shall be written. If the precision is not specified, or is greater than
  783. the size of the array, the application shall ensure that the array
  784. contains a null wide character.
  785. .RS 8
  786. .P
  787. If an
  788. .BR l
  789. (ell) qualifier is present, the application shall ensure that the
  790. argument is a pointer to an array of type
  791. .BR wchar_t .
  792. Wide characters from the array shall be written up to (but not
  793. including) a terminating null wide character. If no precision is
  794. specified, or is greater than the size of the array, the application
  795. shall ensure that the array contains a null wide character. If a
  796. precision is specified, no more than that many wide characters shall be
  797. written.
  798. .RE
  799. .IP "\fRp\fP" 8
  800. The application shall ensure that the argument is a pointer to
  801. .BR void .
  802. The value of the pointer shall be converted to a sequence of printable
  803. wide characters in an implementation-defined manner.
  804. .IP "\fRn\fP" 8
  805. The application shall ensure that the argument is a pointer to an
  806. integer into which is written the number of wide characters written to
  807. the output so far by this call to one of the
  808. \fIfwprintf\fR()
  809. functions. No argument shall be converted, but one shall be consumed.
  810. If the conversion specification includes any flags, a field width, or a
  811. precision, the behavior is undefined.
  812. .IP "\fRC\fP" 8
  813. Equivalent to
  814. .BR lc .
  815. .IP "\fRS\fP" 8
  816. Equivalent to
  817. .BR ls .
  818. .IP "\fR%\fR" 8
  819. Output a
  820. .BR '%'
  821. wide character; no argument shall be converted. The entire conversion
  822. specification shall be
  823. .BR %% .
  824. .P
  825. If a conversion specification does not match one of the above forms,
  826. the behavior is undefined.
  827. .P
  828. In no case does a nonexistent or small field width cause truncation of
  829. a field; if the result of a conversion is wider than the field width,
  830. the field shall be expanded to contain the conversion result.
  831. Characters generated by
  832. \fIfwprintf\fR()
  833. and
  834. \fIwprintf\fR()
  835. shall be printed as if
  836. \fIfputwc\fR()
  837. had been called.
  838. .P
  839. For
  840. .BR a
  841. and
  842. .BR A
  843. conversions, if FLT_RADIX is not a power of 2 and the result is not
  844. exactly representable in the given precision, the result should be one
  845. of the two adjacent numbers in hexadecimal floating style with the
  846. given precision, with the extra stipulation that the error should have
  847. a correct sign for the current rounding direction.
  848. .P
  849. For
  850. .BR e ,
  851. .BR E ,
  852. .BR f ,
  853. .BR F ,
  854. .BR g ,
  855. and
  856. .BR G
  857. conversion specifiers, if the number of significant decimal digits is
  858. at most DECIMAL_DIG, then the result should be correctly rounded. If
  859. the number of significant decimal digits is more than DECIMAL_DIG but
  860. the source value is exactly representable with DECIMAL_DIG digits, then
  861. the result should be an exact representation with trailing zeros.
  862. Otherwise, the source value is bounded by two adjacent decimal strings
  863. .IR L
  864. <
  865. .IR U ,
  866. both having DECIMAL_DIG significant digits; the value of the resultant
  867. decimal string
  868. .IR D
  869. should satisfy
  870. .IR L
  871. <=
  872. .IR D
  873. <=
  874. .IR U ,
  875. with the extra stipulation that the error should have a correct sign
  876. for the current rounding direction.
  877. .P
  878. The last data modification and last file status change timestamps
  879. of the file shall be marked for update between the call to a
  880. successful execution of
  881. \fIfwprintf\fR()
  882. or
  883. \fIwprintf\fR()
  884. and the next successful completion of a call to
  885. \fIfflush\fR()
  886. or
  887. \fIfclose\fR()
  888. on the same stream, or a call to
  889. \fIexit\fR()
  890. or
  891. \fIabort\fR().
  892. .SH "RETURN VALUE"
  893. Upon successful completion, these functions shall return the number of
  894. wide characters transmitted, excluding the terminating null wide character
  895. in the case of
  896. \fIswprintf\fR(),
  897. or a negative value if an output error was encountered,
  898. and set
  899. .IR errno
  900. to indicate the error.
  901. .P
  902. If
  903. .IR n
  904. or more wide characters were requested to be written,
  905. \fIswprintf\fR()
  906. shall return a negative value,
  907. and set
  908. .IR errno
  909. to indicate the error.
  910. .SH ERRORS
  911. For the conditions under which
  912. \fIfwprintf\fR()
  913. and
  914. \fIwprintf\fR()
  915. fail and may fail, refer to
  916. .IR "\fIfputwc\fR\^(\|)".
  917. .P
  918. In addition, all forms of
  919. \fIfwprintf\fR()
  920. shall fail if:
  921. .TP
  922. .BR EILSEQ
  923. A wide-character code that does not correspond to a valid character has
  924. been detected.
  925. .P
  926. In addition,
  927. \fIfwprintf\fR()
  928. and
  929. \fIwprintf\fR()
  930. may fail if:
  931. .TP
  932. .BR ENOMEM
  933. Insufficient storage space is available.
  934. .P
  935. The
  936. \fIswprintf\fR()
  937. shall fail if:
  938. .TP
  939. .BR EOVERFLOW
  940. The value of
  941. .IR n
  942. is greater than
  943. {INT_MAX}
  944. or the number of bytes needed to hold the output excluding the
  945. terminating null is greater than
  946. {INT_MAX}.
  947. .LP
  948. .IR "The following sections are informative."
  949. .SH "EXAMPLES"
  950. To print the language-independent date and time format, the following
  951. statement could be used:
  952. .sp
  953. .RS 4
  954. .nf
  955. wprintf(format, weekday, month, day, hour, min);
  956. .fi
  957. .P
  958. .RE
  959. .P
  960. For American usage,
  961. .IR format
  962. could be a pointer to the wide-character string:
  963. .sp
  964. .RS 4
  965. .nf
  966. L"%s, %s %d, %d:%.2d\en"
  967. .fi
  968. .P
  969. .RE
  970. .P
  971. producing the message:
  972. .sp
  973. .RS 4
  974. .nf
  975. Sunday, July 3, 10:02
  976. .fi
  977. .P
  978. .RE
  979. .P
  980. whereas for German usage,
  981. .IR format
  982. could be a pointer to the wide-character string:
  983. .sp
  984. .RS 4
  985. .nf
  986. L"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
  987. .fi
  988. .P
  989. .RE
  990. .P
  991. producing the message:
  992. .sp
  993. .RS 4
  994. .nf
  995. Sonntag, 3. Juli, 10:02
  996. .fi
  997. .P
  998. .RE
  999. .SH "APPLICATION USAGE"
  1000. None.
  1001. .SH RATIONALE
  1002. If an implementation detects that there are insufficient
  1003. arguments for the format, it is recommended that the function
  1004. should fail and report an
  1005. .BR [EINVAL]
  1006. error.
  1007. .SH "FUTURE DIRECTIONS"
  1008. None.
  1009. .SH "SEE ALSO"
  1010. .IR "Section 2.5" ", " "Standard I/O Streams",
  1011. .IR "\fIbtowc\fR\^(\|)",
  1012. .IR "\fIfputwc\fR\^(\|)",
  1013. .IR "\fIfwscanf\fR\^(\|)",
  1014. .IR "\fImbrtowc\fR\^(\|)",
  1015. .IR "\fIsetlocale\fR\^(\|)"
  1016. .P
  1017. The Base Definitions volume of POSIX.1\(hy2017,
  1018. .IR "Chapter 7" ", " "Locale",
  1019. .IR "\fB<inttypes.h>\fP",
  1020. .IR "\fB<stdio.h>\fP",
  1021. .IR "\fB<wchar.h>\fP"
  1022. .\"
  1023. .SH COPYRIGHT
  1024. Portions of this text are reprinted and reproduced in electronic form
  1025. from IEEE Std 1003.1-2017, Standard for Information Technology
  1026. -- Portable Operating System Interface (POSIX), The Open Group Base
  1027. Specifications Issue 7, 2018 Edition,
  1028. Copyright (C) 2018 by the Institute of
  1029. Electrical and Electronics Engineers, Inc and The Open Group.
  1030. In the event of any discrepancy between this version and the original IEEE and
  1031. The Open Group Standard, the original IEEE and The Open Group Standard
  1032. is the referee document. The original Standard can be obtained online at
  1033. http://www.opengroup.org/unix/online.html .
  1034. .PP
  1035. Any typographical or formatting errors that appear
  1036. in this page are most likely
  1037. to have been introduced during the conversion of the source files to
  1038. man page format. To report such errors, see
  1039. https://www.kernel.org/doc/man-pages/reporting_bugs.html .