print 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451
  1. .TH PRINT 2
  2. .SH NAME
  3. print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .PP
  9. .ta \w'\fLchar* 'u
  10. .B
  11. int print(char *format, ...)
  12. .PP
  13. .B
  14. int fprint(int fd, char *format, ...)
  15. .PP
  16. .B
  17. int sprint(char *s, char *format, ...)
  18. .PP
  19. .B
  20. int snprint(char *s, int len, char *format, ...)
  21. .PP
  22. .B
  23. char* seprint(char *s, char *e, char *format, ...)
  24. .PP
  25. .B
  26. char* smprint(char *format, ...)
  27. .PP
  28. .B
  29. int runesprint(Rune *s, char *format, ...)
  30. .PP
  31. .B
  32. int runesnprint(Rune *s, int len, char *format, ...)
  33. .PP
  34. .B
  35. Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
  36. .PP
  37. .B
  38. Rune* runesmprint(char *format, ...)
  39. .PP
  40. .B
  41. int vfprint(int fd, char *format, va_list v)
  42. .PP
  43. .B
  44. int vsnprint(char *s, int len, char *format, va_list v)
  45. .PP
  46. .B
  47. char* vseprint(char *s, char *e, char *format, va_list v)
  48. .PP
  49. .B
  50. char* vsmprint(char *format, va_list v)
  51. .PP
  52. .B
  53. int runevsnprint(Rune *s, int len, char *format, va_list v)
  54. .PP
  55. .B
  56. Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
  57. .PP
  58. .B
  59. Rune* runevsmprint(Rune *format, va_list v)
  60. .PP
  61. .B
  62. .SH DESCRIPTION
  63. .I Print
  64. writes text to the standard output.
  65. .I Fprint
  66. writes to the named output
  67. file descriptor;
  68. a buffered form
  69. is described in
  70. .IR bio (2).
  71. .I Sprint
  72. places text
  73. followed by the NUL character
  74. .RB ( \e0 )
  75. in consecutive bytes starting at
  76. .IR s ;
  77. it is the user's responsibility to ensure that
  78. enough storage is available.
  79. Each function returns the number of bytes
  80. transmitted (not including the NUL
  81. in the case of
  82. .IR sprint ),
  83. or
  84. a negative value if an output error was encountered.
  85. .PP
  86. .I Snprint
  87. is like
  88. .IR sprint ,
  89. but will not place more than
  90. .I len
  91. bytes in
  92. .IR s .
  93. Its result is always NUL-terminated and holds the maximal
  94. number of complete UTF-8 characters that can fit.
  95. .I Seprint
  96. is like
  97. .IR snprint ,
  98. except that the end is indicated by a pointer
  99. .I e
  100. rather than a count and the return value points to the terminating NUL of the
  101. resulting string.
  102. .I Smprint
  103. is like
  104. .IR sprint ,
  105. except that it prints into and returns a string of the required length, which is
  106. allocated by
  107. .IR malloc (2).
  108. .PP
  109. The routines
  110. .IR runesprint ,
  111. .IR runesnprint ,
  112. .IR runeseprint ,
  113. and
  114. .I runesmprint
  115. are the same as
  116. .IR sprint ,
  117. .IR snprint ,
  118. .IR seprint
  119. and
  120. .I smprint
  121. except that their output is rune strings instead of byte strings.
  122. .PP
  123. Finally, the routines
  124. .IR vfprint ,
  125. .IR vsnprint ,
  126. .IR vseprint ,
  127. .IR vsmprint ,
  128. .IR runevsnprint ,
  129. .IR runevseprint ,
  130. and
  131. .IR runevsmprint
  132. are like their
  133. .BR v-less
  134. relatives except they take as arguments a
  135. .B va_list
  136. parameter, so they can be called within a variadic function.
  137. The Example section shows a representative usage.
  138. .PP
  139. Each of these functions
  140. converts, formats, and prints its
  141. trailing arguments
  142. under control of a
  143. .IR format
  144. string.
  145. The
  146. format
  147. contains two types of objects:
  148. plain characters, which are simply copied to the
  149. output stream,
  150. and conversion specifications,
  151. each of which results in fetching of
  152. zero or more
  153. arguments.
  154. The results are undefined if there are arguments of the
  155. wrong type or too few
  156. arguments for the format.
  157. If the format is exhausted while
  158. arguments remain, the excess
  159. is ignored.
  160. .PP
  161. Each conversion specification has the following format:
  162. .IP
  163. .B "% [flags] verb
  164. .PP
  165. The verb is a single character and each flag is a single character or a
  166. (decimal) numeric string.
  167. Up to two numeric strings may be used;
  168. the first is called
  169. .IR width ,
  170. the second
  171. .IR precision .
  172. A period can be used to separate them, and if the period is
  173. present then
  174. .I width
  175. and
  176. .I precision
  177. are taken to be zero if missing, otherwise they are `omitted'.
  178. Either or both of the numbers may be replaced with the character
  179. .BR * ,
  180. meaning that the actual number will be obtained from the argument list
  181. as an integer.
  182. The flags and numbers are arguments to
  183. the
  184. .I verb
  185. described below.
  186. .PP
  187. The numeric verbs
  188. .BR d ,
  189. .BR o ,
  190. .BR b ,
  191. .BR x ,
  192. and
  193. .B X
  194. format their arguments in decimal,
  195. octal, binary, hexadecimal, and upper case hexadecimal.
  196. Each interprets the flags
  197. .BR 0 ,
  198. .BR h ,
  199. .BR hh ,
  200. .BR l ,
  201. .BR u ,
  202. .BR + ,
  203. .BR - ,
  204. .BR , ,
  205. and
  206. .B #
  207. to mean pad with zeros,
  208. short, byte, long, unsigned, always print a sign, left justified, commas every three digits,
  209. and alternate format.
  210. Also, a space character in the flag
  211. position is like
  212. .BR + ,
  213. but prints a space instead of a plus sign for non-negative values.
  214. If neither
  215. short nor long is specified,
  216. then the argument is an
  217. .BR int .
  218. If unsigned is specified,
  219. then the argument is interpreted as a
  220. positive number and no sign is output.
  221. If two
  222. .B l
  223. flags are given,
  224. then the argument is interpreted as a
  225. .B vlong
  226. (usually an 8-byte, sometimes a 4-byte integer).
  227. If
  228. .I precision
  229. is not omitted, the number is padded on the left with zeros
  230. until at least
  231. .I precision
  232. digits appear.
  233. Then, if alternate format is specified,
  234. for
  235. .B o
  236. conversion, the number is preceded by a
  237. .B 0
  238. if it doesn't already begin with one;
  239. for
  240. .B x
  241. conversion, the number is preceded by
  242. .BR 0x ;
  243. for
  244. .B X
  245. conversion, the number is preceded by
  246. .BR 0X .
  247. Finally, if
  248. .I width
  249. is not omitted, the number is padded on the left (or right, if
  250. left justification is specified) with enough blanks to
  251. make the field at least
  252. .I width
  253. characters long.
  254. .PP
  255. The floating point verbs
  256. .BR f ,
  257. .BR e ,
  258. .BR E ,
  259. .BR g ,
  260. and
  261. .B G
  262. take a
  263. .B double
  264. argument.
  265. Each interprets the flags
  266. .BR + ,
  267. .BR - ,
  268. and
  269. .B #
  270. to mean
  271. always print a sign,
  272. left justified,
  273. and
  274. alternate format.
  275. .I Width
  276. is the minimum field width and,
  277. if the converted value takes up less than
  278. .I width
  279. characters, it is padded on the left (or right, if `left justified')
  280. with spaces.
  281. .I Precision
  282. is the number of digits that are converted after the decimal place for
  283. .BR e ,
  284. .BR E ,
  285. and
  286. .B f
  287. conversions,
  288. and
  289. .I precision
  290. is the maximum number of significant digits for
  291. .B g
  292. and
  293. .B G
  294. conversions.
  295. The
  296. .B f
  297. verb produces output of the form
  298. .RB [ - ] digits [ .digits\fR].
  299. .B E
  300. conversion appends an exponent
  301. .BR E [ - ] digits ,
  302. and
  303. .B e
  304. conversion appends an exponent
  305. .BR e [ - ] digits .
  306. The
  307. .B g
  308. verb will output the argument in either
  309. .B e
  310. or
  311. .B f
  312. with the goal of producing the smallest output.
  313. Also, trailing zeros are omitted from the fraction part of
  314. the output, and a trailing decimal point appears only if it is followed
  315. by a digit.
  316. The
  317. .B G
  318. verb is similar, but uses
  319. .B E
  320. format instead of
  321. .BR e .
  322. When alternate format is specified, the result will always contain a decimal point,
  323. and for
  324. .B g
  325. and
  326. .B G
  327. conversions, trailing zeros are not removed.
  328. .PP
  329. The
  330. .B s
  331. verb copies a nul-terminated string
  332. (pointer to
  333. .BR char )
  334. to the output.
  335. The number of characters copied
  336. .RI ( n )
  337. is the minimum
  338. of the size of the string and
  339. .IR precision .
  340. These
  341. .I n
  342. characters are justified within a field of
  343. .I width
  344. characters as described above.
  345. If a
  346. .I precision
  347. is given, it is safe for the string not to be nul-terminated
  348. as long as it is at least
  349. .I precision
  350. characters (not bytes!) long.
  351. The
  352. .B S
  353. verb is similar, but it interprets its pointer as an array
  354. of runes (see
  355. .IR utf (6));
  356. the runes are converted to
  357. .SM UTF
  358. before output.
  359. .PP
  360. The
  361. .B c
  362. verb copies a single
  363. .B char
  364. (promoted to
  365. .BR int )
  366. justified within a field of
  367. .I width
  368. characters as described above.
  369. The
  370. .B C
  371. verb is similar, but works on runes.
  372. .PP
  373. The
  374. .B p
  375. verb formats a pointer value.
  376. At the moment, it is a synonym for
  377. .BR ux ,
  378. but that will change once pointers and integers are different sizes.
  379. .PP
  380. The
  381. .B r
  382. verb takes no arguments; it copies the error string returned by a call to
  383. .IR errstr (2).
  384. .PP
  385. Custom verbs may be installed using
  386. .IR fmtinstall (2).
  387. .SH EXAMPLE
  388. This function prints an error message with a variable
  389. number of arguments and then quits.
  390. .IP
  391. .EX
  392. .ta 6n +6n +6n
  393. void fatal(char *msg, ...)
  394. {
  395. char buf[1024], *out;
  396. va_list arg;
  397. out = seprint(buf, buf+sizeof(buf), "Fatal error: ");
  398. va_start(arg, msg);
  399. out = vseprint(out, buf+sizeof(buf), msg, arg);
  400. va_end(arg);
  401. write(2, buf, out-buf);
  402. exits("fatal error");
  403. }
  404. .EE
  405. .SH SOURCE
  406. .B /sys/src/libc/fmt
  407. .SH SEE ALSO
  408. .IR fmtinstall (2),
  409. .IR fprintf (2),
  410. .IR utf (6),
  411. .IR errstr (2)
  412. .SH DIAGNOSTICS
  413. Routines that write to a file descriptor or call
  414. .IR malloc
  415. set
  416. .IR errstr .
  417. .SH BUGS
  418. The formatting is close to that specified for ANSI
  419. .IR fprintf (2);
  420. the main difference is that
  421. .B b
  422. is not in ANSI and
  423. .B u
  424. is a flag here instead of a verb.
  425. Also, and distinctly not a bug,
  426. .I print
  427. and friends generate
  428. .SM UTF
  429. rather than
  430. .SM ASCII.
  431. .PP
  432. There is no
  433. .BR runeprint ,
  434. .BR runefprint ,
  435. etc. because runes are byte-order dependent and should not be written directly to a file; use the
  436. UTF output of
  437. .I print
  438. or
  439. .I fprint
  440. instead.
  441. Also,
  442. .I sprint
  443. is deprecated for safety reasons; use
  444. .IR snprint ,
  445. .IR seprint ,
  446. or
  447. .I smprint
  448. instead.
  449. Safety also precludes the existence of
  450. .IR runesprint .