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

fprintf.3p (36130B)


  1. '\" et
  2. .TH FPRINTF "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. dprintf,
  12. fprintf,
  13. printf,
  14. snprintf,
  15. sprintf
  16. \(em print formatted output
  17. .SH SYNOPSIS
  18. .LP
  19. .nf
  20. #include <stdio.h>
  21. .P
  22. int dprintf(int \fIfildes\fP, const char *restrict \fIformat\fP, ...);
  23. int fprintf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, ...);
  24. int printf(const char *restrict \fIformat\fP, ...);
  25. int snprintf(char *restrict \fIs\fP, size_t \fIn\fP,
  26. const char *restrict \fIformat\fP, ...);
  27. int sprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...);
  28. .fi
  29. .SH DESCRIPTION
  30. Excluding
  31. \fIdprintf\fR():
  32. The functionality described on this reference page is aligned with the
  33. ISO\ C standard. Any conflict between the requirements described here and the
  34. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  35. .P
  36. The
  37. \fIfprintf\fR()
  38. function shall place output on the named output
  39. .IR stream .
  40. The
  41. \fIprintf\fR()
  42. function shall place output on the standard output stream
  43. .IR stdout .
  44. The
  45. \fIsprintf\fR()
  46. function shall place output followed by the null byte,
  47. .BR '\e0' ,
  48. in consecutive bytes starting at *\fIs\fP; it is the user's
  49. responsibility to ensure that enough space is available.
  50. .P
  51. The
  52. \fIdprintf\fR()
  53. function shall be equivalent to the
  54. \fIfprintf\fR()
  55. function, except that
  56. \fIdprintf\fR()
  57. shall write output to the file associated with the file descriptor
  58. specified by the
  59. .IR fildes
  60. argument rather than place output on a stream.
  61. .P
  62. The
  63. \fIsnprintf\fR()
  64. function shall be equivalent to
  65. \fIsprintf\fR(),
  66. with the addition of the
  67. .IR n
  68. argument which states the size of the buffer referred to by
  69. .IR s .
  70. If
  71. .IR n
  72. is zero, nothing shall be written and
  73. .IR s
  74. may be a null pointer. Otherwise, output bytes beyond the
  75. .IR n \(hy1st
  76. shall be discarded instead of being written to the array, and a null
  77. byte is written at the end of the bytes actually written into the
  78. array.
  79. .P
  80. If copying takes place between objects that overlap as a result of a
  81. call to
  82. \fIsprintf\fR()
  83. or
  84. \fIsnprintf\fR(),
  85. the results are undefined.
  86. .P
  87. Each of these functions converts, formats, and prints its arguments
  88. under control of the
  89. .IR format .
  90. The
  91. .IR format
  92. is a character string, beginning and ending in its initial shift state,
  93. if any. The
  94. .IR format
  95. is composed of zero or more directives:
  96. .IR "ordinary characters" ,
  97. which are simply copied to the output stream, and
  98. .IR "conversion specifications" ,
  99. each of which shall result in the fetching of zero or more arguments.
  100. The results are undefined if there are insufficient arguments for the
  101. .IR format .
  102. If the
  103. .IR format
  104. is exhausted while arguments remain, the excess arguments shall be
  105. evaluated but are otherwise ignored.
  106. .P
  107. Conversions can be applied to the
  108. .IR n th
  109. argument after the
  110. .IR format
  111. in the argument list, rather than to the next unused argument. In this
  112. case, the conversion specifier character
  113. .BR %
  114. (see below) is replaced by the sequence \fR"%\fIn\fR$"\fR, where
  115. .IR n
  116. is a decimal integer in the range [1,{NL_ARGMAX}],
  117. giving the position of the argument in the argument list. This feature
  118. provides for the definition of format strings that select arguments in
  119. an order appropriate to specific languages (see the EXAMPLES section).
  120. .P
  121. The
  122. .IR format
  123. can contain either numbered argument conversion specifications (that
  124. is, \fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument
  125. conversion specifications (that is,
  126. .BR %
  127. and
  128. .BR * ),
  129. but not both. The only exception to this is that
  130. .BR %%
  131. can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing
  132. numbered and unnumbered argument specifications in a
  133. .IR format
  134. string are undefined. When numbered argument specifications are used,
  135. specifying the
  136. .IR N th
  137. argument requires that all the leading arguments, from the first to the
  138. (\fIN\-1\fP)th, are specified in the format string.
  139. .P
  140. In format strings containing the \fR"%\fIn\fR$"\fR form of conversion
  141. specification, numbered arguments in the argument list can be
  142. referenced from the format string as many times as required.
  143. .P
  144. In format strings containing the
  145. .BR %
  146. form of conversion specification, each conversion specification uses
  147. the first unused argument in the argument list.
  148. .P
  149. All forms of the
  150. \fIfprintf\fR()
  151. functions allow for the insertion of a language-dependent radix
  152. character in the output string. The radix character is defined in the
  153. current locale (category
  154. .IR LC_NUMERIC ).
  155. In the POSIX locale, or in a locale where the radix character is not
  156. defined, the radix character shall default to a
  157. <period>
  158. (\c
  159. .BR '.' ).
  160. .P
  161. Each conversion specification is introduced by the
  162. .BR '%'
  163. character
  164. or by the character sequence \fR"%\fIn\fR$"\fR,
  165. after which the following appear in sequence:
  166. .IP " *" 4
  167. Zero or more
  168. .IR flags
  169. (in any order), which modify the meaning of the conversion
  170. specification.
  171. .IP " *" 4
  172. An optional minimum
  173. .IR "field width" .
  174. If the converted value has fewer bytes than the field width, it shall
  175. be padded with
  176. <space>
  177. characters by default on the left; it shall be padded on the right if
  178. the left-adjustment flag (\c
  179. .BR '\-' ),
  180. described below, is given to the field width. The field width takes the
  181. form of an
  182. <asterisk>
  183. (\c
  184. .BR '*' ),
  185. described below, or a decimal integer.
  186. .IP " *" 4
  187. An optional
  188. .IR precision
  189. that gives the minimum number of digits to appear for the
  190. .BR d ,
  191. .BR i ,
  192. .BR o ,
  193. .BR u ,
  194. .BR x ,
  195. and
  196. .BR X
  197. conversion specifiers; the number of digits to appear after the radix
  198. character for the
  199. .BR a ,
  200. .BR A ,
  201. .BR e ,
  202. .BR E ,
  203. .BR f ,
  204. and
  205. .BR F
  206. conversion specifiers; the maximum number of significant digits for the
  207. .BR g
  208. and
  209. .BR G
  210. conversion specifiers; or the maximum number of bytes to be printed
  211. from a string in the
  212. .BR s
  213. and
  214. .BR S
  215. conversion specifiers. The precision takes the form of a
  216. <period>
  217. (\c
  218. .BR '.' )
  219. followed either by an
  220. <asterisk>
  221. (\c
  222. .BR '*' ),
  223. described below, or an optional decimal digit string, where a null
  224. digit string is treated as zero. If a precision appears with any other
  225. conversion specifier, the behavior is undefined.
  226. .IP " *" 4
  227. An optional length modifier that specifies the size of the argument.
  228. .IP " *" 4
  229. A
  230. .IR "conversion specifier"
  231. character that indicates the type of conversion to be applied.
  232. .P
  233. A field width, or precision, or both, may be indicated by an
  234. <asterisk>
  235. (\c
  236. .BR '*' ).
  237. In this case an argument of type
  238. .BR int
  239. supplies the field width or precision. Applications shall ensure that
  240. arguments specifying field width, or precision, or both appear in that
  241. order before the argument, if any, to be converted. A negative field
  242. width is taken as a
  243. .BR '\-'
  244. flag followed by a positive field width. A negative precision is taken
  245. as if the precision were omitted.
  246. In
  247. .IR format
  248. strings containing the \fR"%\fIn\fR$"\fR form of a
  249. conversion specification, a field width or precision may be indicated
  250. by the sequence \fR"*\fIm\fR$"\fR, where
  251. .IR m
  252. is a decimal integer in the range [1,{NL_ARGMAX}] giving the position
  253. in the argument list (after the
  254. .IR format
  255. argument) of an integer argument containing the field width or
  256. precision, for example:
  257. .sp
  258. .RS 4
  259. .nf
  260. printf("%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec);
  261. .fi
  262. .P
  263. .RE
  264. .P
  265. The flag characters and their meanings are:
  266. .IP "\fR\(aq\fR" 8
  267. (The
  268. <apostrophe>.)
  269. The integer portion of the result of a decimal conversion (\c
  270. .BR %i ,
  271. .BR %d ,
  272. .BR %u ,
  273. .BR %f ,
  274. .BR %F ,
  275. .BR %g ,
  276. or
  277. .BR %G )
  278. shall be formatted with thousands' grouping characters. For other
  279. conversions the behavior is undefined. The non-monetary grouping
  280. character is used.
  281. .IP "\fR\-\fR" 8
  282. The result of the conversion shall be left-justified within the field.
  283. The conversion is right-justified if this flag is not specified.
  284. .IP "\fR+\fR" 8
  285. The result of a signed conversion shall always begin with a sign (\c
  286. .BR '+'
  287. or
  288. .BR '\-' ).
  289. The conversion shall begin with a sign only when a negative value is
  290. converted if this flag is not specified.
  291. .IP <space> 8
  292. If the first character of a signed conversion is not a sign or if a
  293. signed conversion results in no characters, a
  294. <space>
  295. shall be prefixed to the result. This means that if the
  296. <space>
  297. and
  298. .BR '+'
  299. flags both appear, the
  300. <space>
  301. flag shall be ignored.
  302. .IP "\fR#\fR" 8
  303. Specifies that the value is to be converted to an alternative
  304. form. For
  305. .BR o
  306. conversion, it shall increase the precision, if and only if necessary,
  307. to force the first digit of the result to be a zero (if the value
  308. and precision are both 0, a single 0 is printed). For
  309. .BR x
  310. or
  311. .BR X
  312. conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed
  313. to it. For
  314. .BR a ,
  315. .BR A ,
  316. .BR e ,
  317. .BR E ,
  318. .BR f ,
  319. .BR F ,
  320. .BR g ,
  321. and
  322. .BR G
  323. conversion specifiers, the result shall always contain a radix
  324. character, even if no digits follow the radix character. Without this
  325. flag, a radix character appears in the result of these conversions only
  326. if a digit follows it. For
  327. .BR g
  328. and
  329. .BR G
  330. conversion specifiers, trailing zeros shall
  331. .IR not
  332. be removed from the result as they normally are. For other conversion
  333. specifiers, the behavior is undefined.
  334. .IP "\fR0\fR" 8
  335. For
  336. .BR d ,
  337. .BR i ,
  338. .BR o ,
  339. .BR u ,
  340. .BR x ,
  341. .BR X ,
  342. .BR a ,
  343. .BR A ,
  344. .BR e ,
  345. .BR E ,
  346. .BR f ,
  347. .BR F ,
  348. .BR g ,
  349. and
  350. .BR G
  351. conversion specifiers, leading zeros (following any indication of sign
  352. or base) are used to pad to the field width rather than performing
  353. space padding, except when converting an infinity or NaN. If the
  354. .BR '0'
  355. and
  356. .BR '\-'
  357. flags both appear, the
  358. .BR '0'
  359. flag is ignored. For
  360. .BR d ,
  361. .BR i ,
  362. .BR o ,
  363. .BR u ,
  364. .BR x ,
  365. and
  366. .BR X
  367. conversion specifiers, if a precision is specified, the
  368. .BR '0'
  369. flag shall be ignored.
  370. If the
  371. .BR '0'
  372. and
  373. <apostrophe>
  374. flags both appear, the grouping characters are inserted before zero
  375. padding. For other conversions, the behavior is undefined.
  376. .P
  377. The length modifiers and their meanings are:
  378. .IP "\fRhh\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 "signed char"
  389. or
  390. .BR "unsigned char"
  391. argument (the argument will have been promoted according to the integer
  392. promotions, but its value shall be converted to
  393. .BR "signed char"
  394. or
  395. .BR "unsigned char"
  396. before printing); or that a following
  397. .BR n
  398. conversion specifier applies to a pointer to a
  399. .BR "signed char"
  400. argument.
  401. .IP "\fRh\fR" 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 "short"
  412. or
  413. .BR "unsigned short"
  414. argument (the argument will have been promoted according to the integer
  415. promotions, but its value shall be converted to
  416. .BR "short"
  417. or
  418. .BR "unsigned short"
  419. before printing); or that a following
  420. .BR n
  421. conversion specifier applies to a pointer to a
  422. .BR "short"
  423. argument.
  424. .IP "\fRl\fR\ (ell)" 8
  425. Specifies that a following
  426. .BR d ,
  427. .BR i ,
  428. .BR o ,
  429. .BR u ,
  430. .BR x ,
  431. or
  432. .BR X
  433. conversion specifier applies to a
  434. .BR "long"
  435. or
  436. .BR "unsigned long"
  437. argument; that a following
  438. .BR n
  439. conversion specifier applies to a pointer to a
  440. .BR "long"
  441. argument; that a following
  442. .BR c
  443. conversion specifier applies to a
  444. .BR wint_t
  445. argument; that a following
  446. .BR s
  447. conversion specifier applies to a pointer to a
  448. .BR wchar_t
  449. argument; or has no effect on a following
  450. .BR a ,
  451. .BR A ,
  452. .BR e ,
  453. .BR E ,
  454. .BR f ,
  455. .BR F ,
  456. .BR g ,
  457. or
  458. .BR G
  459. conversion specifier.
  460. .IP "\fRll\fR\ (ell-ell)" 8
  461. .br
  462. Specifies that a following
  463. .BR d ,
  464. .BR i ,
  465. .BR o ,
  466. .BR u ,
  467. .BR x ,
  468. or
  469. .BR X
  470. conversion specifier applies to a
  471. .BR "long long"
  472. or
  473. .BR "unsigned long long"
  474. argument; or that a following
  475. .BR n
  476. conversion specifier applies to a pointer to a
  477. .BR "long long"
  478. argument.
  479. .IP "\fRj\fR" 8
  480. Specifies that a following
  481. .BR d ,
  482. .BR i ,
  483. .BR o ,
  484. .BR u ,
  485. .BR x ,
  486. or
  487. .BR X
  488. conversion specifier applies to an
  489. .BR intmax_t
  490. or
  491. .BR uintmax_t
  492. argument; or that a following
  493. .BR n
  494. conversion specifier applies to a pointer to an
  495. .BR intmax_t
  496. argument.
  497. .IP "\fRz\fR" 8
  498. Specifies that a following
  499. .BR d ,
  500. .BR i ,
  501. .BR o ,
  502. .BR u ,
  503. .BR x ,
  504. or
  505. .BR X
  506. conversion specifier applies to a
  507. .BR size_t
  508. or the corresponding signed integer type argument; or that a following
  509. .BR n
  510. conversion specifier applies to a pointer to a signed integer type
  511. corresponding to a
  512. .BR size_t
  513. argument.
  514. .IP "\fRt\fR" 8
  515. Specifies that a following
  516. .BR d ,
  517. .BR i ,
  518. .BR o ,
  519. .BR u ,
  520. .BR x ,
  521. or
  522. .BR X
  523. conversion specifier applies to a
  524. .BR ptrdiff_t
  525. or the corresponding
  526. .BR unsigned
  527. type argument; or that a following
  528. .BR n
  529. conversion specifier applies to a pointer to a
  530. .BR ptrdiff_t
  531. argument.
  532. .IP "\fRL\fR" 8
  533. Specifies that a following
  534. .BR a ,
  535. .BR A ,
  536. .BR e ,
  537. .BR E ,
  538. .BR f ,
  539. .BR F ,
  540. .BR g ,
  541. or
  542. .BR G
  543. conversion specifier applies to a
  544. .BR "long double"
  545. argument.
  546. .P
  547. If a length modifier appears with any conversion specifier other than
  548. as specified above, the behavior is undefined.
  549. .P
  550. The conversion specifiers and their meanings are:
  551. .IP "\fRd\fR,\ \fRi\fR" 8
  552. The
  553. .BR int
  554. argument shall be converted to a signed decimal in the style
  555. \fR"[\-]\fIdddd\fR"\fR. The precision specifies the minimum number of
  556. digits to appear; if the value being converted can be represented in
  557. fewer digits, it shall be expanded with leading zeros. The default
  558. precision is 1. The result of converting zero with an explicit
  559. precision of zero shall be no characters.
  560. .IP "\fRo\fP" 8
  561. The
  562. .BR unsigned
  563. argument shall be converted to unsigned octal format in the style
  564. \fR"\fIdddd\fR"\fR. The precision specifies the minimum number of
  565. digits to appear; if the value being converted can be represented in
  566. fewer digits, it shall be expanded with leading zeros. The default
  567. precision is 1. The result of converting zero with an explicit
  568. precision of zero shall be no characters.
  569. .IP "\fRu\fP" 8
  570. The
  571. .BR unsigned
  572. argument shall be converted to unsigned decimal format in the style
  573. \fR"\fIdddd\fR"\fR. The precision specifies the minimum number of
  574. digits to appear; if the value being converted can be represented in
  575. fewer digits, it shall be expanded with leading zeros. The default
  576. precision is 1. The result of converting zero with an explicit
  577. precision of zero shall be no characters.
  578. .IP "\fRx\fP" 8
  579. The
  580. .BR unsigned
  581. argument shall be converted to unsigned hexadecimal format in the
  582. style \fR"\fIdddd\fR"\fR; the letters
  583. .BR \(dqabcdef\(dq
  584. are used. The precision specifies the minimum number of digits to
  585. appear; if the value being converted can be represented in fewer
  586. digits, it shall be expanded with leading zeros. The default precision
  587. is 1. The result of converting zero with an explicit precision of zero
  588. shall be no characters.
  589. .IP "\fRX\fP" 8
  590. Equivalent to the
  591. .BR x
  592. conversion specifier, except that letters
  593. .BR \(dqABCDEF\(dq
  594. are used instead of
  595. .BR \(dqabcdef\(dq .
  596. .IP "\fRf\fR,\ \fRF\fR" 8
  597. The
  598. .BR double
  599. argument shall be converted to decimal notation in the style
  600. \fR"[\-]\fIddd\fR.\fIddd\fR"\fR, where the number of digits after the
  601. radix character is equal to the precision specification. If the
  602. precision is missing, it shall be taken as 6; if the precision is
  603. explicitly zero and no
  604. .BR '#'
  605. flag is present, no radix character shall appear. If a radix character
  606. appears, at least one digit appears before it. The low-order digit
  607. shall be rounded in an implementation-defined manner.
  608. .RS 8
  609. .P
  610. A
  611. .BR double
  612. argument representing an infinity shall be converted in one of the
  613. styles
  614. .BR \(dq[-]inf\(dq
  615. or
  616. .BR \(dq[-]infinity\(dq ;
  617. which style is implementation-defined. A
  618. .BR double
  619. argument representing a NaN shall be converted in one of the styles
  620. \fR"[\-]nan(\fIn-char-sequence\fR)"\fR or
  621. .BR \(dq[-]nan\(dq ;
  622. which style, and the meaning of any
  623. .IR n-char-sequence ,
  624. is implementation-defined. The
  625. .BR F
  626. conversion specifier produces
  627. .BR \(dqINF\(dq ,
  628. .BR \(dqINFINITY\(dq ,
  629. or
  630. .BR \(dqNAN\(dq
  631. instead of
  632. .BR \(dqinf\(dq ,
  633. .BR \(dqinfinity\(dq ,
  634. or
  635. .BR \(dqnan\(dq ,
  636. respectively.
  637. .RE
  638. .IP "\fRe\fR,\ \fRE\fR" 8
  639. The
  640. .BR double
  641. argument shall be converted in the style
  642. \fR"[\-]\fId\fR.\fIddd\fRe\(+-\fIdd\fR"\fR, where there is one digit
  643. before the radix character (which is non-zero if the argument is
  644. non-zero) and the number of digits after it is equal to the precision;
  645. if the precision is missing, it shall be taken as 6; if the precision
  646. is zero and no
  647. .BR '#'
  648. flag is present, no radix character shall appear. The low-order digit
  649. shall be rounded in an implementation-defined manner. The
  650. .BR E
  651. conversion specifier shall produce a number with
  652. .BR 'E'
  653. instead of
  654. .BR 'e'
  655. introducing the exponent. The exponent shall always contain at least
  656. two digits. If the value is zero, the exponent shall be zero.
  657. .RS 8
  658. .P
  659. A
  660. .BR double
  661. argument representing an infinity or NaN shall be converted in
  662. the style of an
  663. .BR f
  664. or
  665. .BR F
  666. conversion specifier.
  667. .RE
  668. .IP "\fRg\fR,\ \fRG\fR" 8
  669. The
  670. .BR double
  671. argument representing a floating-point number shall be converted in the
  672. style
  673. .BR f
  674. or
  675. .BR e
  676. (or in the style
  677. .BR F
  678. or
  679. .BR E
  680. in the case of a
  681. .BR G
  682. conversion specifier), depending on the value converted and the precision.
  683. Let
  684. .BR P
  685. equal the precision if non-zero, 6 if the precision is omitted, or 1 if the
  686. precision is zero. Then, if a conversion with style
  687. .BR E
  688. would have an exponent of
  689. .IR X :
  690. .RS 8
  691. .IP -- 4
  692. If
  693. .BR P >\c
  694. .IR X \(>=\-4,
  695. the conversion shall be with style
  696. .BR f
  697. (or
  698. .BR F )
  699. and precision
  700. .BR P \-(\c
  701. .IR X +1).
  702. .IP -- 4
  703. Otherwise, the conversion shall be with style
  704. .BR e
  705. (or
  706. .BR E )
  707. and precision
  708. .BR P \-1.
  709. .P
  710. Finally, unless the
  711. .BR '#'
  712. flag is used, any trailing zeros shall be removed from the fractional
  713. portion of the result and the decimal-point character shall be removed
  714. if there is no fractional portion remaining.
  715. .P
  716. A
  717. .BR double
  718. argument representing an infinity or NaN shall be converted in the
  719. style of an
  720. .BR f
  721. or
  722. .BR F
  723. conversion specifier.
  724. .RE
  725. .IP "\fRa\fR,\ \fRA\fR" 8
  726. A
  727. .BR double
  728. argument representing a floating-point number shall be converted in the
  729. style \fR"[\-]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there is
  730. one hexadecimal digit (which shall be non-zero if the argument is a
  731. normalized floating-point number and is otherwise unspecified) before
  732. the decimal-point character and the number of hexadecimal digits after
  733. it is equal to the precision; if the precision is missing and FLT_RADIX
  734. is a power of 2, then the precision shall be sufficient for an exact
  735. representation of the value; if the precision is missing and FLT_RADIX
  736. is not a power of 2, then the precision shall be sufficient to
  737. distinguish values of type
  738. .BR double ,
  739. except that trailing zeros may be omitted; if the precision is zero and
  740. the
  741. .BR '#'
  742. flag is not specified, no decimal-point character shall appear. The
  743. letters
  744. .BR \(dqabcdef\(dq
  745. shall be used for
  746. .BR a
  747. conversion and the letters
  748. .BR \(dqABCDEF\(dq
  749. for
  750. .BR A
  751. conversion. The
  752. .BR A
  753. conversion specifier produces a number with
  754. .BR 'X'
  755. and
  756. .BR 'P'
  757. instead of
  758. .BR 'x'
  759. and
  760. .BR 'p' .
  761. The exponent shall always contain at least one digit, and only as many
  762. more digits as necessary to represent the decimal exponent of 2. If the
  763. value is zero, the exponent shall be zero.
  764. .RS 8
  765. .P
  766. A
  767. .BR double
  768. argument representing an infinity or NaN shall be converted in the
  769. style of an
  770. .BR f
  771. or
  772. .BR F
  773. conversion specifier.
  774. .RE
  775. .IP "\fRc\fP" 8
  776. The
  777. .BR int
  778. argument shall be converted to an
  779. .BR "unsigned char" ,
  780. and the resulting byte shall be written.
  781. .RS 8
  782. .P
  783. If an
  784. .BR l
  785. (ell) qualifier is present, the
  786. .BR wint_t
  787. argument shall be converted as if by an
  788. .BR ls
  789. conversion specification with no precision and an argument that points
  790. to a two-element array of type
  791. .BR wchar_t ,
  792. the first element of which contains the
  793. .BR wint_t
  794. argument to the
  795. .BR ls
  796. conversion specification and the second element contains a null wide
  797. character.
  798. .RE
  799. .IP "\fRs\fP" 8
  800. The argument shall be a pointer to an array of
  801. .BR char .
  802. Bytes from the array shall be written up to (but not including) any
  803. terminating null byte. If the precision is specified, no more than that
  804. many bytes shall be written. If the precision is not specified or is
  805. greater than the size of the array, the application shall ensure that
  806. the array contains a null byte.
  807. .RS 8
  808. .P
  809. If an
  810. .BR l
  811. (ell) qualifier is present, the argument shall be a pointer to an array
  812. of type
  813. .BR wchar_t .
  814. Wide characters from the array shall be converted to characters (each
  815. as if by a call to the
  816. \fIwcrtomb\fR()
  817. function, with the conversion state described by an
  818. .BR mbstate_t
  819. object initialized to zero before the first wide character is
  820. converted) up to and including a terminating null wide character. The
  821. resulting characters shall be written up to (but not including) the
  822. terminating null character (byte). If no precision is specified, the
  823. application shall ensure that the array contains a null wide character.
  824. If a precision is specified, no more than that many characters (bytes)
  825. shall be written (including shift sequences, if any), and the array
  826. shall contain a null wide character if, to equal the character sequence
  827. length given by the precision, the function would need to access a wide
  828. character one past the end of the array. In no case shall a partial
  829. character be written.
  830. .RE
  831. .IP "\fRp\fP" 8
  832. The argument shall be a pointer to
  833. .BR void .
  834. The value of the pointer is converted to a sequence of printable
  835. characters, in an implementation-defined manner.
  836. .IP "\fRn\fP" 8
  837. The argument shall be a pointer to an integer into which is written the
  838. number of bytes written to the output so far by this call to one of the
  839. \fIfprintf\fR()
  840. functions. No argument is converted.
  841. .IP "\fRC\fP" 8
  842. Equivalent to
  843. .BR lc .
  844. .IP "\fRS\fP" 8
  845. Equivalent to
  846. .BR ls .
  847. .IP "\fR%\fR" 8
  848. Print a
  849. .BR '%'
  850. character; no argument is converted. The complete conversion
  851. specification shall be
  852. .BR %% .
  853. .P
  854. If a conversion specification does not match one of the above forms,
  855. the behavior is undefined. If any argument is not the correct type for
  856. the corresponding conversion specification, the behavior is undefined.
  857. .P
  858. In no case shall a nonexistent or small field width cause truncation of
  859. a field; if the result of a conversion is wider than the field width,
  860. the field shall be expanded to contain the conversion result.
  861. Characters generated by
  862. \fIfprintf\fR()
  863. and
  864. \fIprintf\fR()
  865. are printed as if
  866. \fIfputc\fR()
  867. had been called.
  868. .P
  869. For the
  870. .BR a
  871. and
  872. .BR A
  873. conversion specifiers, if FLT_RADIX is a power of 2, the value shall be
  874. correctly rounded to a hexadecimal floating number with the given
  875. precision.
  876. .P
  877. For
  878. .BR a
  879. and
  880. .BR A
  881. conversions, if FLT_RADIX is not a power of 2 and the result is not
  882. exactly representable in the given precision, the result should be one
  883. of the two adjacent numbers in hexadecimal floating style with the
  884. given precision, with the extra stipulation that the error should have
  885. a correct sign for the current rounding direction.
  886. .P
  887. For the
  888. .BR e ,
  889. .BR E ,
  890. .BR f ,
  891. .BR F ,
  892. .BR g ,
  893. and
  894. .BR G
  895. conversion specifiers, if the number of significant decimal digits is
  896. at most DECIMAL_DIG, then the result should be correctly rounded. If
  897. the number of significant decimal digits is more than DECIMAL_DIG but
  898. the source value is exactly representable with DECIMAL_DIG digits, then
  899. the result should be an exact representation with trailing zeros.
  900. Otherwise, the source value is bounded by two adjacent decimal strings
  901. .IR L
  902. <
  903. .IR U ,
  904. both having DECIMAL_DIG significant digits; the value of the resultant
  905. decimal string
  906. .IR D
  907. should satisfy
  908. .IR L
  909. <=
  910. .IR D
  911. <=
  912. .IR U ,
  913. with the extra stipulation that the error should have a correct sign
  914. for the current rounding direction.
  915. .P
  916. The last data modification and last file status change timestamps
  917. of the file shall be marked for update:
  918. .IP " 1." 4
  919. Between the call to a successful execution of
  920. \fIfprintf\fR()
  921. or
  922. \fIprintf\fR()
  923. and the next successful completion of a call to
  924. \fIfflush\fR()
  925. or
  926. \fIfclose\fR()
  927. on the same stream or a call to
  928. \fIexit\fR()
  929. or
  930. \fIabort\fR()
  931. .IP " 2." 4
  932. Upon successful completion of a call to
  933. \fIdprintf\fR()
  934. .SH "RETURN VALUE"
  935. Upon successful completion, the
  936. \fIdprintf\fR(),
  937. \fIfprintf\fR(),
  938. and
  939. \fIprintf\fR()
  940. functions shall return the number of bytes transmitted.
  941. .P
  942. Upon successful completion, the
  943. \fIsprintf\fR()
  944. function shall return the number of bytes written to
  945. .IR s ,
  946. excluding the terminating null byte.
  947. .P
  948. Upon successful completion, the
  949. \fIsnprintf\fR()
  950. function shall return the number of bytes that would be written to
  951. .IR s
  952. had
  953. .IR n
  954. been sufficiently large excluding the terminating null byte.
  955. .P
  956. If an output error was encountered, these functions shall return a
  957. negative value
  958. and set
  959. .IR errno
  960. to indicate the error.
  961. .P
  962. If the value of
  963. .IR n
  964. is zero on a call to
  965. \fIsnprintf\fR(),
  966. nothing shall be written, the number of bytes that would have been
  967. written had
  968. .IR n
  969. been sufficiently large excluding the terminating null shall be
  970. returned, and
  971. .IR s
  972. may be a null pointer.
  973. .SH ERRORS
  974. For the conditions under which
  975. \fIdprintf\fR(),
  976. \fIfprintf\fR(),
  977. and
  978. \fIprintf\fR()
  979. fail and may fail, refer to
  980. .IR "\fIfputc\fR\^(\|)"
  981. or
  982. .IR "\fIfputwc\fR\^(\|)".
  983. .P
  984. In addition, all forms of
  985. \fIfprintf\fR()
  986. shall fail if:
  987. .TP
  988. .BR EILSEQ
  989. A wide-character code that does not correspond to a valid character
  990. has been detected.
  991. .TP
  992. .BR EOVERFLOW
  993. The value to be returned is greater than
  994. {INT_MAX}.
  995. .P
  996. The
  997. \fIdprintf\fR()
  998. function may fail if:
  999. .TP
  1000. .BR EBADF
  1001. The
  1002. .IR fildes
  1003. argument is not a valid file descriptor.
  1004. .P
  1005. The
  1006. \fIdprintf\fR(),
  1007. \fIfprintf\fR(),
  1008. and
  1009. \fIprintf\fR()
  1010. functions may fail if:
  1011. .TP
  1012. .BR ENOMEM
  1013. Insufficient storage space is available.
  1014. .P
  1015. The
  1016. \fIsnprintf\fR()
  1017. function shall fail if:
  1018. .TP
  1019. .BR EOVERFLOW
  1020. The value of
  1021. .IR n
  1022. is greater than
  1023. {INT_MAX}.
  1024. .LP
  1025. .IR "The following sections are informative."
  1026. .SH "EXAMPLES"
  1027. .SS "Printing Language-Independent Date and Time"
  1028. .P
  1029. The following statement can be used to print date and time using a
  1030. language-independent format:
  1031. .sp
  1032. .RS 4
  1033. .nf
  1034. printf(format, weekday, month, day, hour, min);
  1035. .fi
  1036. .P
  1037. .RE
  1038. .P
  1039. For American usage,
  1040. .IR format
  1041. could be a pointer to the following string:
  1042. .sp
  1043. .RS 4
  1044. .nf
  1045. "%s, %s %d, %d:%.2d\en"
  1046. .fi
  1047. .P
  1048. .RE
  1049. .P
  1050. This example would produce the following message:
  1051. .sp
  1052. .RS 4
  1053. .nf
  1054. Sunday, July 3, 10:02
  1055. .fi
  1056. .P
  1057. .RE
  1058. .P
  1059. For German usage,
  1060. .IR format
  1061. could be a pointer to the following string:
  1062. .sp
  1063. .RS 4
  1064. .nf
  1065. "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
  1066. .fi
  1067. .P
  1068. .RE
  1069. .P
  1070. This definition of
  1071. .IR format
  1072. would produce the following message:
  1073. .sp
  1074. .RS 4
  1075. .nf
  1076. Sonntag, 3. Juli, 10:02
  1077. .fi
  1078. .P
  1079. .RE
  1080. .SS "Printing File Information"
  1081. .P
  1082. The following example prints information about the type, permissions,
  1083. and number of links of a specific file in a directory.
  1084. .P
  1085. The first two calls to
  1086. \fIprintf\fR()
  1087. use data decoded from a previous
  1088. \fIstat\fR()
  1089. call. The user-defined
  1090. \fIstrperm\fR()
  1091. function shall return a string similar to the one at the beginning of the
  1092. output for the following command:
  1093. .sp
  1094. .RS 4
  1095. .nf
  1096. ls -l
  1097. .fi
  1098. .P
  1099. .RE
  1100. .P
  1101. The next call to
  1102. \fIprintf\fR()
  1103. outputs the owner's name if it is found using
  1104. \fIgetpwuid\fR();
  1105. the
  1106. \fIgetpwuid\fR()
  1107. function shall return a
  1108. .BR passwd
  1109. structure from which the name of the user is extracted. If the user
  1110. name is not found, the program instead prints out the numeric value of
  1111. the user ID.
  1112. .P
  1113. The next call prints out the group name if it is found using
  1114. \fIgetgrgid\fR();
  1115. \fIgetgrgid\fR()
  1116. is very similar to
  1117. \fIgetpwuid\fR()
  1118. except that it shall return group information based on the group number.
  1119. Once again, if the group is not found, the program prints the numeric
  1120. value of the group for the entry.
  1121. .P
  1122. The final call to
  1123. \fIprintf\fR()
  1124. prints the size of the file.
  1125. .sp
  1126. .RS 4
  1127. .nf
  1128. #include <stdio.h>
  1129. #include <sys/types.h>
  1130. #include <pwd.h>
  1131. #include <grp.h>
  1132. .P
  1133. char *strperm (mode_t);
  1134. \&...
  1135. struct stat statbuf;
  1136. struct passwd *pwd;
  1137. struct group *grp;
  1138. \&...
  1139. printf("%10.10s", strperm (statbuf.st_mode));
  1140. printf("%4d", statbuf.st_nlink);
  1141. .P
  1142. if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
  1143. printf(" %-8.8s", pwd->pw_name);
  1144. else
  1145. printf(" %-8ld", (long) statbuf.st_uid);
  1146. .P
  1147. if ((grp = getgrgid(statbuf.st_gid)) != NULL)
  1148. printf(" %-8.8s", grp->gr_name);
  1149. else
  1150. printf(" %-8ld", (long) statbuf.st_gid);
  1151. .P
  1152. printf("%9jd", (intmax_t) statbuf.st_size);
  1153. \&...
  1154. .fi
  1155. .P
  1156. .RE
  1157. .SS "Printing a Localized Date String"
  1158. .P
  1159. The following example gets a localized date string. The
  1160. \fInl_langinfo\fR()
  1161. function shall return the localized date string, which specifies the
  1162. order and layout of the date. The
  1163. \fIstrftime\fR()
  1164. function takes this information and, using the
  1165. .BR tm
  1166. structure for values, places the date and time information into
  1167. .IR datestring .
  1168. The
  1169. \fIprintf\fR()
  1170. function then outputs
  1171. .IR datestring
  1172. and the name of the entry.
  1173. .sp
  1174. .RS 4
  1175. .nf
  1176. #include <stdio.h>
  1177. #include <time.h>
  1178. #include <langinfo.h>
  1179. \&...
  1180. struct dirent *dp;
  1181. struct tm *tm;
  1182. char datestring[256];
  1183. \&...
  1184. strftime(datestring, sizeof(datestring), nl_langinfo (D_T_FMT), tm);
  1185. .P
  1186. printf(" %s %s\en", datestring, dp->d_name);
  1187. \&...
  1188. .fi
  1189. .P
  1190. .RE
  1191. .SS "Printing Error Information"
  1192. .P
  1193. The following example uses
  1194. \fIfprintf\fR()
  1195. to write error information to standard error.
  1196. .P
  1197. In the first group of calls, the program tries to open the password
  1198. lock file named
  1199. .BR LOCKFILE .
  1200. If the file already exists, this is an error, as indicated by the
  1201. O_EXCL flag on the
  1202. \fIopen\fR()
  1203. function. If the call fails, the program assumes that someone else is
  1204. updating the password file, and the program exits.
  1205. .P
  1206. The next group of calls saves a new password file as the current
  1207. password file by creating a link between
  1208. .BR LOCKFILE
  1209. and the new password file
  1210. .BR PASSWDFILE .
  1211. .sp
  1212. .RS 4
  1213. .nf
  1214. #include <sys/types.h>
  1215. #include <sys/stat.h>
  1216. #include <fcntl.h>
  1217. #include <stdio.h>
  1218. #include <stdlib.h>
  1219. #include <unistd.h>
  1220. #include <string.h>
  1221. #include <errno.h>
  1222. .P
  1223. #define LOCKFILE "/etc/ptmp"
  1224. #define PASSWDFILE "/etc/passwd"
  1225. \&...
  1226. int pfd;
  1227. \&...
  1228. if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
  1229. S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
  1230. {
  1231. fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\en");
  1232. exit(1);
  1233. }
  1234. \&...
  1235. if (link(LOCKFILE,PASSWDFILE) == -1) {
  1236. fprintf(stderr, "Link error: %s\en", strerror(errno));
  1237. exit(1);
  1238. }
  1239. \&...
  1240. .fi
  1241. .P
  1242. .RE
  1243. .SS "Printing Usage Information"
  1244. .P
  1245. The following example checks to make sure the program has the necessary
  1246. arguments, and uses
  1247. \fIfprintf\fR()
  1248. to print usage information if the expected number of arguments is not
  1249. present.
  1250. .sp
  1251. .RS 4
  1252. .nf
  1253. #include <stdio.h>
  1254. #include <stdlib.h>
  1255. \&...
  1256. char *Options = "hdbtl";
  1257. \&...
  1258. if (argc < 2) {
  1259. fprintf(stderr, "Usage: %s -%s <file\en", argv[0], Options); exit(1);
  1260. }
  1261. \&...
  1262. .fi
  1263. .P
  1264. .RE
  1265. .SS "Formatting a Decimal String"
  1266. .P
  1267. The following example prints a key and data pair on
  1268. .IR stdout .
  1269. Note use of the
  1270. <asterisk>
  1271. (\c
  1272. .BR '*' )
  1273. in the format string; this ensures the correct number of decimal places
  1274. for the element based on the number of elements requested.
  1275. .sp
  1276. .RS 4
  1277. .nf
  1278. #include <stdio.h>
  1279. \&...
  1280. long i;
  1281. char *keystr;
  1282. int elementlen, len;
  1283. \&...
  1284. while (len < elementlen) {
  1285. \&...
  1286. printf("%s Element%0*ld\en", keystr, elementlen, i);
  1287. \&...
  1288. }
  1289. .fi
  1290. .P
  1291. .RE
  1292. .SS "Creating a Pathname"
  1293. .P
  1294. The following example creates a pathname using information from a previous
  1295. \fIgetpwnam\fR()
  1296. function that returned the password database entry of the user.
  1297. .sp
  1298. .RS 4
  1299. .nf
  1300. #include <stdint.h>
  1301. #include <stdio.h>
  1302. #include <stdlib.h>
  1303. #include <string.h>
  1304. #include <sys/types.h>
  1305. #include <unistd.h>
  1306. \&...
  1307. char *pathname;
  1308. struct passwd *pw;
  1309. size_t len;
  1310. \&...
  1311. // digits required for pid_t is number of bits times
  1312. // log2(10) = approx 10/33
  1313. len = strlen(pw->pw_dir) + 1 + 1+(sizeof(pid_t)*80+32)/33 +
  1314. sizeof ".out";
  1315. pathname = malloc(len);
  1316. if (pathname != NULL)
  1317. {
  1318. snprintf(pathname, len, "%s/%jd.out", pw->pw_dir,
  1319. (intmax_t)getpid());
  1320. ...
  1321. }
  1322. .fi
  1323. .P
  1324. .RE
  1325. .SS "Reporting an Event"
  1326. .P
  1327. The following example loops until an event has timed out. The
  1328. \fIpause\fR()
  1329. function waits forever unless it receives a signal. The
  1330. \fIfprintf\fR()
  1331. statement should never occur due to the possible return values of
  1332. \fIpause\fR().
  1333. .sp
  1334. .RS 4
  1335. .nf
  1336. #include <stdio.h>
  1337. #include <unistd.h>
  1338. #include <string.h>
  1339. #include <errno.h>
  1340. \&...
  1341. while (!event_complete) {
  1342. \&...
  1343. if (pause() != -1 || errno != EINTR)
  1344. fprintf(stderr, "pause: unknown error: %s\en", strerror(errno));
  1345. }
  1346. \&...
  1347. .fi
  1348. .P
  1349. .RE
  1350. .SS "Printing Monetary Information"
  1351. .P
  1352. The following example uses
  1353. \fIstrfmon\fR()
  1354. to convert a number and store it as a formatted monetary string named
  1355. .IR convbuf .
  1356. If the first number is printed, the program prints the format and the
  1357. description; otherwise, it just prints the number.
  1358. .sp
  1359. .RS 4
  1360. .nf
  1361. #include <monetary.h>
  1362. #include <stdio.h>
  1363. \&...
  1364. struct tblfmt {
  1365. char *format;
  1366. char *description;
  1367. };
  1368. .P
  1369. struct tblfmt table[] = {
  1370. { "%n", "default formatting" },
  1371. { "%11n", "right align within an 11 character field" },
  1372. { "%#5n", "aligned columns for values up to 99\|999" },
  1373. { "%=*#5n", "specify a fill character" },
  1374. { "%=0#5n", "fill characters do not use grouping" },
  1375. { "%\(ha#5n", "disable the grouping separator" },
  1376. { "%\(ha#5.0n", "round off to whole units" },
  1377. { "%\(ha#5.4n", "increase the precision" },
  1378. { "%(#5n", "use an alternative pos/neg style" },
  1379. { "%!(#5n", "disable the currency symbol" },
  1380. };
  1381. \&...
  1382. float input[3];
  1383. int i, j;
  1384. char convbuf[100];
  1385. \&...
  1386. strfmon(convbuf, sizeof(convbuf), table[i].format, input[j]);
  1387. .P
  1388. if (j == 0) {
  1389. printf("%s\t%s\t%s\en", table[i].format,
  1390. convbuf, table[i].description);
  1391. }
  1392. else {
  1393. printf("\t%s\en", convbuf);
  1394. }
  1395. \&...
  1396. .fi
  1397. .P
  1398. .RE
  1399. .SS "Printing Wide Characters"
  1400. .P
  1401. The following example prints a series of wide characters. Suppose that
  1402. .BR \(dqL`@`\(dq
  1403. expands to three bytes:
  1404. .sp
  1405. .RS 4
  1406. .nf
  1407. wchar_t wz [3] = L"@@"; // Zero-terminated
  1408. wchar_t wn [3] = L"@@@"; // Unterminated
  1409. .P
  1410. fprintf (stdout,"%ls", wz); // Outputs 6 bytes
  1411. fprintf (stdout,"%ls", wn); // Undefined because wn has no terminator
  1412. fprintf (stdout,"%4ls", wz); // Outputs 3 bytes
  1413. fprintf (stdout,"%4ls", wn); // Outputs 3 bytes; no terminator needed
  1414. fprintf (stdout,"%9ls", wz); // Outputs 6 bytes
  1415. fprintf (stdout,"%9ls", wn); // Outputs 9 bytes; no terminator needed
  1416. fprintf (stdout,"%10ls", wz); // Outputs 6 bytes
  1417. fprintf (stdout,"%10ls", wn); // Undefined because wn has no terminator
  1418. .fi
  1419. .P
  1420. .RE
  1421. .P
  1422. In the last line of the example, after processing three characters,
  1423. nine bytes have been output. The fourth character must then be examined
  1424. to determine whether it converts to one byte or more. If it converts
  1425. to more than one byte, the output is only nine bytes. Since there is
  1426. no fourth character in the array, the behavior is undefined.
  1427. .SH "APPLICATION USAGE"
  1428. If the application calling
  1429. \fIfprintf\fR()
  1430. has any objects of type
  1431. .BR wint_t
  1432. or
  1433. .BR wchar_t ,
  1434. it must also include the
  1435. .IR <wchar.h>
  1436. header to have these objects defined.
  1437. .SH RATIONALE
  1438. If an implementation detects that there are insufficient
  1439. arguments for the format, it is recommended that the function
  1440. should fail and report an
  1441. .BR [EINVAL]
  1442. error.
  1443. .SH "FUTURE DIRECTIONS"
  1444. None.
  1445. .SH "SEE ALSO"
  1446. .IR "Section 2.5" ", " "Standard I/O Streams",
  1447. .IR "\fIfputc\fR\^(\|)",
  1448. .IR "\fIfscanf\fR\^(\|)",
  1449. .IR "\fIsetlocale\fR\^(\|)",
  1450. .IR "\fIstrfmon\fR\^(\|)",
  1451. .IR "\fIwcrtomb\fR\^(\|)"
  1452. .P
  1453. The Base Definitions volume of POSIX.1\(hy2017,
  1454. .IR "Chapter 7" ", " "Locale",
  1455. .IR "\fB<inttypes.h>\fP",
  1456. .IR "\fB<stdio.h>\fP",
  1457. .IR "\fB<wchar.h>\fP"
  1458. .\"
  1459. .SH COPYRIGHT
  1460. Portions of this text are reprinted and reproduced in electronic form
  1461. from IEEE Std 1003.1-2017, Standard for Information Technology
  1462. -- Portable Operating System Interface (POSIX), The Open Group Base
  1463. Specifications Issue 7, 2018 Edition,
  1464. Copyright (C) 2018 by the Institute of
  1465. Electrical and Electronics Engineers, Inc and The Open Group.
  1466. In the event of any discrepancy between this version and the original IEEE and
  1467. The Open Group Standard, the original IEEE and The Open Group Standard
  1468. is the referee document. The original Standard can be obtained online at
  1469. http://www.opengroup.org/unix/online.html .
  1470. .PP
  1471. Any typographical or formatting errors that appear
  1472. in this page are most likely
  1473. to have been introduced during the conversion of the source files to
  1474. man page format. To report such errors, see
  1475. https://www.kernel.org/doc/man-pages/reporting_bugs.html .