stdio/FreeBSD/printf.3.patch

   1 --- printf.3    2004-11-25 11:38:35.000000000 -0800
   2 +++ printf.3.edit       2006-09-06 16:56:37.000000000 -0700
   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,7 @@
 150  .Fn vsprintf
 151  functions
 152  effectively assume an infinite
 153 -.Fa size .
 154 +.Fa n .
 155  .Pp
 156  The format string is composed of zero or more directives:
 157  ordinary
 158 @@ -287,6 +337,20 @@
 159  .Xr localeconv 3 .
 160  .El
 161  .It
 162 +An optional separator character (
 163 +.Cm \ , | \;  | \ : | _
 164 +) used for separating multiple values when printing an AltiVec or SSE vector,
 165 +or other multi-value unit.
 166 +.Pp
 167 +NOTE: This is an extension to the
 168 +.Fn printf
 169 +specification.
 170 +Behaviour of these values for
 171 +.Fn printf
 172 +is only defined for operating systems conforming to the
 173 +AltiVec Technology Programming Interface Manual.
 174 +(At time of writing this includes only Mac OS X 10.2 and later.)
 175 +.It
 176  An optional decimal digit string specifying a minimum field width.
 177  If the converted value has fewer characters than the field width, it will
 178  be padded with spaces on the left (or right, if the left-adjustment
 179 @@ -379,6 +443,34 @@
 180  .It Sy Modifier Ta Cm c Ta Cm s
 181  .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *"
 182  .El
 183 +.Pp
 184 +The AltiVec Technology Programming Interface Manual also defines five additional length modifiers
 185 +which can be used (in place of the conventional length modifiers) for the printing of AltiVec or SSE vectors:
 186 +.Bl -tag -compact
 187 +.It Cm v
 188 +Treat the argument as a vector value, unit length will be determined by the conversion
 189 +specifier (default = 16 8-bit units for all integer conversions,
 190 +4 32-bit units for floating point conversions).
 191 +.It Cm vh, hv
 192 +Treat the argument as a vector of 8 16-bit units.
 193 +.It Cm vl, lv
 194 +Treat the argument as a vector of 4 32-bit units.
 195 +.El
 196 +.Pp
 197 +NOTE: The vector length specifiers are extensions to the
 198 +.Fn printf
 199 +specification.
 200 +Behaviour of these values for
 201 +.Fn printf
 202 +is only defined for operating systems conforming to the
 203 +AltiVec Technology Programming Interface Manual.
 204 +(At time of writing this includes only Mac OS X 10.2 and later.)
 205 +.Pp
 206 +As a further extension, for SSE2 64-bit units:
 207 +.Bl -tag -compact
 208 +.It Cm vll, llv
 209 +Treat the argument as a vector of 2 64-bit units.
 210 +.El
 211  .It
 212  A character that specifies the type of conversion to be applied.
 213  .El
 214 @@ -790,14 +882,11 @@
 215  .Sh SEE ALSO
 216  .Xr printf 1 ,
 217  .Xr fmtcheck 3 ,
 218 +.Xr printf_l 3 ,
 219  .Xr scanf 3 ,
 220  .Xr setlocale 3 ,
 221 +.Xr stdarg 3 ,
 222  .Xr wprintf 3
 223 -.Rs
 224 -.%T "The FreeBSD Security Architecture"
 225 -.Re
 226 -(See
 227 -.Pa "/usr/share/doc/{to be determined}" . )
 228  .Sh STANDARDS
 229  Subject to the caveats noted in the
 230  .Sx BUGS