logo

utils-std

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

printf.1 (11427B)


  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 May 26, 2025
  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
  78. .St -isoC-2011 ,
  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 \ee
  89. Write an <escape> character.
  90. .It Cm \ef
  91. Write a <form-feed> character.
  92. .It Cm \en
  93. Write a <new-line> character.
  94. .It Cm \er
  95. Write a <carriage return> character.
  96. .It Cm \et
  97. Write a <tab> character.
  98. .It Cm \ev
  99. Write a <vertical tab> character.
  100. .It Cm \e\(aq
  101. Write a <single quote> character.
  102. .It Cm \e\e
  103. Write a backslash character.
  104. .It Cm \ec | Cm \ec Ns Ar char
  105. In
  106. .Cm %b
  107. cut the string argument and make
  108. .Nm printf
  109. exits.
  110. .Pp
  111. Otherwise as format conversion escape: Write a control character, where:
  112. .Bl -bullet -compact
  113. .It
  114. .Cm @
  115. is 0x00 / NULL,
  116. .It
  117. .Cm A-Z
  118. /
  119. .Cm a-z
  120. corresponds to 0x01-0x1A,
  121. .It
  122. .Cm \(lB
  123. is 0x1B / ESC / Escape,
  124. .It
  125. .Cm \(rs
  126. is 0x1C / FS / Field-Separator,
  127. .It
  128. .Cm \(rB
  129. is 0x1D / GS / Group-Separator,
  130. .It
  131. .Cm ^
  132. is 0x1E / RS / Record-Separator,
  133. .\" not sure how to tell mandoc to include the underscore as Cm argument
  134. .It
  135. .Cm _
  136. is 0x1F / US / Unit-Separator,
  137. .It
  138. .Cm \&?
  139. is 0x7F / DEL / Delete.
  140. .El
  141. Note that the values corresponds to circumflex escapes (ie. ^A == \ecA).
  142. .It Cm \ex Ns Ar hex-num
  143. Write a byte whose
  144. value is the 1- or 2-digits
  145. hexadecimal number
  146. .Ar hex-num .
  147. .It Cm \e Ns Ar num
  148. Write a byte whose
  149. value is the 1-, 2-, or 3-digit
  150. octal number
  151. .Ar num .
  152. .El
  153. Multibyte characters can be constructed using multiple
  154. .Cm \ex Ns Ar hex-num
  155. or
  156. .Cm \e Ns Ar num
  157. sequences.
  158. .Pp
  159. Each format specification is introduced by the percent character
  160. (``%'').
  161. The remainder of the format specification includes,
  162. in the following order:
  163. .Bl -tag -width Ds
  164. .It "Zero or more of the following flags:"
  165. .Bl -tag -width Ds
  166. .It Cm #
  167. A `#' character
  168. specifying that the value should be printed in an ``alternate form''.
  169. For
  170. .Cm b , c , d , s
  171. and
  172. .Cm u
  173. formats, this option has no effect.
  174. For the
  175. .Cm o
  176. formats the precision of the number is increased to force the first
  177. character of the output string to a zero.
  178. For the
  179. .Cm x
  180. .Pq Cm X
  181. format, a non-zero result has the string
  182. .Li 0x
  183. .Pq Li 0X
  184. prepended to it.
  185. For
  186. .Cm a , A , e , E , f , F , g
  187. and
  188. .Cm G
  189. formats, the result will always contain a decimal point, even if no
  190. digits follow the point (normally, a decimal point only appears in the
  191. results of those formats if a digit follows the decimal point).
  192. For
  193. .Cm g
  194. and
  195. .Cm G
  196. formats, trailing zeros are not removed from the result as they
  197. would otherwise be;
  198. .It Cm \&\-
  199. A minus sign `\-' which specifies
  200. .Em left adjustment
  201. of the output in the indicated field;
  202. .It Cm \&+
  203. A `+' character specifying that there should always be
  204. a sign placed before the number when using signed formats.
  205. .It Sq \&\ \&
  206. A space specifying that a blank should be left before a positive number
  207. for a signed format.
  208. A `+' overrides a space if both are used;
  209. .It Cm \&0
  210. A zero `0' character indicating that zero-padding should be used
  211. rather than blank-padding.
  212. A `\-' overrides a `0' if both are used;
  213. .El
  214. .It "Field Width:"
  215. An optional digit string specifying a
  216. .Em field width ;
  217. if the output string has fewer bytes than the field width it will
  218. be blank-padded on the left (or right, if the left-adjustment indicator
  219. has been given) to make up the field width (note that a leading zero
  220. is a flag, but an embedded zero is part of a field width);
  221. .It Precision:
  222. An optional period,
  223. .Sq Cm \&.\& ,
  224. followed by an optional digit string giving a
  225. .Em precision
  226. which specifies the number of digits to appear after the decimal point,
  227. for
  228. .Cm e
  229. and
  230. .Cm f
  231. formats, or the maximum number of bytes to be printed
  232. from a string; if the digit string is missing, the precision is treated
  233. as zero;
  234. .It Format:
  235. A character which indicates the type of format to use (one of
  236. .Cm diouxXfFeEgGaAcsb ) .
  237. The uppercase formats differ from their lowercase counterparts only in
  238. that the output of the former is entirely in uppercase.
  239. The floating-point format specifiers
  240. .Pq Cm fFeEgGaA
  241. may be prefixed by an
  242. .Cm L
  243. to request that additional precision be used, if available.
  244. .El
  245. .Pp
  246. A field width or precision may be
  247. .Sq Cm \&*
  248. instead of a digit string.
  249. In this case an
  250. .Ar argument
  251. supplies the field width or precision.
  252. .Pp
  253. The format characters and their meanings are:
  254. .Bl -tag -width Fl
  255. .It Cm diouXx
  256. The
  257. .Ar argument
  258. is printed as a signed decimal (d or i), unsigned octal, unsigned decimal,
  259. or unsigned hexadecimal (X or x), respectively.
  260. .It Cm fF
  261. The
  262. .Ar argument
  263. is printed in the style `[\-]ddd.ddd' where the number of d's
  264. after the decimal point is equal to the precision specification for
  265. the argument.
  266. If the precision is missing, 6 digits are given; if the precision
  267. is explicitly 0, no digits and no decimal point are printed.
  268. The values \*[If] and \*[Na] are printed as
  269. .Ql inf
  270. and
  271. .Ql nan ,
  272. respectively.
  273. .It Cm eE
  274. The
  275. .Ar argument
  276. is printed in the style
  277. .Cm e
  278. .Sm off
  279. .Sq Op - Ar d.ddd No \(+- Ar dd
  280. .Sm on
  281. where there
  282. is one digit before the decimal point and the number after is equal to
  283. the precision specification for the argument; when the precision is
  284. missing, 6 digits are produced.
  285. The values \*[If] and \*[Na] are printed as
  286. .Ql inf
  287. and
  288. .Ql nan ,
  289. respectively.
  290. .It Cm gG
  291. The
  292. .Ar argument
  293. is printed in style
  294. .Cm f
  295. .Pq Cm F
  296. or in style
  297. .Cm e
  298. .Pq Cm E
  299. whichever gives full precision in minimum space.
  300. .It Cm aA
  301. The
  302. .Ar argument
  303. is printed in style
  304. .Sm off
  305. .Sq Op - Ar h.hhh No \(+- Li p Ar d
  306. .Sm on
  307. where there is one digit before the hexadecimal point and the number
  308. after is equal to the precision specification for the argument;
  309. when the precision is missing, enough digits are produced to convey
  310. the argument's exact double-precision floating-point representation.
  311. The values \*[If] and \*[Na] are printed as
  312. .Ql inf
  313. and
  314. .Ql nan ,
  315. respectively.
  316. .It Cm c
  317. The first byte of
  318. .Ar argument
  319. is printed.
  320. .It Cm s
  321. Bytes from the string
  322. .Ar argument
  323. are printed until the end is reached or until the number of bytes
  324. indicated by the precision specification is reached; however if the
  325. precision is 0 or missing, the string is printed entirely.
  326. .It Cm b
  327. As for
  328. .Cm s ,
  329. but interpret character escapes in backslash notation in the string
  330. .Ar argument .
  331. The permitted escape sequences are slightly different in that
  332. octal escapes are
  333. .Cm \e0 Ns Ar num
  334. instead of
  335. .Cm \e Ns Ar num
  336. and that an additional escape sequence
  337. .Cm \ec
  338. stops further output from this
  339. .Nm
  340. invocation.
  341. .It Cm q
  342. Print
  343. .Ar argument
  344. so it can be reused for shell input,
  345. escaping control characters and single-quote with POSIX.1-2024
  346. .Cm $''
  347. (dollar-single-quote) syntax.
  348. .It Cm n$
  349. Allows reordering of the output according to
  350. .Ar argument .
  351. .It Cm \&%
  352. Print a `%'; no argument is used.
  353. .El
  354. .Pp
  355. The decimal point
  356. character is defined in the program's locale (category
  357. .Dv LC_NUMERIC ) .
  358. .Pp
  359. In no case does a non-existent or small field width cause truncation of
  360. a field; padding takes place only if the specified field width exceeds
  361. the actual width.
  362. .Pp
  363. Some shells may provide a builtin
  364. .Nm
  365. command which is similar or identical to this utility.
  366. .Sh EXIT STATUS
  367. .Ex -std
  368. .Sh EXAMPLES
  369. Print the string
  370. .Qq hello :
  371. .Bd -literal -offset indent
  372. $ printf "%s\en" hello
  373. hello
  374. .Ed
  375. .Pp
  376. Same as above, but notice that the format string is not quoted and hence we
  377. do not get the expected behavior:
  378. .Bd -literal -offset indent
  379. $ printf %s\en hello
  380. hellon$
  381. .Ed
  382. .Pp
  383. Print arguments forcing sign only for the first argument:
  384. .Bd -literal -offset indent
  385. $ printf "%+d\en%d\en%d\en" 1 -2 13
  386. +1
  387. -2
  388. 13
  389. .Ed
  390. .Pp
  391. Same as above, but the single format string will be applied to the three
  392. arguments:
  393. .Bd -literal -offset indent
  394. $ printf "%+d\en" 1 -2 13
  395. +1
  396. -2
  397. +13
  398. .Ed
  399. .Pp
  400. Print number using only two digits after the decimal point:
  401. .Bd -literal -offset indent
  402. $ printf "%.2f\en" 31.7456
  403. 31.75
  404. .Ed
  405. .Sh COMPATIBILITY
  406. The traditional
  407. .Bx
  408. behavior of converting arguments of numeric formats not beginning
  409. with a digit to the ASCII
  410. code of the first character is not supported.
  411. .Sh SEE ALSO
  412. .Xr echo 1 ,
  413. .Xr sh 1 ,
  414. .Xr printf 3
  415. .Sh STANDARDS
  416. The
  417. .Nm
  418. utility should be compliant with the
  419. IEEE Std 1003.1-2024 (“POSIX.1”) specification.
  420. .Pp
  421. The
  422. .Cm \ee ,
  423. .Cm \ec Ns Ar char ,
  424. and
  425. .Cm \ex Ns Ar hex-num
  426. backslash-escapes are extensions
  427. inspired by
  428. .Xr sh 1 Ns 's
  429. dollar-single-quote($'…') escapes.
  430. .Pp
  431. The
  432. .Cm %q
  433. format specifier is an extension inspired by GNU coreutils.
  434. .Sh HISTORY
  435. The
  436. .Nm
  437. command appeared in
  438. .Bx 4.3 Reno .
  439. It is modeled
  440. after the standard library function,
  441. .Xr printf 3 .