stdio/FreeBSD/printf.3.patch

   1 --- printf.3.orig       2009-12-15 17:50:20.000000000 -0800
   2 +++ printf.3    2009-12-15 17:58:46.000000000 -0800
   3 @@ -42,7 +42,6 @@
   4  .Sh LIBRARY
   5  .Lb libc
   6  .Sh SYNOPSIS
   7 -.Fd "#define _WITH_DPRINTF"
   8  .In stdio.h
   9  .Ft int
  10  .Fn printf "const char * restrict format" ...
  11 @@ -98,7 +97,7 @@ write output to the given file descripto
  12  and
  13  .Fn vsnprintf
  14  write to the character string
  15 -.Fa str ;
  16 +.Fa s ;
  17  and
  18  .Fn asprintf
  19  and
  20 @@ -106,6 +105,12 @@ and
  21  dynamically allocate a new string with
  22  .Xr malloc 3 .
  23  .Pp
  24 +Extended locale versions of these functions are documented in
  25 +.Xr printf_l 3 .
  26 +See
  27 +.Xr xlocale 3
  28 +for more information.
  29 +.Pp
  30  These functions write the output under the control of a
  31  .Fa format
  32  string that specifies how subsequent arguments
  33 @@ -122,7 +127,7 @@ except for
  34  and
  35  .Fn vsnprintf ,
  36  which return the number of characters that would have been printed if the
  37 -.Fa size
  38 +.Fa n
  39  were unlimited
  40  (again, not including the final
  41  .Ql \e0 ) .
  42 @@ -154,14 +159,14 @@ and
  43  .Fn vsnprintf
  44  functions
  45  will write at most
  46 -.Fa size Ns \-1
  47 +.Fa n Ns \-1
  48  of the characters printed into the output string
  49  (the
  50 -.Fa size Ns 'th
  51 +.Fa n Ns \'th
  52  character then gets the terminating
  53  .Ql \e0 ) ;
  54  if the return value is greater than or equal to the
  55 -.Fa size
  56 +.Fa n
  57  argument, the string was too short
  58  and some of the printed characters were discarded.
  59  The output is always null-terminated.
  60 @@ -172,7 +177,11 @@ and
  61  .Fn vsprintf
  62  functions
  63  effectively assume an infinite
  64 -.Fa size .
  65 +.Fa n .
  66 +.Pp
  67 +For those routines that write to a user-provided character string,
  68 +that string and the format strings should not overlap, as the
  69 +behavior is undefined.
  70  .Pp
  71  The format string is composed of zero or more directives:
  72  ordinary
  73 @@ -291,6 +300,20 @@ the non-monetary separator returned by
  74  .Xr localeconv 3 .
  75  .El
  76  .It
  77 +An optional separator character (
  78 +.Cm \ , | \;  | \ : | _
  79 +) used for separating multiple values when printing an AltiVec or SSE vector,
  80 +or other multi-value unit.
  81 +.Pp
  82 +NOTE: This is an extension to the
  83 +.Fn printf
  84 +specification.
  85 +Behaviour of these values for
  86 +.Fn printf
  87 +is only defined for operating systems conforming to the
  88 +AltiVec Technology Programming Interface Manual.
  89 +(At time of writing this includes only Mac OS X 10.2 and later.)
  90 +.It
  91  An optional decimal digit string specifying a minimum field width.
  92  If the converted value has fewer characters than the field width, it will
  93  be padded with spaces on the left (or right, if the left-adjustment
  94 @@ -383,6 +406,34 @@ conversion:
  95  .It Sy Modifier Ta Cm c Ta Cm s
  96  .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
  97  .El
  98 +.Pp
  99 +The AltiVec Technology Programming Interface Manual also defines five additional length modifiers
 100 +which can be used (in place of the conventional length modifiers) for the printing of AltiVec or SSE vectors:
 101 +.Bl -tag -compact
 102 +.It Cm v
 103 +Treat the argument as a vector value, unit length will be determined by the conversion
 104 +specifier (default = 16 8-bit units for all integer conversions,
 105 +4 32-bit units for floating point conversions).
 106 +.It Cm vh, hv
 107 +Treat the argument as a vector of 8 16-bit units.
 108 +.It Cm vl, lv
 109 +Treat the argument as a vector of 4 32-bit units.
 110 +.El
 111 +.Pp
 112 +NOTE: The vector length specifiers are extensions to the
 113 +.Fn printf
 114 +specification.
 115 +Behaviour of these values for
 116 +.Fn printf
 117 +is only defined for operating systems conforming to the
 118 +AltiVec Technology Programming Interface Manual.
 119 +(At time of writing this includes only Mac OS X 10.2 and later.)
 120 +.Pp
 121 +As a further extension, for SSE2 64-bit units:
 122 +.Bl -tag -compact
 123 +.It Cm vll, llv
 124 +Treat the argument as a vector of 2 64-bit units.
 125 +.El
 126  .It
 127  A character that specifies the type of conversion to be applied.
 128  .El
 129 @@ -561,10 +612,9 @@ For example,
 130  and
 131  .Li 0xc.9p-2
 132  are all equivalent.
 133 -.Fx 8.0
 134 -and later always prints finite non-zero numbers using
 135 -.Ql 1
 136 -as the digit before the hexadecimal point.
 137 +The format chosen depends on the internal representation of the
 138 +number, but the implementation guarantees that the length of the
 139 +mantissa will be minimized.
 140  Zeroes are always represented with a mantissa of 0 (preceded by a
 141  .Ql -
 142  if appropriate) and an exponent of
 143 @@ -781,34 +831,6 @@ Always use the proper secure idiom:
 144  .Pp
 145  .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);"
 146  .Sh COMPATIBILITY
 147 -Many application writers used the name
 148 -.Va dprintf
 149 -before the
 150 -.Fn dprintf
 151 -function was introduced in
 152 -.St -p1003.1 ,
 153 -so a prototype is not provided by default in order to avoid
 154 -compatibility problems.
 155 -Applications that wish to use the
 156 -.Fn dprintf
 157 -function described herein should either request a strict
 158 -.St -p1003.1-2008
 159 -environment by defining the macro
 160 -.Dv _POSIX_C_SOURCE
 161 -to the value 200809 or greater, or by defining the macro
 162 -.Dv _WITH_DPRINTF ,
 163 -prior to the inclusion of
 164 -.In stdio.h .
 165 -For compatibility with GNU libc, defining either
 166 -.Dv _BSD_SOURCE
 167 -or
 168 -.Dv _GNU_SOURCE
 169 -prior to the inclusion of
 170 -.In stdio.h
 171 -will also make
 172 -.Fn dprintf
 173 -available.
 174 -.Pp
 175  The conversion formats
 176  .Cm \&%D , \&%O ,
 177  and
 178 @@ -845,9 +867,11 @@ Insufficient storage space is available.
 179  .El
 180  .Sh SEE ALSO
 181  .Xr printf 1 ,
 182 +.Xr printf_l 3 ,
 183  .Xr fmtcheck 3 ,
 184  .Xr scanf 3 ,
 185  .Xr setlocale 3 ,
 186 +.Xr stdarg 3 ,
 187  .Xr wprintf 3
 188  .Sh STANDARDS
 189  Subject to the caveats noted in the