You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

1035 lines
25 KiB

  1. .\" Copyright (c) 1990, 1991, 1993
  2. .\" The Regents of the University of California. All rights reserved.
  3. .\" Copyright (c) 2013 Matthew Seaman <matthew@FreeBSD.org>
  4. .\"
  5. .\" This code is derived from software contributed to Berkeley by
  6. .\" Chris Torek and the American National Standards Committee X3,
  7. .\" on Information Processing Systems.
  8. .\"
  9. .\" Redistribution and use in source and binary forms, with or without
  10. .\" modification, are permitted provided that the following conditions
  11. .\" are met:
  12. .\" 1. Redistributions of source code must retain the above copyright
  13. .\" notice, this list of conditions and the following disclaimer.
  14. .\" 2. Redistributions in binary form must reproduce the above copyright
  15. .\" notice, this list of conditions and the following disclaimer in the
  16. .\" documentation and/or other materials provided with the distribution.
  17. .\" 4. Neither the name of the University nor the names of its contributors
  18. .\" may be used to endorse or promote products derived from this software
  19. .\" without specific prior written permission.
  20. .\"
  21. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31. .\" SUCH DAMAGE.
  32. .\"
  33. .Dd November 18, 2014
  34. .Dt PKG_PRINTF 3
  35. .Os
  36. .Sh NAME
  37. .Nm pkg_printf , pkg_fprintf , pkg_dprintf , pkg_snprintf , pkg_asprintf ,
  38. .Nm pkg_sbuf_printf ,
  39. .Nm pkg_vprintf , pkg_vfprintf , pkg_vdprintf , pkg_vsnprintf , pkg_vasprintf ,
  40. .Nm pkg_sbuf_vprintf
  41. .Nd formatted output of package data
  42. .Sh LIBRARY
  43. .Lb libpkg
  44. .Sh SYNOPSIS
  45. .In pkg.h
  46. .Ft int
  47. .Fn pkg_printf "const char * restrict format" ...
  48. .Ft int
  49. .Fn pkg_fprintf "FILE * restrict stream" "const char * restrict format" ...
  50. .Ft int
  51. .Fn pkg_dprintf "int fd" "const char * restrict format" ...
  52. .Ft int
  53. .Fn pkg_snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
  54. .Ft int
  55. .Fn pkg_asprintf "char **ret" "const char * restrict format" ...
  56. .Ft struct sbuf *
  57. .Fn pkg_sbuf_printf "struct sbuf * restrict sbuf" "const char * restrict format" ...
  58. .In stdarg.h
  59. .Ft int
  60. .Fn pkg_vprintf "const char * restrict format" "va_list ap"
  61. .Ft int
  62. .Fn pkg_vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
  63. .Ft int
  64. .Fn pkg_vdprintf "int fd" "const char * restrict format" "va_list ap"
  65. .Ft int
  66. .Fn pkg_vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
  67. .Ft int
  68. .Fn pkg_vasprintf "char **ret" "const char * restrict format" "va_list ap"
  69. .Ft struct sbuf *
  70. .Fn pkg_sbuf_vprintf "struct sbuf * restrict sbuf" "const char * restrict format" "va_list ap"
  71. .Sh DESCRIPTION
  72. The
  73. .Fn pkg_printf
  74. family of functions produces output of package data according to a
  75. .Fa format
  76. as described below, analogously to the similarly named
  77. .Xr printf 3
  78. family of functions.
  79. The
  80. .Fn pkg_printf
  81. and
  82. .Fn pkg_vprintf
  83. functions
  84. write output to
  85. .Dv stdout ,
  86. the standard output stream;
  87. .Fn pkg_fprintf
  88. and
  89. .Fn pkg_vfprintf
  90. write output to the given output
  91. .Fa stream ;
  92. .Fn pkg_dprintf
  93. and
  94. .Fn pkg_vdprintf
  95. write output to the given file descriptor;
  96. .Fn pkg_snprintf
  97. and
  98. .Fn pkg_vsnprintf
  99. write to the character string
  100. .Fa str ;
  101. .Fn pkg_asprintf
  102. and
  103. .Fn pkg_vasprintf
  104. dynamically allocate a new string with
  105. .Xr malloc 3
  106. to write to;
  107. .Fn pkg_sbuf_printf
  108. and
  109. .Fn pkg_sbuf_vprintf
  110. write to the given sbuf structure.
  111. .Pp
  112. These functions write the output under the control of a
  113. .Fa format
  114. string that specifies how subsequent arguments
  115. (or arguments accessed via the variable-length argument facilities of
  116. .Xr stdarg 3 )
  117. are converted for output.
  118. .Pp
  119. These functions return the number of characters printed
  120. (not including the trailing
  121. .Ql \e0
  122. used to end output to strings) or a negative value if an output error occurs,
  123. except for
  124. .Fn pkg_snprintf
  125. or
  126. .Fn pkg_vsnprintf
  127. which return the number of characters that would have been printed if the
  128. .Fa size
  129. were unlimited
  130. (again, not including the final
  131. .Ql \e0 )
  132. and the two functions
  133. .Fn pkg_sbuf_printf
  134. and
  135. .Fn pkg_sbuf_vprintf
  136. which return the given sbuf pointer, or
  137. .Dv NULL
  138. in the case of errors.
  139. .Pp
  140. The
  141. .Fn pkg_asprintf
  142. and
  143. .Fn pkg_vasprintf
  144. functions set
  145. .Fa *ret
  146. to be a pointer to a buffer sufficiently large to hold the formatted string.
  147. This pointer should be passed to
  148. .Xr free 3
  149. to release the allocated storage when it is no longer needed.
  150. If sufficient space cannot be allocated,
  151. .Fn pkg_asprintf
  152. and
  153. .Fn pkg_vasprintf
  154. will return \-1 and set
  155. .Fa ret
  156. to be a
  157. .Dv NULL
  158. pointer.
  159. .Pp
  160. The
  161. .Fn pkg_snprintf
  162. and
  163. .Fn pkg_vsnprintf
  164. functions will write at most
  165. .Fa size Ns \-1
  166. of the characters printed into the output string
  167. (the
  168. .Fa size Ns 'th
  169. character then gets the terminating
  170. .Ql \e0 ) ;
  171. if the return value is greater than or equal to the
  172. .Fa size
  173. argument, the string was too short
  174. and some of the printed characters were discarded.
  175. The output is always null-terminated.
  176. .Pp
  177. The format string is composed of zero or more directives:
  178. ordinary
  179. .\" multibyte
  180. characters (not
  181. .Cm % ) ,
  182. which are copied unchanged to the output stream;
  183. and conversion specifications, each of which results
  184. in fetching zero or more subsequent arguments.
  185. Each conversion specification is introduced by
  186. the
  187. .Cm %
  188. character.
  189. The arguments must correspond properly with the conversion specifier.
  190. After the
  191. .Cm % ,
  192. the following appear in sequence:
  193. .Bl -bullet
  194. .It
  195. Zero or more of the following flags:
  196. .Bl -tag -width ".So \ Sc (space)"
  197. .It Cm \&?
  198. The value should be converted to the
  199. .Dq first alternate form .
  200. .Pp
  201. For integer valued conversions
  202. .Cm ( I , s
  203. and
  204. .Cm t )
  205. this is a
  206. .Vt humanized
  207. form as a floating point value scaled to the range 0 \- 1000
  208. followed by the SI powers-of-10 scale factor.
  209. See
  210. .Sx SCALE FACTORS .
  211. .Pp
  212. For array valued conversions
  213. .Cm ( A, B , C , D , F , G , L , O , U , d ,
  214. and
  215. .Cm r )
  216. generate
  217. .Dq 0
  218. if there are no items in the array,
  219. .Dq 1
  220. otherwise.
  221. .Pp
  222. For formats returning file modes
  223. .Cm ( Dp
  224. or
  225. .Cm Fp )
  226. print the mode in the style of
  227. .Xr strmode 3 .
  228. .Pp
  229. For boolean valued formats
  230. .Cm ( dk , rk , a
  231. and
  232. .Cm k )
  233. generate either
  234. .Dq yes
  235. or
  236. .Dq no
  237. for
  238. .Sq true
  239. and
  240. .Sq false
  241. respectively.
  242. .Pp
  243. For the licence logic format
  244. .Cm (l)
  245. generate
  246. .Dq \^
  247. (empty),
  248. .Dq &
  249. or
  250. .Dq |
  251. for types
  252. .Sq SINGLE ,
  253. .Sq AND
  254. and
  255. .Sq OR
  256. respectively.
  257. .It Cm #
  258. The value should be converted to the
  259. .Dq second alternate form .
  260. .Pp
  261. For the integer valued conversions
  262. .Cm ( I , s , t )
  263. this is a
  264. .Dq humanized
  265. form as a floating point value scaled to the range 0 \- 1024
  266. followed by the IEE/IEC and SI powers-of-2 scale factor.
  267. See
  268. .Sx SCALE FACTORS .
  269. .Pp
  270. For array valued conversions
  271. .Cm ( A, B , C , D , F , G , L , O , U , d ,
  272. and
  273. .Cm r )
  274. generate the number of items in the array.
  275. .Pp
  276. For formats returning file modes
  277. .Cm ( Dp
  278. or
  279. .Cm Fp )
  280. print the mode as an octal integer with a leading 0.
  281. .Pp
  282. For boolean valued formats
  283. .Cm ( dk , rk , a
  284. and
  285. .Cm k )
  286. generate either
  287. .Dq (*)
  288. or
  289. .Dq \^
  290. (empty) for
  291. .Sq true
  292. and
  293. .Sq false
  294. respectively.
  295. .Pp
  296. For the licence logic format
  297. .Cm (l)
  298. generate
  299. .Dq == ,
  300. .Dq &&
  301. or
  302. .Dq ||
  303. for types
  304. .Sq SINGLE ,
  305. .Sq AND
  306. and
  307. .Sq OR
  308. respectively.
  309. .It Cm 0 (zero)
  310. Zero padding.
  311. For all integer valued conversions and humanized numbers the converted
  312. value is padded on the left with zeros rather than blanks.
  313. .It Cm \-
  314. A negative field width flag;
  315. the converted value is to be left adjusted on the field boundary.
  316. The converted value is padded on the right with blanks,
  317. rather than on the left with blanks or zeros.
  318. Applies to all scalar-valued conversions.
  319. .Dq Cm \-
  320. overrides a
  321. .Dq Cm 0
  322. if both are given.
  323. .It So "\ " Sc (space)
  324. A blank should be left before a positive number
  325. produced by a signed conversion
  326. .Cm ( I , s ,
  327. or
  328. .Cm t ) .
  329. .It Cm +
  330. A sign must always be placed before an integer or humanized
  331. number produced by a numerical conversion.
  332. A
  333. .Dq Cm +
  334. overrides a space if both are used.
  335. .It Sq Cm '
  336. Numerical (integer) conversions should be grouped and separated by
  337. thousands using the non-monetary separator returned by
  338. .Xr localeconv 3 .
  339. Has no visible effect in the default
  340. .Dq C
  341. locale.
  342. .El
  343. .It
  344. An optional decimal digit string specifying a minimum field width.
  345. If the converted value has fewer characters than the field width,
  346. it will be padded with spaces (or zeroes, if the zero-padding flag has
  347. been given and the conversion supports it) on the left (or spaces on
  348. the right, if the left-adjustment flag has been given) to fill out the
  349. field width.
  350. .It
  351. One or two characters that specify the type of conversion to be applied.
  352. .It
  353. An optional
  354. .Dq row format
  355. for array valued conversions
  356. .Cm ( A, B , C , D , F , G , L , O , U , d ,
  357. and
  358. .Cm r )
  359. or the timestamp value conversion
  360. .Cm ( t ) .
  361. Which conversion characters are permissible in the row format is
  362. context dependent.
  363. See the
  364. .Sx FORMAT CODES
  365. section for details.
  366. .El
  367. .Ss SCALE FACTORS
  368. Humanized number conversions scale the number to lie within
  369. the range 1 \- 1000 (power of ten conversions using the
  370. .Cm \&?
  371. format modifier) or 1 \- 1024 (power of two conversions using the
  372. .Cm #
  373. format modifier) and append a scale factor as follows:
  374. .Pp
  375. The SI power of ten suffixes are
  376. .Bl -column "Suffix" "Description" "1,000,000,000,000,000,000" -offset indent
  377. .It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier"
  378. .It Li \^ Ta No (none) Ta 1
  379. .It Li k Ta No kilo Ta 1,000
  380. .It Li M Ta No mega Ta 1,000,000
  381. .It Li G Ta No giga Ta 1,000,000,000
  382. .It Li T Ta No tera Ta 1,000,000,000,000
  383. .It Li P Ta No peta Ta 1,000,000,000,000,000
  384. .It Li E Ta No exa Ta 1,000,000,000,000,000,000
  385. .El
  386. .Pp
  387. The IEE/IEC (and now also SI) power of two suffixes are:
  388. .Bl -column "Suffix" "Description" "1,000,000,000,000,000,000" -offset indent
  389. .It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier"
  390. .It Li \^ Ta No (none) Ta 1
  391. .It Li Ki Ta No kibi Ta 1,024
  392. .It Li Mi Ta No mebi Ta 1,048,576
  393. .It Li Gi Ta No gibi Ta 1,073,741,824
  394. .It Li Ti Ta No tebi Ta 1,099,511,627,776
  395. .It Li Pi Ta No pebi Ta 1,125,899,906,842,624
  396. .It Li Ei Ta No exbi Ta 1,152,921,504,606,846,976
  397. .El
  398. .Ss FORMAT CODES
  399. Format codes will format the output classified as the type shown in
  400. square brackets.
  401. .Cm %\^I
  402. is unique in that it can only be used inside a
  403. .Dq row format.
  404. All other format codes may be used stand-alone.
  405. When used in this fashion they will consume one argument of the indicated
  406. type from the function's argument list.
  407. .Pp
  408. The array valued format codes
  409. .Cm ( A , B , C , D , F , G , L , O , U , d ,
  410. and
  411. .Cm r )
  412. and the timestamp format code
  413. .Cm ( t )
  414. can be followed by a
  415. .Dq row format .
  416. They will use a default row format (detailed below) if one is not
  417. given explicitly.
  418. .Pp
  419. The row format is bracketed by the character sequences
  420. .Cm %{
  421. and
  422. .Cm %}
  423. and, for array values only, may be optionally divided into two by the
  424. character sequence
  425. .Cm %| .
  426. For array values, it contains one or two strings containing any number
  427. of a context sensitive subset of format conversions from those
  428. described here.
  429. For timestamp values it contains any number of format conversion
  430. specifiers with meanings as described in
  431. .Xr strftime 3 .
  432. .Pp
  433. The first or only format string is repeatedly processed for each of the
  434. array items in turn.
  435. The optional second format string is processed as a separator between
  436. each of the array items.
  437. If no row format is given, output will be generated according to a
  438. default format, detailed below.
  439. .Pp
  440. Within a
  441. .Dq row format
  442. string, you may use any of the single-character non-array valued
  443. format codes except for
  444. .Cm %S ,
  445. but only the two-character format codes which correspond
  446. to the parent item and have the same first character.
  447. Array valued format codes may not be used within row formats,
  448. nor may you embed one
  449. .Dq row format
  450. within another.
  451. Only one argument, a
  452. .Vt struct pkg *
  453. pointer is consumed from the argument list.
  454. Thus this is a legal
  455. .Fa format
  456. string:
  457. .Bd -literal -offset indent
  458. "%B%{%n-%v:%Bn%|\en%}"
  459. .Ed
  460. .Pp
  461. which serves to print out a list of the shared libraries required by
  462. the programs within the package, each prefixed by the package name and
  463. version.
  464. .Pp
  465. The conversion specifiers and their meanings are:
  466. .Bl -tag -width ".Cm %Bn"
  467. .It Cm \^%A
  468. Annotations [array]
  469. .Vt struct pkg *
  470. .Pp
  471. Default row format
  472. .Cm "%A%{%An: %Av\en%|%}"
  473. .It Cm \^%An
  474. Annotation tag name [string]
  475. .Vt struct pkg_note *
  476. .It Cm \^%Av
  477. Annotation value [string]
  478. .Vt struct pkg_note *
  479. .It Cm \^%B
  480. Required shared libraries [array]
  481. .Vt struct pkg *
  482. .Pp
  483. Default row format:
  484. .Cm "%B%{%Bn\en%|%}"
  485. .It Cm %Bn
  486. Required shared library name [string]
  487. .Vt struct pkg_shlib *
  488. .It Cm \&%C
  489. Categories [array]
  490. .Vt struct pkg *
  491. .Pp
  492. Default row format:
  493. .Cm "%C%{%Cn%|, %}"
  494. .It Cm %Cn
  495. Category name [string]
  496. .Vt struct pkg_category *
  497. .It Cm \^%D
  498. Directories [array]
  499. .Vt struct pkg *
  500. .Pp
  501. Default row format:
  502. .Cm "%D%{%Dn\en%|%}"
  503. .It Cm %Dg
  504. Directory ownership: group name [string]
  505. .Vt struct pkg_dir *
  506. .It Cm %Dn
  507. Directory path name [string]
  508. .Vt struct pkg_dir *
  509. .It Cm %Dp
  510. Directory permissions [mode]
  511. .Vt struct pkg_dir *
  512. .It Cm %Du
  513. Directory ownership: user name [string]
  514. .Vt struct pkg_dir *
  515. .It Cm %F
  516. Files [array]
  517. .Vt struct pkg *
  518. .Pp
  519. Default row format:
  520. .Cm "%F%{%Fn\en%|%}"
  521. .It Cm %Fg
  522. File ownership: group name [string]
  523. .Vt struct pkg_file *
  524. .It Cm %\^Fn
  525. File path name [string]
  526. .Vt struct pkg_file *
  527. .It Cm %Fp
  528. File permissions [mode]
  529. .Vt struct pkg_file *
  530. .It Cm %Fs
  531. File SHA256 checksum [string]
  532. .Vt struct pkg_file *
  533. .It Cm %Fu
  534. File ownership: user name [string]
  535. .Vt struct pkg_file *
  536. .It Cm %G
  537. Groups [array]
  538. .Vt struct pkg *
  539. .Pp
  540. Default row format:
  541. .Cm "%G%{%Gn\en%|%}"
  542. .It Cm %Gg
  543. Group GID-string [string]
  544. .Vt struct pkg_group *
  545. .Pp
  546. The GID-string consists of a colon-separated list containing the
  547. group name,
  548. .Sq *
  549. as a place holder instead of any hashed password for the group,
  550. the group identifier number and a possibly empty comma separated list
  551. of the group members,
  552. equivalent to one line from
  553. .Fa /etc/group
  554. as described in
  555. .Xr group 5 .
  556. .It Cm %Gn
  557. Group name [string]
  558. .Vt struct pkg_group *
  559. .It Cm \^%I
  560. Row counter [integer].
  561. .Pp
  562. This format code may only be used as part of a
  563. .Dq row format.
  564. .It Cm %L
  565. Licenses [array]
  566. .Vt struct pkg *
  567. .Pp
  568. Default row format:
  569. .Cm "%L%{%Ln%| %l %}"
  570. .It Cm %Ln
  571. Licence name [string]
  572. .Vt struct pkg_license *
  573. .It Cm %M
  574. Package message [string]
  575. .Vt struct pkg *
  576. .It Cm \&%N
  577. Repository identity [string]
  578. .Vt struct pkg *
  579. .It Cm \^%O
  580. Options [array]
  581. .Vt struct pkg *
  582. .Pp
  583. Default row format:
  584. .Cm "%O%{%On %Ov\en%|%}"
  585. .It Cm %On
  586. Option name [string]
  587. .Vt struct pkg_option *
  588. .It Cm %Ov
  589. Option value [string]
  590. .Vt struct pkg_option *
  591. .It Cm %Od
  592. Option default value [string] (if known: will produce an empty string
  593. if not.)
  594. .Vt struct pkg_option *
  595. .It Cm %OD
  596. Option description [string] (if known: will produce an empty string
  597. if not.)
  598. .Vt struct pkg_option *
  599. .It Cm \^%R
  600. Repository path - the path relative to the repository root that
  601. package may be downloaded from [string].
  602. .Vt struct pkg *
  603. .It Cm \^%S
  604. Arbitrary character string [string]
  605. .Vt const char *
  606. .Pp
  607. .It Cm \^%U
  608. Users [array]
  609. .Vt struct pkg *
  610. .Pp
  611. Default row format:
  612. .Cm "%U%{%Un\en%|%}"
  613. .It Cm %Un
  614. User name [string]
  615. .Vt struct pkg_user *
  616. .It Cm %Uu
  617. User UID-str [string]
  618. .Vt struct pkg_user *
  619. .Pp
  620. The UID-string consists of a colon-separated list containing the
  621. user name,
  622. .Sq *
  623. as a place holder instead of any hashed password for the user, the
  624. user identifier number, the user's login group id, an empty field for
  625. the user login class, zero for the password change time, zero for the
  626. account expiry time,
  627. .Sq gecos
  628. string (general information about the user), the user's home directory
  629. and the user's login shell; equivalent to one line from
  630. .Fa /etc/master.passwd
  631. as described in
  632. .Xr passwd 5 .
  633. .It Cm \^%V
  634. Old version [string].
  635. Valid only during operations when one version of a package is being
  636. replaced by another.
  637. .Vt struct pkg *
  638. .It Cm %a
  639. Autoremove flag [boolean]
  640. .Vt struct pkg *
  641. .It Cm \^%b
  642. Provided shared libraries [array]
  643. .Vt struct pkg *
  644. .Pp
  645. Default row format:
  646. .Cm "%b%{%bn\en%|%}"
  647. .It Cm %bn
  648. Provided shared library name [string]
  649. .Vt struct pkg_shlib *
  650. .It Cm %c
  651. Comment [string]
  652. .Vt struct pkg *
  653. .It Cm %d
  654. Dependencies [array]
  655. .Vt struct pkg *
  656. .Pp
  657. Default row format:
  658. .Cm "%d%{%dn-%dv\en%|%}"
  659. .It Cm %dk
  660. Dependency lock status [boolean]
  661. .Vt struct pkg_dep *
  662. .It Cm %dn
  663. Dependency name [string]
  664. .Vt struct pkg_dep *
  665. .It Cm %do
  666. Dependency origin [string]
  667. .Vt struct pkg_dep *
  668. .It Cm %dv
  669. Dependency version [string]
  670. .Vt struct pkg_dep *
  671. .It Cm %e
  672. Description [string]
  673. .Vt struct pkg *
  674. .It Cm %i
  675. Additional information [string]
  676. .Vt struct pkg *
  677. .It Cm %k
  678. Locking status [boolean]
  679. .Vt struct pkg *
  680. .It Cm %l
  681. License logic [licence-logic]
  682. .Vt struct pkg *
  683. .It Cm %m
  684. Maintainer [string]
  685. .Vt struct pkg *
  686. .It Cm %n
  687. Package name [string]
  688. .Vt struct pkg *
  689. .It Cm %o
  690. Origin [string]
  691. .Vt struct pkg *
  692. .It Cm %p
  693. Prefix [string]
  694. .Vt struct pkg *
  695. .It Cm %r
  696. Requirements [array]
  697. .Vt struct pkg *
  698. .Pp
  699. Default row format:
  700. .Cm "%r%{%rn-%rv\en%|%}"
  701. .It Cm %rk
  702. Requirement lock status [boolean]
  703. .Vt struct pkg_dep *
  704. .It Cm %rn
  705. Requirement name [string]
  706. .Vt struct pkg_dep *
  707. .It Cm %ro
  708. Requirement origin [string]
  709. .Vt struct pkg_dep *
  710. .It Cm %rv
  711. Requirement version [string]
  712. .Vt struct pkg_dep *
  713. .It Cm %s
  714. Package flat size [integer]
  715. .Vt struct pkg *
  716. .It Cm %t
  717. Installation timestamp [date-time]
  718. .Vt struct pkg *
  719. .It Cm %u
  720. Package checksum [string]
  721. .Vt struct pkg *
  722. .It Cm %v
  723. Package version [string]
  724. .Vt struct pkg *
  725. .It Cm %w
  726. Home page URL [string]
  727. .Vt struct pkg *
  728. .It Cm %%
  729. A
  730. .Ql %
  731. is written.
  732. No argument is converted.
  733. The complete conversion specification
  734. is
  735. .Ql %% .
  736. .El
  737. .Pp
  738. The decimal point
  739. character is defined in the program's locale (category
  740. .Dv LC_NUMERIC ) .
  741. .Pp
  742. In no case does a non-existent or small field width cause truncation of
  743. a numeric field;
  744. if the result of a conversion is wider than the field width, the field
  745. is expanded to contain the conversion result.
  746. .Ss ARRAY VALUES
  747. Effective format modifiers:
  748. .Bl -tag -width ".So \ Sc" -offset indent
  749. .It Cm \&?
  750. First Alternate Form: 0 if the array is empty, 1 if it has any number
  751. of elements within it
  752. .It Cm #
  753. Second Alternate Form: The number of elements in the array
  754. .El
  755. .Ss STRING VALUES
  756. Effective format modifiers:
  757. .Bl -tag -width ".So \ Sc" -offset indent
  758. .It Cm \-
  759. Left align
  760. .El
  761. .Ss INTEGER VALUES
  762. Effective format modifiers:
  763. .Bl -tag -width ".So \ Sc" -offset indent
  764. .It Cm \-
  765. Left align
  766. .It Cm \&?
  767. First Alternate Form: humanized number (decimal)
  768. .It Cm #
  769. Second Alternate Form: humanized number (binary)
  770. .It Cm 0
  771. Zero pad
  772. .It So "\ " Sc
  773. Blank for plus
  774. .It Cm +
  775. Explicit + or \- sign
  776. .It Sq Cm '
  777. Thousands separator
  778. .El
  779. .Ss BOOLEAN VALUES
  780. The two possible values
  781. .Sq true
  782. or
  783. .Sq false
  784. may be output in one of three different styles: plain; or alternate
  785. forms 1 and 2 specified using format modifiers.
  786. .Bl -column "FALSE" "Plain (%a)" "Alt 1 (%?a)" "Alt 2 (%#a)" -offset indent
  787. .It Sy "Value" Ta Sy "Plain (%a)" Ta Sy "Alt 1 (%?a)" Ta Sy "Alt 2 (%#a)"
  788. .It Li FALSE Ta No false Ta no Ta \^
  789. .It Li TRUE Ta No true Ta yes Ta (*)
  790. .El
  791. The second alternate form produces no output for
  792. .Cm false .
  793. .Pp
  794. Effective format modifiers:
  795. .Bl -tag -width ".Cm #" -offset indent
  796. .It Cm \&?
  797. First Alternate Form
  798. .It Cm #
  799. Second Alternate Form
  800. .It Cm \-
  801. Left align
  802. .El
  803. .Ss FILE MODE VALUES
  804. The file mode is a bitmap representing setid, user, group and other
  805. permissions.
  806. The plain format prints it as an octal value, for example:
  807. .Bd -literal -offset indent
  808. 4755
  809. .Ed
  810. .Pp
  811. The first alternate form is similar but adds a leading zero:
  812. .Bd -literal -offset indent
  813. 04755
  814. .Ed
  815. .Pp
  816. Whilst the second alternate form produces a string in the style of
  817. .Xr strmode 3 :
  818. .Bd -literal -offset indent
  819. -rwsr-xr-x
  820. .Ed
  821. .Pp
  822. Note: there is always a space at the end of the
  823. .Xr strmode 3
  824. output.
  825. .Pp
  826. Effective format modifiers (all forms):
  827. .Bl -tag -width ".Cm \-" -offset indent
  828. .It Cm \-
  829. Left align
  830. .El
  831. .Pp
  832. Additionally, when the value is printed as an integer (i.e., plain
  833. or alternate form 1), these additional modifiers take effect:
  834. .Bl -tag -width ".So \ Sc" -offset indent
  835. .It Cm \&?
  836. First Alternate Form: add leading zero to octal integer
  837. .It Cm 0
  838. Zero pad
  839. .El
  840. .Ss LICENSE LOGIC VALUES
  841. License-logic is a three-valued type: one of
  842. .Sq SINGLE ,
  843. .Sq OR
  844. or
  845. .Sq AND ,
  846. which shows whether the package is distributed under the terms of a
  847. single license, or when there are several applicable licenses, whether
  848. these should be treated as alternatives or applied in aggregate.
  849. There are three different output styles: plain; or alternate forms 1
  850. and 2 specified using format modifiers.
  851. .Bl -column "SINGLE" "Plain (%l)" "Alt 1 (%?l)" "Alt 2 (%#l)" -offset indent
  852. .It Sy "Logic" Ta Sy "Plain (%l)" Ta Sy "Alt 1 (%?l)" Ta Sy "Alt 2 (%#l)"
  853. .It Li SINGLE Ta No single Ta \^ Ta ==
  854. .It Li OR Ta No or Ta | Ta ||
  855. .It Li AND Ta No and Ta & Ta &&
  856. .El
  857. .Pp
  858. Effective format modifiers:
  859. .Bl -tag -width ".Cm #" -offset indent
  860. .It Cm \&?
  861. First Alternate Form
  862. .It Cm #
  863. Second Alternate Form
  864. .It Cm \-
  865. Left align
  866. .El
  867. .Ss DATE-TIME VALUES
  868. When used outside of a
  869. .Dq row format
  870. string may be followed by an optional
  871. .Xr strftime 3
  872. format, enclosed in
  873. .Cm %{
  874. and
  875. .Cm %} ,
  876. which will be used to format the timestamp.
  877. Otherwise the timestamp is printed as an integer value of the
  878. number of seconds since the Epoch (00:00:00 UTC, 1 January 1970; see
  879. .Xr time 3).
  880. .Pp
  881. Effective format modifiers:
  882. .Bl -tag -width ".Cm \-" -offset indent
  883. .It Cm \-
  884. Left align
  885. .El
  886. .Pp
  887. Additionally, when the value is printed as an integer (i.e., without
  888. .Xr strftime 3
  889. format codes enclosed in
  890. .Cm %{
  891. and
  892. .Cm %} ,
  893. the following format modifiers are also effective:
  894. .Bl -tag -width ".So \ Sc" -offset indent
  895. .It Cm \&?
  896. First Alternate Form: humanized number (decimal)
  897. .It Cm #
  898. Second Alternate Form: humanized number (binary)
  899. .It Cm 0
  900. Zero pad
  901. .It So "\ " Sc
  902. Blank for plus
  903. .It Cm +
  904. Explicit + or \- sign
  905. .It Sq Cm '
  906. Thousands separator
  907. .El
  908. .Sh EXAMPLES
  909. To print the package installation timestamp in the form
  910. .Dq Li "Sunday, July 3, 10:02" ,
  911. .Bd -literal -offset indent
  912. #include <pkg.h>
  913. pkg_fprintf(stdout, "%t%{%A, %B %e, %R%}\en", pkg);
  914. .Ed
  915. .Pp
  916. To print the package name and version, followed by the name and
  917. version of all of the packages it depends upon, one per line, each
  918. indented by one tab stop:
  919. .Bd -literal -offset indent
  920. #include <pkg.h>
  921. pkg_printf("%n-%v\en%d%{\et%dn-%dv%|%\en%}\en", pkg, pkg, pkg);
  922. .Ed
  923. .Pp
  924. Note that the item separator part of the row format is only printed
  925. between individual row items.
  926. Thus to fill the character array
  927. .Fa buf
  928. with a one-line string listing all of the licenses for the package
  929. separated by
  930. .Dq and
  931. or
  932. .Dq or
  933. as appropriate:
  934. .Bd -literal -offset indent
  935. #include <pkg.h>
  936. char buf[256];
  937. pkg_snprintf(buf, sizeof(buf), "%L%{%Ln%| %l %}", pkg);
  938. .Ed
  939. .Sh ERRORS
  940. In addition to the errors documented for the
  941. .Xr write 2
  942. system call, the
  943. .Fn pkg_printf
  944. family of functions may fail if:
  945. .Bl -tag -width Er
  946. .It Bq Er EILSEQ
  947. An invalid wide character code was encountered.
  948. .It Bq Er ENOMEM
  949. Insufficient storage space is available.
  950. .El
  951. .Sh SEE ALSO
  952. .Xr printf 1 ,
  953. .Xr printf 3 ,
  954. .Xr strftime 3 ,
  955. .Xr setlocale 3
  956. .Xr pkg_repos 3 ,
  957. .Xr pkg-repository 5 ,
  958. .Xr pkg.conf 5 ,
  959. .Xr pkg 8 ,
  960. .Xr pkg-add 8 ,
  961. .Xr pkg-annotate 8 ,
  962. .Xr pkg-audit 8 ,
  963. .Xr pkg-autoremove 8 ,
  964. .Xr pkg-backup 8 ,
  965. .Xr pkg-check 8 ,
  966. .Xr pkg-clean 8 ,
  967. .Xr pkg-config 8 ,
  968. .Xr pkg-convert 8 ,
  969. .Xr pkg-create 8 ,
  970. .Xr pkg-delete 8 ,
  971. .Xr pkg-fetch 8 ,
  972. .Xr pkg-info 8 ,
  973. .Xr pkg-install 8 ,
  974. .Xr pkg-lock 8 ,
  975. .Xr pkg-query 8 ,
  976. .Xr pkg-register 8 ,
  977. .Xr pkg-repo 8 ,
  978. .Xr pkg-rquery 8 ,
  979. .Xr pkg-search 8 ,
  980. .Xr pkg-set 8 ,
  981. .Xr pkg-shell 8 ,
  982. .Xr pkg-shlib 8 ,
  983. .Xr pkg-ssh 8 ,
  984. .Xr pkg-stats 8 ,
  985. .Xr pkg-update 8 ,
  986. .Xr pkg-updating 8 ,
  987. .Xr pkg-upgrade 8 ,
  988. .Xr pkg-version 8 ,
  989. .Xr pkg-which 8
  990. .Sh BUGS
  991. The
  992. .Nm pkg_printf
  993. family of functions do not correctly handle multibyte characters in the
  994. .Fa format
  995. argument.
  996. .Pp
  997. There is no way to sort the output of array valued items.
  998. .Sh SECURITY CONSIDERATIONS
  999. Equivalents to the
  1000. .Fn sprintf
  1001. and
  1002. .Fn vsprintf
  1003. functions are not supplied.
  1004. Instead, use
  1005. .Fn pkg_snprintf
  1006. to write into a fixed length buffer without danger of overflow.
  1007. .Pp
  1008. The
  1009. .Fn pkg_printf
  1010. family, like the
  1011. .Fn printf
  1012. family of functions it is modelled on, is also easily misused in a manner
  1013. allowing malicious users to arbitrarily change a running program's
  1014. functionality by either causing the program
  1015. to print potentially sensitive data
  1016. .Dq "left on the stack" ,
  1017. or causing it to generate a memory fault or bus error
  1018. by dereferencing an invalid pointer.
  1019. .Pp
  1020. Programmers are therefore strongly advised to never pass untrusted strings
  1021. as the
  1022. .Fa format
  1023. argument, as an attacker can put format specifiers in the string
  1024. to mangle your stack,
  1025. leading to a possible security hole.
  1026. This holds true even if the string was built using a function like
  1027. .Fn snprintf ,
  1028. as the resulting string may still contain user-supplied conversion specifiers
  1029. for later interpolation by
  1030. .Fn pkg_printf .
  1031. .Pp
  1032. Always use the proper secure idiom:
  1033. .Pp
  1034. .Dl "pkg_snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"