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