1
0

fprintf 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506
  1. .TH FPRINTF 2
  2. .SH NAME
  3. fprintf, printf, sprintf, snprintf, vfprintf, vprintf, vsprintf, vsnprintf \- print formatted output
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <stdio.h>
  8. .PP
  9. .B
  10. int fprintf(FILE *f, char *format, ...)
  11. .PP
  12. .B
  13. int printf(char *format, ...)
  14. .PP
  15. .B
  16. int sprintf(char *s, char *format, ...)
  17. .PP
  18. .B
  19. int snprintf(char *s, int n, char *format, ...)
  20. .PP
  21. .B
  22. int vfprintf(FILE *f, char *format, va_list args)
  23. .PP
  24. .B
  25. int vprintf(char *format, va_list args)
  26. .PP
  27. .B
  28. int vsprintf(char *s, char *format, va_list args)
  29. .PP
  30. .B
  31. int vsnprintf(char *s, int n, char *format, va_list args)
  32. .SH DESCRIPTION
  33. .I Fprintf
  34. places output on the named output stream
  35. .I f
  36. (see
  37. .IR fopen (2)).
  38. .I Printf
  39. places output on the standard output stream
  40. .IR stdout .
  41. .I Sprintf
  42. places output
  43. followed by the null character
  44. .RB ( \e0 )
  45. in consecutive bytes starting at
  46. .IR s ;
  47. it is the user's responsibility to ensure that
  48. enough storage is available.
  49. .I Snprintf
  50. is like
  51. .I sprintf
  52. but writes at most
  53. .I n
  54. bytes (including the null character)
  55. into
  56. .IR s .
  57. .IR Vfprintf ,
  58. .IR vprintf ,
  59. .IR vsnprintf ,
  60. and
  61. .I vsprintf
  62. are the same, except the
  63. .I args
  64. argument is the argument list of the
  65. calling function, and the effect is as if the calling function's
  66. argument list from that point on is passed to the
  67. .I printf
  68. routines.
  69. .PP
  70. Each function returns the number of characters
  71. transmitted (not including the
  72. .B \e0
  73. in the case of
  74. .IR sprintf
  75. and friends),
  76. or
  77. a negative value if an output error was encountered.
  78. .PP
  79. These functions
  80. convert, format, and print their
  81. trailing arguments
  82. under control of a
  83. .IR format
  84. string.
  85. The
  86. .I format
  87. contains two types of objects:
  88. plain characters, which are simply copied to the
  89. output stream,
  90. and conversion specifications,
  91. each of which results in fetching of
  92. zero or more
  93. arguments.
  94. The results are undefined if there are arguments of the
  95. wrong type or too few
  96. arguments for the format.
  97. If the format is exhausted while
  98. arguments remain, the excess
  99. are ignored.
  100. .PP
  101. Each conversion specification is introduced by
  102. the character
  103. .BR % .
  104. After the
  105. .BR % ,
  106. the following
  107. appear in sequence:
  108. .PP
  109. .RS
  110. Zero or more
  111. .IR flags ,
  112. which modify the meaning of
  113. the conversion specification.
  114. .PP
  115. An optional decimal digit string specifying a minimum
  116. .IR "field width" .
  117. If the converted value has fewer characters
  118. than the field width, it will be padded with spaces on the
  119. left (or right, if the left adjustment, described later, has been given)
  120. to the field width.
  121. .PP
  122. An optional
  123. .I precision\^
  124. that gives
  125. the minimum number of digits to appear for the
  126. .BR d ,
  127. .BR i ,
  128. .BR o ,
  129. .BR u ,
  130. .BR x ,
  131. and
  132. .B X
  133. conversions,
  134. the number of digits to appear after the
  135. decimal point for the
  136. .BR e ,
  137. .BR E ,
  138. and
  139. .B f
  140. conversions,
  141. the maximum number of significant digits
  142. for the
  143. .B g
  144. and
  145. .B G
  146. conversions,
  147. or the maximum number of characters
  148. to be written from a string in
  149. .B s
  150. conversion.
  151. The precision takes the form of a period
  152. .RB ( \&. )
  153. followed by an optional decimal integer;
  154. if the integer is omitted, it is treated as zero.
  155. .PP
  156. An optional
  157. .B h
  158. specifying that a following
  159. .BR d ,
  160. .BR i ,
  161. .BR o ,
  162. .BR u ,
  163. .BR x
  164. or
  165. .BR X
  166. conversion specifier applies to a
  167. .B short
  168. .B int
  169. or
  170. .B unsigned
  171. .B short
  172. argument (the argument will have been promoted according to the integral
  173. promotions, and its value shall be converted to
  174. .B short
  175. or
  176. .B unsigned
  177. .B short
  178. before printing);
  179. an optional
  180. .B h
  181. specifying that a following
  182. .B n
  183. conversion specifier applies to a pointer to a
  184. .B short
  185. argument;
  186. an optional
  187. .B l
  188. (ell) specifying that a following
  189. .BR d ,
  190. .BR i ,
  191. .BR o ,
  192. .BR u ,
  193. .BR x ,
  194. or
  195. .B X
  196. conversion character applies to a
  197. .B long
  198. or
  199. .B unsigned
  200. .B long
  201. argument;
  202. an optional
  203. .B l
  204. specifying that a following
  205. .B n
  206. conversion specifier applies to a pointer to a
  207. .B long
  208. .B int
  209. argument;
  210. or an optional
  211. .B L
  212. specifying that a following
  213. .BR e ,
  214. .BR E ,
  215. .BR f ,
  216. .BR g ,
  217. or
  218. .B G
  219. conversion specifier applies to a
  220. .B long double
  221. argument.
  222. If an
  223. .BR h ,
  224. .BR l ,
  225. or
  226. .B L
  227. appears with any other conversion specifier, the behavior is undefined.
  228. .PP
  229. A character that indicates the type of
  230. conversion to be applied.
  231. .RE
  232. .PP
  233. A field width or precision, or both, may be
  234. indicated by an asterisk
  235. .RB ( * )
  236. instead of a digit string.
  237. In this case, an
  238. .B int
  239. .I arg\^
  240. supplies
  241. the field width or precision.
  242. The arguments specifying field width or precision, or both,
  243. shall appear (in that order) before the argument (if any) to be converted.
  244. A negative field width argument is taken as a
  245. .B -
  246. flag followed by a positive field width.
  247. A negative precision is taken as if it were missing.
  248. .PP
  249. The flag characters and their meanings are:
  250. .PD 0
  251. .TP 10
  252. .B -
  253. The result of the conversion is left-justified within the field.
  254. .TP
  255. .B +
  256. The result of a signed
  257. conversion always begins with a sign
  258. .RB ( +
  259. or
  260. .BR - ).
  261. .TP
  262. blank
  263. If the first character of a signed conversion is not a sign,
  264. or a signed conversion results in no characters,
  265. a blank
  266. is prefixed to the result.
  267. This implies that if the blank and
  268. .B +
  269. flags both appear, the blank flag is ignored.
  270. .TP
  271. .B #
  272. The result is to be converted
  273. to an ``alternate form.''
  274. For
  275. .B o
  276. conversion, it increases the precision to force
  277. the first digit of the result to be a zero.
  278. For
  279. .B x
  280. or
  281. .B X
  282. conversion, a non-zero result has
  283. .B 0x
  284. or
  285. .B 0X
  286. prefixed to it.
  287. For
  288. .BR e ,
  289. .BR E ,
  290. .BR f ,
  291. .BR g ,
  292. and
  293. .B G
  294. conversions, the result always contains a decimal point,
  295. even if no digits follow the point (normally, a decimal point
  296. appears in the result of these conversions only if a digit
  297. follows it).
  298. For
  299. .B g
  300. and
  301. .B G
  302. conversions, trailing zeros are
  303. .I not\^
  304. be removed from the result
  305. as they normally are.
  306. For other conversions, the behavior is undefined.
  307. .TP
  308. .B 0
  309. For
  310. .BR d ,
  311. .BR i ,
  312. .BR o ,
  313. .BR u ,
  314. .BR x ,
  315. .BR X ,
  316. .BR e ,
  317. .BR E ,
  318. .BR f ,
  319. .BR g ,
  320. and
  321. .B G
  322. conversions, leading zeros (following any indication of sign or base)
  323. are used to pad the field width; no space padding is performed.
  324. If the
  325. .B 0
  326. and
  327. .B -
  328. flags both appear, the
  329. .B 0
  330. flag will be ignored.
  331. For
  332. .BR d ,
  333. .BR i ,
  334. .BR o ,
  335. .BR u ,
  336. .BR x ,
  337. and
  338. .B X
  339. conversions, if a precision is specified, the
  340. .B 0
  341. flag will be ignored.
  342. For other conversions, the behavior is undefined.
  343. .PD
  344. .PP
  345. The conversion characters
  346. and their meanings are:
  347. .PP
  348. .PD 0
  349. .TP 10
  350. \fLd\fP,\fLo\fP,\fLu\fP,\fLx\fP,\fLX\fP
  351. The integer
  352. .I arg\^
  353. is converted to signed decimal
  354. .RB ( d
  355. or
  356. .BR i ),
  357. unsigned octal
  358. .RB ( o ),
  359. unsigned decimal
  360. .RB ( u ),
  361. or unsigned hexadecimal notation
  362. .RB ( x
  363. or
  364. .BR X );
  365. the letters
  366. .B abcdef
  367. are used for
  368. .B x
  369. conversion and the letters
  370. .B ABCDEF
  371. for
  372. .B X
  373. conversion.
  374. The precision specifies the minimum number of digits
  375. to appear; if the value being converted can be represented
  376. in fewer digits, it is expanded with leading zeros.
  377. The default precision is 1.
  378. The result of converting a zero value with a precision
  379. of zero is no characters.
  380. .TP
  381. .BR f
  382. The
  383. .B double
  384. argument is converted to decimal notation
  385. in the style
  386. [\-]\fIddd\fL.\fIddd\fR,
  387. where the number of digits after the decimal point
  388. is equal to the precision specification.
  389. If the precision
  390. is missing,
  391. it is taken as 6;
  392. if the precision is explicitly
  393. .LR 0 ,
  394. no decimal point appears.
  395. .TP
  396. .BR e , E
  397. The
  398. .B double
  399. argument is converted in the style
  400. [\-]\fId\fL.\fIddd\fLe\fR±\fIdd\fR,
  401. where there is one digit before the decimal point and
  402. the number of digits after it is equal to the
  403. precision;
  404. when the precision is missing, it is taken as 6;
  405. if the precision is zero, no decimal point appears.
  406. The
  407. .B E
  408. format code produces a number with
  409. .B E
  410. instead of
  411. .B e
  412. introducing the exponent.
  413. The exponent always contains at least two digits.
  414. .TP
  415. .BR g , G
  416. The
  417. .B double
  418. argument is printed in style
  419. .BR f
  420. or
  421. .BR e
  422. (or in style
  423. .B E
  424. in the case of a
  425. .B G
  426. conversion specifier),
  427. with the precision specifying the number of significant digits.
  428. If an explicit precision is zero, it is taken as 1.
  429. The style used depends on the value converted:
  430. style
  431. .B e
  432. is used only if the exponent resulting from
  433. the conversion is less than \-4
  434. or greater than or equal to the precision.
  435. Trailing zeros are removed from the fractional portion of the result;
  436. a decimal point appears only if it is followed by a digit.
  437. .TP
  438. .B c
  439. The
  440. .B int
  441. argument is converted to an
  442. .B unsigned
  443. .BR char ,
  444. and the resulting character is written.
  445. .TP
  446. .B s
  447. The
  448. argument is taken to be a string (character pointer)
  449. and characters from the string are printed until
  450. a null character
  451. .RB ( \e0 )
  452. is encountered or
  453. the number of characters indicated by the precision
  454. specification is reached.
  455. If the precision is missing, it is taken to be infinite, so
  456. all characters up to the first null character are printed.
  457. A
  458. zero
  459. value for
  460. the argument yields undefined results.
  461. .TP
  462. .B P
  463. The
  464. .B void*
  465. argument is printed in an implementation-defined way (for Plan 9:
  466. the address as hexadecimal number).
  467. .TP
  468. .B n
  469. The argument shall be a pointer to an integer into which is
  470. .I written
  471. the number of characters written to the output stream so far by
  472. this call to
  473. .IR fprintf .
  474. No argument is converted.
  475. .TP
  476. .B %
  477. Print a
  478. .BR % ;
  479. no argument is converted.
  480. .PD
  481. .PP
  482. If a conversion specification is invalid, the behavior is undefined.
  483. .PP
  484. If any argument is, or points to, a union or an aggregate
  485. (except for an array of character type using
  486. .B %s
  487. conversion, or a pointer cast to be a pointer to
  488. .B void
  489. using
  490. .B %P
  491. conversion), the behavior is undefined.
  492. .PP
  493. In no case does a nonexistent or small field width cause truncation
  494. of a field; if the result of a conversion is wider than the field width,
  495. the field is expanded to contain the conversion result.
  496. .SH SOURCE
  497. .B /sys/src/libstdio
  498. .SH SEE ALSO
  499. .IR fopen (2),
  500. .IR fscanf (2),
  501. .IR print (2)
  502. .SH BUGS
  503. There is no way to print a wide character (rune); use
  504. .IR print (2)
  505. or
  506. .IR bio (2).