pkg_printf.3

.\" Copyright (c) 1990, 1991, 1993
.\"     The Regents of the University of California.  All rights reserved.
.\" Copyright (c) 2013-2015 Matthew Seaman <matthew@FreeBSD.org>
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Chris Torek and the American National Standards Committee X3,
.\" on Information Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd August 15, 2015
.Dt PKG_PRINTF 3
.Os
.Sh NAME
.Nm pkg_printf , pkg_fprintf , pkg_dprintf , pkg_snprintf , pkg_asprintf ,
.Nm pkg_utstring_printf ,
.Nm pkg_vprintf , pkg_vfprintf , pkg_vdprintf , pkg_vsnprintf , pkg_vasprintf ,
.Nm pkg_utstring_vprintf
.Nd formatted output of package data
.Sh LIBRARY
.Lb libpkg
.Sh SYNOPSIS
.In pkg.h
.Ft int
.Fn pkg_printf "const char * restrict format" ...
.Ft int
.Fn pkg_fprintf "FILE * restrict stream" "const char * restrict format" ...
.Ft int
.Fn pkg_dprintf "int fd" "const char * restrict format" ...
.Ft int
.Fn pkg_snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
.Ft int
.Fn pkg_asprintf "char **ret" "const char * restrict format" ...
.Ft struct utstring *
.Fn pkg_utstring_printf "struct utstring * restrict utstring" "const char * restrict format" ...
.In stdarg.h
.Ft int
.Fn pkg_vprintf "const char * restrict format" "va_list ap"
.Ft int
.Fn pkg_vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
.Ft int
.Fn pkg_vdprintf "int fd" "const char * restrict format" "va_list ap"
.Ft int
.Fn pkg_vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
.Ft int
.Fn pkg_vasprintf "char **ret" "const char * restrict format" "va_list ap"
.Ft struct utstring *
.Fn pkg_utstring_vprintf "struct utstring * restrict utstring" "const char * restrict format" "va_list ap"
.Sh DESCRIPTION
The
.Fn pkg_printf
family of functions produces output of package data according to a
.Fa format
as described below, analogously to the similarly named
.Xr printf 3
family of functions.
The
.Fn pkg_printf
and
.Fn pkg_vprintf
functions
write output to
.Dv stdout ,
the standard output stream;
.Fn pkg_fprintf
and
.Fn pkg_vfprintf
write output to the given output
.Fa stream ;
.Fn pkg_dprintf
and
.Fn pkg_vdprintf
write output to the given file descriptor;
.Fn pkg_snprintf
and
.Fn pkg_vsnprintf
write to the character string
.Fa str ;
.Fn pkg_asprintf
and
.Fn pkg_vasprintf
dynamically allocate a new string with
.Xr malloc 3
to write to;
.Fn pkg_utstring_printf
and
.Fn pkg_utstring_vprintf
write to the given utstring structure.
.Pp
These functions write the output under the control of a
.Fa format
string that specifies how subsequent arguments
(or arguments accessed via the variable-length argument facilities of
.Xr stdarg 3 )
are converted for output.
.Pp
These functions return the number of characters printed
(not including the trailing
.Ql \e0
used to end output to strings) or a negative value if an output error occurs,
except for
.Fn pkg_snprintf
or
.Fn pkg_vsnprintf
which return the number of characters that would have been printed if the
.Fa size
were unlimited
(again, not including the final
.Ql \e0 )
and the two functions
.Fn pkg_utstring_printf
and
.Fn pkg_utstring_vprintf
which return the given utstring pointer, or
.Dv NULL
in the case of errors.
.Pp
The
.Fn pkg_asprintf
and
.Fn pkg_vasprintf
functions set
.Fa *ret
to be a pointer to a buffer sufficiently large to hold the formatted string.
This pointer should be passed to
.Xr free 3
to release the allocated storage when it is no longer needed.
If sufficient space cannot be allocated,
.Fn pkg_asprintf
and
.Fn pkg_vasprintf
will return \-1 and set
.Fa ret
to be a
.Dv NULL
pointer.
.Pp
The
.Fn pkg_snprintf
and
.Fn pkg_vsnprintf
functions will write at most
.Fa size Ns \-1
of the characters printed into the output string
(the
.Fa size Ns 'th
character then gets the terminating
.Ql \e0 ) ;
if the return value is greater than or equal to the
.Fa size
argument, the string was too short
and some of the printed characters were discarded.
The output is always null-terminated.
.Pp
The format string is composed of zero or more directives:
ordinary
.\" multibyte
characters (not
.Cm % ) ,
which are copied unchanged to the output stream;
and conversion specifications, each of which results
in fetching zero or more subsequent arguments.
Each conversion specification is introduced by
the
.Cm %
character.
The arguments must correspond properly with the conversion specifier.
After the
.Cm % ,
the following appear in sequence:
.Bl -bullet
.It
Zero or more of the following flags:
.Bl -tag -width ".So \  Sc (space)"
.It Cm \&?
The value should be converted to the
.Dq first alternate form .
.Pp
For integer valued conversions
.Cm ( I , s , t
and
.Cm x )
this is a
.Vt humanized
form as a floating point value scaled to the range 0 \- 1000
followed by the SI powers-of-10 scale factor.
See
.Sx SCALE FACTORS .
.Pp
For array valued conversions
.Cm ( A, B , C , D , F , G , L , O , U , d ,
and
.Cm r )
generate
.Dq 0
if there are no items in the array,
.Dq 1
otherwise.
.Pp
For formats returning file modes
.Cm ( Dp
or
.Cm Fp )
print the mode in the style of
.Xr strmode 3 .
.Pp
For boolean valued formats
.Cm ( dk , rk , a
and
.Cm k )
generate either
.Dq yes
or
.Dq no
for
.Sq true
and
.Sq false
respectively.
.Pp
For the licence logic format
.Cm (l)
generate
.Dq \^
(empty),
.Dq &
or
.Dq |
for types
.Sq SINGLE ,
.Sq AND
and
.Sq OR
respectively.
.It Cm #
The value should be converted to the
.Dq second alternate form .
.Pp
For the integer valued conversions
.Cm ( I , s , t , x )
this is a
.Dq humanized
form as a floating point value scaled to the range 0 \- 1024
followed by the IEE/IEC and SI powers-of-2 scale factor.
See
.Sx SCALE FACTORS .
.Pp
For array valued conversions
.Cm ( A, B , C , D , F , G , L , O , U , d ,
and
.Cm r )
generate the number of items in the array.
.Pp
For formats returning file modes
.Cm ( Dp
or
.Cm Fp )
print the mode as an octal integer with a leading 0.
.Pp
For boolean valued formats
.Cm ( dk , rk , a
and
.Cm k )
generate either
.Dq (*)
or
.Dq \^
(empty) for
.Sq true
and
.Sq false
respectively.
.Pp
For the licence logic format
.Cm (l)
generate
.Dq == ,
.Dq &&
or
.Dq ||
for types
.Sq SINGLE ,
.Sq AND
and
.Sq OR
respectively.
.It Cm 0 (zero)
Zero padding.
For all integer valued conversions and humanized numbers the converted
value is padded on the left with zeros rather than blanks.
For string valued conversions, this has no effect and the converted
value is padded on the left with blanks.
.It Cm \-
A negative field width flag;
the converted value is to be left adjusted on the field boundary.
The converted value is padded on the right with blanks,
rather than on the left with blanks or zeros.
Applies to all scalar-valued conversions.
.Dq Cm \-
overrides a
.Dq Cm 0
if both are given.
.It So "\ " Sc (space)
A blank should be left before a positive number
produced by a signed conversion
.Cm ( I , s , t ,
or
.Cm x ) .
.It Cm +
A sign must always be placed before an integer or humanized
number produced by a numerical conversion.
A
.Dq Cm +
overrides a space if both are used.
.It Sq Cm '
Numerical (integer) conversions should be grouped and separated by
thousands using the non-monetary separator returned by
.Xr localeconv 3 .
Has no visible effect in the default
.Dq C
locale.
.El
.It
An optional decimal digit string specifying a minimum field width.
If the converted value has fewer characters than the field width,
it will be padded with spaces (or zeroes, if the zero-padding flag has
been given and the conversion supports it) on the left (or spaces on
the right, if the left-adjustment flag has been given) to fill out the
field width.
.It
One or two characters that specify the type of conversion to be applied.
.It
An optional
.Dq row format
for array valued conversions
.Cm ( A, B , C , D , F , G , L , O , U , d ,
and
.Cm r )
or the timestamp value conversion
.Cm ( t ) .
Which conversion characters are permissible in the row format is
context dependent.
See the
.Sx FORMAT CODES
section for details.
.El
.Ss SCALE FACTORS
Humanized number conversions scale the number to lie within
the range 1 \- 1000 (power of ten conversions using the
.Cm \&?
format modifier) or 1 \- 1024 (power of two conversions using the
.Cm #
format modifier) and append a scale factor as follows:
.Pp
The SI power of ten suffixes are
.Bl -column "Suffix" "Description" "1,000,000,000,000,000,000" -offset indent
.It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier"
.It Li \^ Ta No (none) Ta 1
.It Li k Ta No kilo   Ta 1,000
.It Li M Ta No mega   Ta 1,000,000
.It Li G Ta No giga   Ta 1,000,000,000
.It Li T Ta No tera   Ta 1,000,000,000,000
.It Li P Ta No peta   Ta 1,000,000,000,000,000
.It Li E Ta No exa    Ta 1,000,000,000,000,000,000
.El
.Pp
The IEE/IEC (and now also SI) power of two suffixes are:
.Bl -column "Suffix" "Description" "1,000,000,000,000,000,000" -offset indent
.It Sy "Suffix" Ta Sy "Description" Ta Sy "Multiplier"
.It Li \^ Ta No (none) Ta 1
.It Li Ki Ta No kibi   Ta 1,024
.It Li Mi Ta No mebi   Ta 1,048,576
.It Li Gi Ta No gibi   Ta 1,073,741,824
.It Li Ti Ta No tebi   Ta 1,099,511,627,776
.It Li Pi Ta No pebi   Ta 1,125,899,906,842,624
.It Li Ei Ta No exbi   Ta 1,152,921,504,606,846,976
.El
.Ss FORMAT CODES
Format codes will format the output classified as the type shown in
square brackets.
.Cm %\^I
is unique in that it can only be used inside a
.Dq row format.
All other format codes may be used stand-alone.
When used in this fashion they will consume one argument of the indicated
type from the function's argument list.
.Pp
The array valued format codes
.Cm ( A , B , C , D , F , G , L , O , U , d ,
and
.Cm r )
and the timestamp format code
.Cm ( t )
can be followed by a
.Dq row format .
They will use a default row format (detailed below) if one is not
given explicitly.
.Pp
The row format is bracketed by the character sequences
.Cm %{
and
.Cm %}
and, for array values only, may be optionally divided into two by the
character sequence
.Cm %| .
For array values, it contains one or two strings containing any number
of a context sensitive subset of format conversions from those
described here.
For timestamp values it contains any number of format conversion
specifiers with meanings as described in
.Xr strftime 3 .
.Pp
The first or only format string is repeatedly processed for each of the
array items in turn.
The optional second format string is processed as a separator between
each of the array items.
If no row format is given, output will be generated according to a
default format, detailed below.
.Pp
Within a
.Dq row format
string, you may use any of the single-character non-array valued
format codes except for
.Cm %S ,
but only the two-character format codes which correspond
to the parent item and have the same first character.
Array valued format codes may not be used within row formats,
nor may you embed one
.Dq row format
within another.
Only one argument, a
.Vt struct pkg *
pointer is consumed from the argument list.
Thus this is a legal
.Fa format
string:
.Bd -literal -offset indent
"%B%{%n-%v:%Bn%|\en%}"
.Ed
.Pp
which serves to print out a list of the shared libraries required by
the programs within the package, each prefixed by the package name and
version.
.Pp
The conversion specifiers and their meanings are:
.Bl -tag -width ".Cm %Bn"
.It Cm \^%A
Annotations [array]
.Vt struct pkg *
.Pp
Default row format
.Cm "%A%{%An: %Av\en%|%}"
.It Cm \^%An
Annotation tag name [string]
.Vt struct pkg_note *
.It Cm \^%Av
Annotation value [string]
.Vt struct pkg_note *
.It Cm \^%B
Required shared libraries [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%B%{%Bn\en%|%}"
.It Cm %Bn
Required shared library name [string]
.Vt struct pkg_shlib *
.It Cm \&%C
Categories [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%C%{%Cn%|, %}"
.It Cm %Cn
Category name [string]
.Vt struct pkg_category *
.It Cm \^%D
Directories [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%D%{%Dn\en%|%}"
.It Cm %Dg
Directory ownership: group name [string]
.Vt struct pkg_dir *
.It Cm %Dn
Directory path name [string]
.Vt struct pkg_dir *
.It Cm %Dp
Directory permissions [mode]
.Vt struct pkg_dir *
.It Cm %Du
Directory ownership: user name [string]
.Vt struct pkg_dir *
.It Cm %F
Files [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%F%{%Fn\en%|%}"
.It Cm %Fg
File ownership: group name [string]
.Vt struct pkg_file *
.It Cm %\^Fn
File path name [string]
.Vt struct pkg_file *
.It Cm %Fp
File permissions [mode]
.Vt struct pkg_file *
.It Cm %Fs
File SHA256 checksum [string]
.Vt struct pkg_file *
.It Cm %Fu
File ownership: user name [string]
.Vt struct pkg_file *
.It Cm %G
Groups [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%G%{%Gn\en%|%}"
.It Cm %Gn
Group name [string]
.Vt struct pkg_group *
.It Cm \^%I
Row counter [integer].
.Pp
This format code may only be used as part of a
.Dq row format.
.It Cm %L
Licenses [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%L%{%Ln%| %l %}"
.It Cm %Ln
Licence name [string]
.Vt struct pkg_license *
.It Cm %M
Package message [string]
.Vt struct pkg *
.It Cm \&%N
Repository identity [string]
.Vt struct pkg *
.It Cm \^%O
Options [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%O%{%On %Ov\en%|%}"
.It Cm %On
Option name [string]
.Vt struct pkg_option *
.It Cm %Ov
Option value [string]
.Vt struct pkg_option *
.It Cm %Od
Option default value [string] (if known: will produce an empty string
if not.)
.Vt struct pkg_option *
.It Cm %OD
Option description [string] (if known: will produce an empty string
if not.)
.Vt struct pkg_option *
.It Cm \^%R
Repository path - the path relative to the repository root that
package may be downloaded from [string].
.Vt struct pkg *
.It Cm \^%S
Arbitrary character string [string]
.Vt const char *
.Pp
.It Cm \^%U
Users [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%U%{%Un\en%|%}"
.It Cm %Un
User name [string]
.Vt struct pkg_user *
.It Cm \^%V
Old version [string].
Valid only during operations when one version of a package is being
replaced by another.
.Vt struct pkg *
.It Cm %a
Autoremove flag [boolean]
.Vt struct pkg *
.It Cm \^%b
Provided shared libraries [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%b%{%bn\en%|%}"
.It Cm %bn
Provided shared library name [string]
.Vt struct pkg_shlib *
.It Cm %c
Comment [string]
.Vt struct pkg *
.It Cm %d
Dependencies [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%d%{%dn-%dv\en%|%}"
.It Cm %dk
Dependency lock status [boolean]
.Vt struct pkg_dep *
.It Cm %dn
Dependency name [string]
.Vt struct pkg_dep *
.It Cm %do
Dependency origin [string]
.Vt struct pkg_dep *
.It Cm %dv
Dependency version [string]
.Vt struct pkg_dep *
.It Cm %e
Description [string]
.Vt struct pkg *
.It Cm %i
Additional information [string]
.Vt struct pkg *
.It Cm %k
Locking status [boolean]
.Vt struct pkg *
.It Cm %l
License logic [licence-logic]
.Vt struct pkg *
.It Cm %m
Maintainer [string]
.Vt struct pkg *
.It Cm %n
Package name [string]
.Vt struct pkg *
.It Cm %o
Origin [string]
.Vt struct pkg *
.It Cm %p
Prefix [string]
.Vt struct pkg *
.It Cm %r
Requirements [array]
.Vt struct pkg *
.Pp
Default row format:
.Cm "%r%{%rn-%rv\en%|%}"
.It Cm %rk
Requirement lock status [boolean]
.Vt struct pkg_dep *
.It Cm %rn
Requirement name [string]
.Vt struct pkg_dep *
.It Cm %ro
Requirement origin [string]
.Vt struct pkg_dep *
.It Cm %rv
Requirement version [string]
.Vt struct pkg_dep *
.It Cm %s
Package flat size [integer]
.Vt struct pkg *
.It Cm %t
Installation timestamp [date-time]
.Vt struct pkg *
.It Cm %u
Package checksum [string]
.Vt struct pkg *
.It Cm %v
Package version [string]
.Vt struct pkg *
.It Cm %w
Home page URL [string]
.Vt struct pkg *
.It Cm %x
Package tarball size [integer]
.Vt struct pkg *
.It Cm %z
Package short checksum [string]
.Vt struct pkg *
.It Cm %%
A
.Ql %
is written.
No argument is converted.
The complete conversion specification
is
.Ql %% .
.El
.Pp
The decimal point
character is defined in the program's locale (category
.Dv LC_NUMERIC ) .
.Pp
In no case does a non-existent or small field width cause truncation of
a numeric field;
if the result of a conversion is wider than the field width, the field
is expanded to contain the conversion result.
.Ss ARRAY VALUES
Effective format modifiers:
.Bl -tag -width ".So \  Sc" -offset indent
.It Cm \&?
First Alternate Form: 0 if the array is empty, 1 if it has any number
of elements within it
.It Cm #
Second Alternate Form: The number of elements in the array
.El
.Ss STRING VALUES
Effective format modifiers:
.Bl -tag -width ".So \  Sc" -offset indent
.It Cm \-
Left align
.El
.Ss INTEGER VALUES
Effective format modifiers:
.Bl -tag -width ".So \  Sc" -offset indent
.It Cm \-
Left align
.It Cm \&?
First Alternate Form: humanized number (decimal)
.It Cm #
Second Alternate Form: humanized number (binary)
.It Cm 0
Zero pad
.It So "\ " Sc
Blank for plus
.It Cm +
Explicit + or \- sign
.It Sq Cm '
Thousands separator
.El
.Ss BOOLEAN VALUES
The two possible values
.Sq true
or
.Sq false
may be output in one of three different styles: plain; or alternate
forms 1 and 2 specified using format modifiers.
.Bl -column "FALSE" "Plain (%a)" "Alt 1 (%?a)" "Alt 2 (%#a)" -offset indent
.It Sy "Value" Ta Sy "Plain (%a)" Ta Sy "Alt 1 (%?a)" Ta Sy "Alt 2 (%#a)"
.It Li FALSE Ta No false Ta no  Ta \^
.It Li TRUE  Ta No true  Ta yes Ta (*)
.El
The second alternate form produces no output for
.Cm false .
.Pp
Effective format modifiers:
.Bl -tag -width ".Cm #" -offset indent
.It Cm \&?
First Alternate Form
.It Cm #
Second Alternate Form
.It Cm \-
Left align
.El
.Ss FILE MODE VALUES
The file mode is a bitmap representing setid, user, group and other
permissions.
The plain format prints it as an octal value, for example:
.Bd -literal -offset indent
4755
.Ed
.Pp
The first alternate form is similar but adds a leading zero:
.Bd -literal -offset indent
04755
.Ed
.Pp
Whilst the second alternate form produces a string in the style of
.Xr strmode 3 :
.Bd -literal -offset indent
-rwsr-xr-x
.Ed
.Pp
Note: there is always a space at the end of the
.Xr strmode 3
output.
.Pp
Effective format modifiers (all forms):
.Bl -tag -width ".Cm \-" -offset indent
.It Cm \-
Left align
.El
.Pp
Additionally, when the value is printed as an integer (i.e., plain
or alternate form 1), these additional modifiers take effect:
.Bl -tag -width ".So \  Sc" -offset indent
.It Cm \&?
First Alternate Form: add leading zero to octal integer
.It Cm 0
Zero pad
.El
.Ss LICENSE LOGIC VALUES
License-logic  is a three-valued type: one of
.Sq SINGLE ,
.Sq OR
or
.Sq AND ,
which shows whether the package is distributed under the terms of a
single license, or when there are several applicable licenses, whether
these should be treated as alternatives or applied in aggregate.
There are three different output styles: plain; or alternate forms 1
and 2 specified using format modifiers.
.Bl -column "SINGLE" "Plain (%l)" "Alt 1 (%?l)" "Alt 2 (%#l)" -offset indent
.It Sy "Logic" Ta Sy "Plain (%l)" Ta Sy "Alt 1 (%?l)" Ta Sy "Alt 2 (%#l)"
.It Li SINGLE Ta No single Ta \^ Ta ==
.It Li OR     Ta No or     Ta |  Ta ||
.It Li AND    Ta No and    Ta &  Ta &&
.El
.Pp
Effective format modifiers:
.Bl -tag -width ".Cm #" -offset indent
.It Cm \&?
First Alternate Form
.It Cm #
Second Alternate Form
.It Cm \-
Left align
.El
.Ss DATE-TIME VALUES
When used outside of a
.Dq row format
string may be followed by an optional
.Xr strftime 3
format, enclosed in
.Cm %{
and
.Cm %} ,
which will be used to format the timestamp.
Otherwise the timestamp is printed as an integer value of the
number of seconds since the Epoch (00:00:00 UTC, 1 January 1970; see
.Xr time 3).
.Pp
Effective format modifiers:
.Bl -tag -width ".Cm \-" -offset indent
.It Cm \-
Left align
.El
.Pp
Additionally, when the value is printed as an integer (i.e., without
.Xr strftime 3
format codes enclosed in
.Cm %{
and
.Cm %} ,
the following format modifiers are also effective:
.Bl -tag -width ".So \  Sc" -offset indent
.It Cm \&?
First Alternate Form: humanized number (decimal)
.It Cm #
Second Alternate Form: humanized number (binary)
.It Cm 0
Zero pad
.It So "\ " Sc
Blank for plus
.It Cm +
Explicit + or \- sign
.It Sq Cm '
Thousands separator
.El
.Sh EXAMPLES
To print the package installation timestamp in the form
.Dq Li "Sunday, July 3, 10:02" ,
.Bd -literal -offset indent
#include <pkg.h>
pkg_fprintf(stdout, "%t%{%A, %B %e, %R%}\en", pkg);
.Ed
.Pp
To print the package name and version, followed by the name and
version of all of the packages it depends upon, one per line, each
indented by one tab stop:
.Bd -literal -offset indent
#include <pkg.h>
pkg_printf("%n-%v\en%d%{\et%dn-%dv%|%\en%}\en", pkg, pkg, pkg);
.Ed
.Pp
Note that the item separator part of the row format is only printed
between individual row items.
Thus to fill the character array
.Fa buf
with a one-line string listing all of the licenses for the package
separated by
.Dq and
or
.Dq or
as appropriate:
.Bd -literal -offset indent
#include <pkg.h>
char buf[256];
pkg_snprintf(buf, sizeof(buf), "%L%{%Ln%| %l %}", pkg);
.Ed
.Sh ERRORS
In addition to the errors documented for the
.Xr write 2
system call, the
.Fn pkg_printf
family of functions may fail if:
.Bl -tag -width Er
.It Bq Er EILSEQ
An invalid wide character code was encountered.
.It Bq Er ENOMEM
Insufficient storage space is available.
.El
.Sh SEE ALSO
.Xr pkg_repos 3 ,
.Xr pkg-repository 5 ,
.Xr pkg.conf 5 ,
.Xr pkg 8 ,
.Xr pkg-add 8 ,
.Xr pkg-alias 8 ,
.Xr pkg-annotate 8 ,
.Xr pkg-audit 8 ,
.Xr pkg-autoremove 8 ,
.Xr pkg-backup 8 ,
.Xr pkg-check 8 ,
.Xr pkg-clean 8 ,
.Xr pkg-config 8 ,
.Xr pkg-create 8 ,
.Xr pkg-delete 8 ,
.Xr pkg-fetch 8 ,
.Xr pkg-info 8 ,
.Xr pkg-install 8 ,
.Xr pkg-lock 8 ,
.Xr pkg-query 8 ,
.Xr pkg-register 8 ,
.Xr pkg-repo 8 ,
.Xr pkg-rquery 8 ,
.Xr pkg-search 8 ,
.Xr pkg-set 8 ,
.Xr pkg-shell 8 ,
.Xr pkg-shlib 8 ,
.Xr pkg-ssh 8 ,
.Xr pkg-stats 8 ,
.Xr pkg-update 8 ,
.Xr pkg-updating 8 ,
.Xr pkg-upgrade 8 ,
.Xr pkg-version 8 ,
.Xr pkg-which 8
.Sh BUGS
The
.Nm pkg_printf
family of functions do not correctly handle multibyte characters in the
.Fa format
argument.
.Pp
There is no way to sort the output of array valued items.
.Sh SECURITY CONSIDERATIONS
Equivalents to the
.Fn sprintf
and
.Fn vsprintf
functions are not supplied.
Instead, use
.Fn pkg_snprintf
to write into a fixed length buffer without danger of overflow.
.Pp
The
.Fn pkg_printf
family, like the
.Fn printf
family of functions it is modelled on, is also easily misused in a manner
allowing malicious users to arbitrarily change a running program's
functionality by either causing the program
to print potentially sensitive data
.Dq "left on the stack" ,
or causing it to generate a memory fault or bus error
by dereferencing an invalid pointer.
.Pp
Programmers are therefore strongly advised to never pass untrusted strings
as the
.Fa format
argument, as an attacker can put format specifiers in the string
to mangle your stack,
leading to a possible security hole.
This holds true even if the string was built using a function like
.Fn snprintf ,
as the resulting string may still contain user-supplied conversion specifiers
for later interpolation by
.Fn pkg_printf .
.Pp
Always use the proper secure idiom:
.Pp
.Dl "pkg_snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"