stdio/FreeBSD/printf.3.patch

   1 --- printf.3.orig       2008-02-29 10:45:39.000000000 -0800
   2 +++ printf.3    2008-02-29 12:19:06.000000000 -0800
   3 @@ -40,39 +40,83 @@
   4  .Dt PRINTF 3
   5  .Os
   6  .Sh NAME
   7 -.Nm printf , fprintf , sprintf , snprintf , asprintf ,
   8 -.Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf
   9 +.Nm asprintf ,
  10 +.Nm fprintf ,
  11 +.Nm printf ,
  12 +.Nm snprintf ,
  13 +.Nm sprintf ,
  14 +.Nm vasprintf ,
  15 +.Nm vfprintf,
  16 +.Nm vprintf ,
  17 +.Nm vsnprintf ,
  18 +.Nm vsprintf
  19  .Nd formatted output conversion
  20  .Sh LIBRARY
  21  .Lb libc
  22  .Sh SYNOPSIS
  23  .In stdio.h
  24  .Ft int
  25 -.Fn printf "const char * restrict format" ...
  26 +.Fo asprintf
  27 +.Fa "char **ret"
  28 +.Fa "const char *format" ...
  29 +.Fc
  30  .Ft int
  31 -.Fn fprintf "FILE * restrict stream" "const char * restrict format" ...
  32 +.Fo fprintf
  33 +.Fa "FILE *restrict stream"
  34 +.Fa "const char *restrict format" ...
  35 +.Fc
  36  .Ft int
  37 -.Fn sprintf "char * restrict str" "const char * restrict format" ...
  38 +.Fo printf
  39 +.Fa "const char *restrict format" ...
  40 +.Fc
  41  .Ft int
  42 -.Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ...
  43 +.Fo snprintf
  44 +.Fa "char *restrict s"
  45 +.Fa "size_t n"
  46 +.Fa "const char *restrict format" ...
  47 +.Fc
  48  .Ft int
  49 -.Fn asprintf "char **ret" "const char *format" ...
  50 +.Fo sprintf
  51 +.Fa "char *restrict s"
  52 +.Fa "const char *restrict format" ...
  53 +.Fc
  54  .In stdarg.h
  55 +.In stdio.h
  56  .Ft int
  57 -.Fn vprintf "const char * restrict format" "va_list ap"
  58 +.Fo vasprintf
  59 +.Fa "char **ret"
  60 +.Fa "const char *format"
  61 +.Fa "va_list ap"
  62 +.Fc
  63  .Ft int
  64 -.Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap"
  65 +.Fo vfprintf
  66 +.Fa "FILE *restrict stream"
  67 +.Fa "const char *restrict format"
  68 +.Fa "va_list ap"
  69 +.Fc
  70  .Ft int
  71 -.Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap"
  72 +.Fo vprintf
  73 +.Fa "const char *restrict format"
  74 +.Fa "va_list ap"
  75 +.Fc
  76  .Ft int
  77 -.Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap"
  78 +.Fo vsnprintf
  79 +.Fa "char *restrict s"
  80 +.Fa "size_t n"
  81 +.Fa "const char *restrict format"
  82 +.Fa "va_list ap"
  83 +.Fc
  84  .Ft int
  85 -.Fn vasprintf "char **ret" "const char *format" "va_list ap"
  86 +.Fo vsprintf
  87 +.Fa "char *restrict s"
  88 +.Fa "const char *restrict format"
  89 +.Fa "va_list ap"
  90 +.Fc
  91  .Sh DESCRIPTION
  92  The
  93  .Fn printf
  94  family of functions produces output according to a
  95 -.Fa format
  96 +.Fa format ,
  97  as described below.
  98  The
  99  .Fn printf
 100 @@ -93,7 +137,7 @@
 101  and
 102  .Fn vsnprintf
 103  write to the character string
 104 -.Fa str ;
 105 +.Fa s ;
 106  and
 107  .Fn asprintf
 108  and
 109 @@ -101,6 +145,12 @@
 110  dynamically allocate a new string with
 111  .Xr malloc 3 .
 112  .Pp
 113 +Extended locale versions of these functions are documented in
 114 +.Xr printf_l 3 .
 115 +See
 116 +.Xr xlocale 3
 117 +for more information.
 118 +.Pp
 119  These functions write the output under the control of a
 120  .Fa format
 121  string that specifies how subsequent arguments
 122 @@ -117,7 +167,7 @@
 123  and
 124  .Fn vsnprintf ,
 125  which return the number of characters that would have been printed if the
 126 -.Fa size
 127 +.Fa n
 128  were unlimited
 129  (again, not including the final
 130  .Ql \e0 ) .
 131 @@ -149,14 +199,14 @@
 132  .Fn vsnprintf
 133  functions
 134  will write at most
 135 -.Fa size Ns \-1
 136 +.Fa n Ns \-1
 137  of the characters printed into the output string
 138  (the
 139 -.Fa size Ns 'th
 140 +.Fa n Ns \'th
 141  character then gets the terminating
 142  .Ql \e0 ) ;
 143  if the return value is greater than or equal to the
 144 -.Fa size
 145 +.Fa n
 146  argument, the string was too short
 147  and some of the printed characters were discarded.
 148  The output is always null-terminated.
 149 @@ -167,7 +217,11 @@
 150  .Fn vsprintf
 151  functions
 152  effectively assume an infinite
 153 -.Fa size .
 154 +.Fa n .
 155 +.Pp
 156 +For those routines that write to a user-provided character string,
 157 +that string and the format strings should not overlap, as the
 158 +behavior is undefined.
 159  .Pp
 160  The format string is composed of zero or more directives:
 161  ordinary
 162 @@ -287,6 +341,20 @@
 163  .Xr localeconv 3 .
 164  .El
 165  .It
 166 +An optional separator character (
 167 +.Cm \ , | \;  | \ : | _
 168 +) used for separating multiple values when printing an AltiVec or SSE vector,
 169 +or other multi-value unit.
 170 +.Pp
 171 +NOTE: This is an extension to the
 172 +.Fn printf
 173 +specification.
 174 +Behaviour of these values for
 175 +.Fn printf
 176 +is only defined for operating systems conforming to the
 177 +AltiVec Technology Programming Interface Manual.
 178 +(At time of writing this includes only Mac OS X 10.2 and later.)
 179 +.It
 180  An optional decimal digit string specifying a minimum field width.
 181  If the converted value has fewer characters than the field width, it will
 182  be padded with spaces on the left (or right, if the left-adjustment
 183 @@ -379,6 +447,34 @@
 184  .It Sy Modifier Ta Cm c Ta Cm s
 185  .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
 186  .El
 187 +.Pp
 188 +The AltiVec Technology Programming Interface Manual also defines five additional length modifiers
 189 +which can be used (in place of the conventional length modifiers) for the printing of AltiVec or SSE vectors:
 190 +.Bl -tag -compact
 191 +.It Cm v
 192 +Treat the argument as a vector value, unit length will be determined by the conversion
 193 +specifier (default = 16 8-bit units for all integer conversions,
 194 +4 32-bit units for floating point conversions).
 195 +.It Cm vh, hv
 196 +Treat the argument as a vector of 8 16-bit units.
 197 +.It Cm vl, lv
 198 +Treat the argument as a vector of 4 32-bit units.
 199 +.El
 200 +.Pp
 201 +NOTE: The vector length specifiers are extensions to the
 202 +.Fn printf
 203 +specification.
 204 +Behaviour of these values for
 205 +.Fn printf
 206 +is only defined for operating systems conforming to the
 207 +AltiVec Technology Programming Interface Manual.
 208 +(At time of writing this includes only Mac OS X 10.2 and later.)
 209 +.Pp
 210 +As a further extension, for SSE2 64-bit units:
 211 +.Bl -tag -compact
 212 +.It Cm vll, llv
 213 +Treat the argument as a vector of 2 64-bit units.
 214 +.El
 215  .It
 216  A character that specifies the type of conversion to be applied.
 217  .El
 218 @@ -790,14 +886,11 @@
 219  .Sh SEE ALSO
 220  .Xr printf 1 ,
 221  .Xr fmtcheck 3 ,
 222 +.Xr printf_l 3 ,
 223  .Xr scanf 3 ,
 224  .Xr setlocale 3 ,
 225 +.Xr stdarg 3 ,
 226  .Xr wprintf 3
 227 -.Rs
 228 -.%T "The FreeBSD Security Architecture"
 229 -.Re
 230 -(See
 231 -.Pa "/usr/share/doc/{to be determined}" . )
 232  .Sh STANDARDS
 233  Subject to the caveats noted in the
 234  .Sx BUGS