logo

utils-std

Collection of commonly available Unix tools git clone https://anongit.hacktivis.me/git/utils-std.git

printf.1 (11442B)


  1. .\" SPDX-License-Identifier: BSD-3-Clause
  2. .\" Copyright (c) 1989, 1990, 1993
  3. .\" The Regents of the University of California. All rights reserved.
  4. .\"
  5. .\" This code is derived from software contributed to Berkeley by
  6. .\" the Institute of Electrical and Electronics Engineers, Inc.
  7. .\"
  8. .\" Redistribution and use in source and binary forms, with or without
  9. .\" modification, are permitted provided that the following conditions
  10. .\" are met:
  11. .\" 1. Redistributions of source code must retain the above copyright
  12. .\" notice, this list of conditions and the following disclaimer.
  13. .\" 2. Redistributions in binary form must reproduce the above copyright
  14. .\" notice, this list of conditions and the following disclaimer in the
  15. .\" documentation and/or other materials provided with the distribution.
  16. .\" 3. Neither the name of the University nor the names of its contributors
  17. .\" may be used to endorse or promote products derived from this software
  18. .\" without specific prior written permission.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .Dd July 1, 2020
  33. .Dt PRINTF 1
  34. .Os
  35. .Sh NAME
  36. .Nm printf
  37. .Nd formatted output
  38. .Sh SYNOPSIS
  39. .Nm
  40. .Ar format Op Ar argument...
  41. .Sh DESCRIPTION
  42. The
  43. .Nm
  44. utility formats and prints its arguments, after the first, under control
  45. of the
  46. .Ar format .
  47. The
  48. .Ar format
  49. is a character string which contains three types of objects: plain characters,
  50. which are simply copied to standard output, character escape sequences which
  51. are converted and copied to the standard output, and format specifications,
  52. each of which causes printing of the next successive
  53. .Ar argument .
  54. .Pp
  55. The
  56. .Ar argument
  57. after the first are treated as strings if the corresponding format is
  58. either
  59. .Cm c , b
  60. or
  61. .Cm s ;
  62. otherwise it is evaluated as a C constant, with the following extensions:
  63. .Pp
  64. .Bl -bullet -offset indent -compact
  65. .It
  66. A leading plus or minus sign is allowed.
  67. .It
  68. If the leading character is a single or double quote, the value is the
  69. character code of the next character.
  70. .El
  71. .Pp
  72. The format string is reused as often as necessary to satisfy the
  73. .Ar argument .
  74. Any extra format specifications are evaluated with zero or the null
  75. string.
  76. .Pp
  77. Character escape sequences are in backslash notation as defined in the
  78. .St -ansiC ,
  79. with extensions.
  80. The characters and their meanings
  81. are as follows:
  82. .Pp
  83. .Bl -tag -width Ds -offset indent -compact
  84. .It Cm \ea
  85. Write a <bell> character.
  86. .It Cm \eb
  87. Write a <backspace> character.
  88. .It Cm \ef
  89. Write a <form-feed> character.
  90. .It Cm \en
  91. Write a <new-line> character.
  92. .It Cm \er
  93. Write a <carriage return> character.
  94. .It Cm \et
  95. Write a <tab> character.
  96. .It Cm \ev
  97. Write a <vertical tab> character.
  98. .It Cm \e\'
  99. Write a <single quote> character.
  100. .It Cm \e\e
  101. Write a backslash character.
  102. .It Cm \ex Ns Ar hex-num
  103. Write a byte whose
  104. value is the 1- or 2-digits
  105. hexadecimal number
  106. .Ar hex-num .
  107. .It Cm \e Ns Ar num
  108. Write a byte whose
  109. value is the 1-, 2-, or 3-digit
  110. octal number
  111. .Ar num .
  112. .El
  113. Multibyte characters can be constructed using multiple
  114. .Cm \ex Ns Ar hex-num
  115. or
  116. .Cm \e Ns Ar num
  117. sequences.
  118. .Pp
  119. Each format specification is introduced by the percent character
  120. (``%'').
  121. The remainder of the format specification includes,
  122. in the following order:
  123. .Bl -tag -width Ds
  124. .It "Zero or more of the following flags:"
  125. .Bl -tag -width Ds
  126. .It Cm #
  127. A `#' character
  128. specifying that the value should be printed in an ``alternate form''.
  129. For
  130. .Cm b , c , d , s
  131. and
  132. .Cm u
  133. formats, this option has no effect.
  134. For the
  135. .Cm o
  136. formats the precision of the number is increased to force the first
  137. character of the output string to a zero.
  138. For the
  139. .Cm x
  140. .Pq Cm X
  141. format, a non-zero result has the string
  142. .Li 0x
  143. .Pq Li 0X
  144. prepended to it.
  145. For
  146. .Cm a , A , e , E , f , F , g
  147. and
  148. .Cm G
  149. formats, the result will always contain a decimal point, even if no
  150. digits follow the point (normally, a decimal point only appears in the
  151. results of those formats if a digit follows the decimal point).
  152. For
  153. .Cm g
  154. and
  155. .Cm G
  156. formats, trailing zeros are not removed from the result as they
  157. would otherwise be;
  158. .It Cm \&\-
  159. A minus sign `\-' which specifies
  160. .Em left adjustment
  161. of the output in the indicated field;
  162. .It Cm \&+
  163. A `+' character specifying that there should always be
  164. a sign placed before the number when using signed formats.
  165. .It Sq \&\ \&
  166. A space specifying that a blank should be left before a positive number
  167. for a signed format.
  168. A `+' overrides a space if both are used;
  169. .It Cm \&0
  170. A zero `0' character indicating that zero-padding should be used
  171. rather than blank-padding.
  172. A `\-' overrides a `0' if both are used;
  173. .El
  174. .It "Field Width:"
  175. An optional digit string specifying a
  176. .Em field width ;
  177. if the output string has fewer bytes than the field width it will
  178. be blank-padded on the left (or right, if the left-adjustment indicator
  179. has been given) to make up the field width (note that a leading zero
  180. is a flag, but an embedded zero is part of a field width);
  181. .It Precision:
  182. An optional period,
  183. .Sq Cm \&.\& ,
  184. followed by an optional digit string giving a
  185. .Em precision
  186. which specifies the number of digits to appear after the decimal point,
  187. for
  188. .Cm e
  189. and
  190. .Cm f
  191. formats, or the maximum number of bytes to be printed
  192. from a string; if the digit string is missing, the precision is treated
  193. as zero;
  194. .It Format:
  195. A character which indicates the type of format to use (one of
  196. .Cm diouxXfFeEgGaAcsb ) .
  197. The uppercase formats differ from their lowercase counterparts only in
  198. that the output of the former is entirely in uppercase.
  199. The floating-point format specifiers
  200. .Pq Cm fFeEgGaA
  201. may be prefixed by an
  202. .Cm L
  203. to request that additional precision be used, if available.
  204. .El
  205. .Pp
  206. A field width or precision may be
  207. .Sq Cm \&*
  208. instead of a digit string.
  209. In this case an
  210. .Ar argument
  211. supplies the field width or precision.
  212. .Pp
  213. The format characters and their meanings are:
  214. .Bl -tag -width Fl
  215. .It Cm diouXx
  216. The
  217. .Ar argument
  218. is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
  219. or unsigned hexadecimal (X or x), respectively.
  220. .It Cm fF
  221. The
  222. .Ar argument
  223. is printed in the style `[\-]ddd.ddd' where the number of d's
  224. after the decimal point is equal to the precision specification for
  225. the argument.
  226. If the precision is missing, 6 digits are given; if the precision
  227. is explicitly 0, no digits and no decimal point are printed.
  228. The values \*[If] and \*[Na] are printed as
  229. .Ql inf
  230. and
  231. .Ql nan ,
  232. respectively.
  233. .It Cm eE
  234. The
  235. .Ar argument
  236. is printed in the style
  237. .Cm e
  238. .Sm off
  239. .Sq Op - Ar d.ddd No \(+- Ar dd
  240. .Sm on
  241. where there
  242. is one digit before the decimal point and the number after is equal to
  243. the precision specification for the argument; when the precision is
  244. missing, 6 digits are produced.
  245. The values \*[If] and \*[Na] are printed as
  246. .Ql inf
  247. and
  248. .Ql nan ,
  249. respectively.
  250. .It Cm gG
  251. The
  252. .Ar argument
  253. is printed in style
  254. .Cm f
  255. .Pq Cm F
  256. or in style
  257. .Cm e
  258. .Pq Cm E
  259. whichever gives full precision in minimum space.
  260. .It Cm aA
  261. The
  262. .Ar argument
  263. is printed in style
  264. .Sm off
  265. .Sq Op - Ar h.hhh No \(+- Li p Ar d
  266. .Sm on
  267. where there is one digit before the hexadecimal point and the number
  268. after is equal to the precision specification for the argument;
  269. when the precision is missing, enough digits are produced to convey
  270. the argument's exact double-precision floating-point representation.
  271. The values \*[If] and \*[Na] are printed as
  272. .Ql inf
  273. and
  274. .Ql nan ,
  275. respectively.
  276. .It Cm c
  277. The first byte of
  278. .Ar argument
  279. is printed.
  280. .It Cm s
  281. Bytes from the string
  282. .Ar argument
  283. are printed until the end is reached or until the number of bytes
  284. indicated by the precision specification is reached; however if the
  285. precision is 0 or missing, the string is printed entirely.
  286. .It Cm b
  287. As for
  288. .Cm s ,
  289. but interpret character escapes in backslash notation in the string
  290. .Ar argument .
  291. The permitted escape sequences are slightly different in that
  292. octal escapes are
  293. .Cm \e0 Ns Ar num
  294. instead of
  295. .Cm \e Ns Ar num
  296. and that an additional escape sequence
  297. .Cm \ec
  298. stops further output from this
  299. .Nm
  300. invocation.
  301. .It Cm n$
  302. Allows reordering of the output according to
  303. .Ar argument .
  304. .It Cm \&%
  305. Print a `%'; no argument is used.
  306. .El
  307. .Pp
  308. The decimal point
  309. character is defined in the program's locale (category
  310. .Dv LC_NUMERIC ) .
  311. .Pp
  312. In no case does a non-existent or small field width cause truncation of
  313. a field; padding takes place only if the specified field width exceeds
  314. the actual width.
  315. .Pp
  316. Some shells may provide a builtin
  317. .Nm
  318. command which is similar or identical to this utility.
  319. Consult the
  320. .Xr builtin 1
  321. manual page.
  322. .Sh EXIT STATUS
  323. .Ex -std
  324. .Sh EXAMPLES
  325. Print the string
  326. .Qq hello :
  327. .Bd -literal -offset indent
  328. $ printf "%s\en" hello
  329. hello
  330. .Ed
  331. .Pp
  332. Same as above, but notice that the format string is not quoted and hence we
  333. do not get the expected behavior:
  334. .Bd -literal -offset indent
  335. $ printf %s\en hello
  336. hellon$
  337. .Ed
  338. .Pp
  339. Print arguments forcing sign only for the first argument:
  340. .Bd -literal -offset indent
  341. $ printf "%+d\en%d\en%d\en" 1 -2 13
  342. +1
  343. -2
  344. 13
  345. .Ed
  346. .Pp
  347. Same as above, but the single format string will be applied to the three
  348. arguments:
  349. .Bd -literal -offset indent
  350. $ printf "%+d\en" 1 -2 13
  351. +1
  352. -2
  353. +13
  354. .Ed
  355. .Pp
  356. Print number using only two digits after the decimal point:
  357. .Bd -literal -offset indent
  358. $ printf "%.2f\en" 31.7456
  359. 31.75
  360. .Ed
  361. .Sh COMPATIBILITY
  362. The traditional
  363. .Bx
  364. behavior of converting arguments of numeric formats not beginning
  365. with a digit to the ASCII
  366. code of the first character is not supported.
  367. .Sh SEE ALSO
  368. .Xr builtin 1 ,
  369. .Xr echo 1 ,
  370. .Xr sh 1 ,
  371. .Xr printf 3
  372. .Sh STANDARDS
  373. The
  374. .Nm
  375. command is expected to be compatible with the
  376. .St -p1003.2
  377. specification.
  378. The
  379. .Cm \ex Ns Ar hex-num
  380. backslash-escape is an extension.
  381. .Sh HISTORY
  382. The
  383. .Nm
  384. command appeared in
  385. .Bx 4.3 Reno .
  386. It is modeled
  387. after the standard library function,
  388. .Xr printf 3 .
  389. .Sh CAVEATS
  390. ANSI hexadecimal character constants were deliberately not provided.
  391. .Pp
  392. Trying to print a dash ("-") as the first character causes
  393. .Nm
  394. to interpret the dash as a program argument.
  395. .Nm --
  396. must be used before
  397. .Ar format .
  398. .Pp
  399. If the locale contains multibyte characters
  400. (such as UTF-8),
  401. the
  402. .Cm c
  403. format and
  404. .Cm b
  405. and
  406. .Cm s
  407. formats with a precision
  408. may not operate as expected.
  409. .Sh BUGS
  410. Since the floating point numbers are translated from ASCII
  411. to floating-point and then back again, floating-point precision may be lost.
  412. (By default, the number is translated to an IEEE-754 double-precision
  413. value before being printed.
  414. The
  415. .Cm L
  416. modifier may produce additional precision, depending on the hardware platform.)
  417. .Pp
  418. The escape sequence \e000 is the string terminator.
  419. When present in the argument for the
  420. .Cm b
  421. format, the argument will be truncated at the \e000 character.
  422. .Pp
  423. Multibyte characters are not recognized in format strings (this is only
  424. a problem if
  425. .Ql %
  426. can appear inside a multibyte character).