sys/man/2/print

   1 .TH PRINT 2
   2 .SH NAME
   3 print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .ta \w'\fLchar* 'u
  10 .B
  11 int     print(char *format, ...)
  12 .PP
  13 .B
  14 int     fprint(int fd, char *format, ...)
  15 .PP
  16 .B
  17 int     sprint(char *s, char *format, ...)
  18 .PP
  19 .B
  20 int     snprint(char *s, int len, char *format, ...)
  21 .PP
  22 .B
  23 char*   seprint(char *s, char *e, char *format, ...)
  24 .PP
  25 .B
  26 char*   smprint(char *format, ...)
  27 .PP
  28 .B
  29 int     runesprint(Rune *s, char *format, ...)
  30 .PP
  31 .B
  32 int     runesnprint(Rune *s, int len, char *format, ...)
  33 .PP
  34 .B
  35 Rune*   runeseprint(Rune *s, Rune *e, char *format, ...)
  36 .PP
  37 .B
  38 Rune*   runesmprint(char *format, ...)
  39 .PP
  40 .B
  41 int     vfprint(int fd, char *format, va_list v)
  42 .PP
  43 .B
  44 int     vsnprint(char *s, int len, char *format, va_list v)
  45 .PP
  46 .B
  47 char*   vseprint(char *s, char *e, char *format, va_list v)
  48 .PP
  49 .B
  50 char*   vsmprint(char *format, va_list v)
  51 .PP
  52 .B
  53 int     runevsnprint(Rune *s, int len, char *format, va_list v)
  54 .PP
  55 .B
  56 Rune*   runevseprint(Rune *s, Rune *e, char *format, va_list v)
  57 .PP
  58 .B
  59 Rune*   runevsmprint(Rune *format, va_list v)
  60 .PP
  61 .B
  62 .SH DESCRIPTION
  63 .I Print
  64 writes text to the standard output.
  65 .I Fprint
  66 writes to the named output
  67 file descriptor;
  68 a buffered form
  69 is described in
  70 .IR bio (2).
  71 .I Sprint
  72 places text
  73 followed by the NUL character
  74 .RB ( \e0 )
  75 in consecutive bytes starting at
  76 .IR s ;
  77 it is the user's responsibility to ensure that
  78 enough storage is available.
  79 Each function returns the number of bytes
  80 transmitted (not including the NUL
  81 in the case of
  82 .IR sprint ),
  83 or
  84 a negative value if an output error was encountered.
  85 .PP
  86 .I Snprint
  87 is like
  88 .IR sprint ,
  89 but will not place more than
  90 .I len
  91 bytes in
  92 .IR s .
  93 Its result is always NUL-terminated and holds the maximal
  94 number of complete UTF-8 characters that can fit.
  95 .I Seprint
  96 is like
  97 .IR snprint ,
  98 except that the end is indicated by a pointer
  99 .I e
 100 rather than a count and the return value points to the terminating NUL of the
 101 resulting string.
 102 .I Smprint
 103 is like
 104 .IR sprint ,
 105 except that it prints into and returns a string of the required length, which is
 106 allocated by
 107 .IR malloc (2).
 108 .PP
 109 The routines
 110 .IR runesprint ,
 111 .IR runesnprint ,
 112 .IR runeseprint ,
 113 and
 114 .I runesmprint
 115 are the same as
 116 .IR sprint ,
 117 .IR snprint ,
 118 .IR seprint
 119 and
 120 .I smprint
 121 except that their output is rune strings instead of byte strings.
 122 .PP
 123 Finally, the routines
 124 .IR vfprint ,
 125 .IR vsnprint ,
 126 .IR vseprint ,
 127 .IR vsmprint ,
 128 .IR runevsnprint ,
 129 .IR runevseprint ,
 130 and
 131 .IR runevsmprint
 132 are like their
 133 .BR v-less
 134 relatives except they take as arguments a
 135 .B va_list
 136 parameter, so they can be called within a variadic function.
 137 The Example section shows a representative usage.
 138 .PP
 139 Each of these functions
 140 converts, formats, and prints its
 141 trailing arguments
 142 under control of a
 143 .IR format
 144 string.
 145 The
 146 format
 147 contains two types of objects:
 148 plain characters, which are simply copied to the
 149 output stream,
 150 and conversion specifications,
 151 each of which results in fetching of
 152 zero or more
 153 arguments.
 154 The results are undefined if there are arguments of the
 155 wrong type or too few
 156 arguments for the format.
 157 If the format is exhausted while
 158 arguments remain, the excess
 159 is ignored.
 160 .PP
 161 Each conversion specification has the following format:
 162 .IP
 163 .B "% [flags] verb
 164 .PP
 165 The verb is a single character and each flag is a single character or a
 166 (decimal) numeric string.
 167 Up to two numeric strings may be used;
 168 the first is called
 169 .IR width ,
 170 the second
 171 .IR precision .
 172 A period can be used to separate them, and if the period is
 173 present then
 174 .I width
 175 and
 176 .I precision
 177 are taken to be zero if missing, otherwise they are `omitted'.
 178 Either or both of the numbers may be replaced with the character
 179 .BR * ,
 180 meaning that the actual number will be obtained from the argument list
 181 as an integer.
 182 The flags and numbers are arguments to
 183 the
 184 .I verb
 185 described below.
 186 .PP
 187 The numeric verbs
 188 .BR d ,
 189 .BR o ,
 190 .BR b ,
 191 .BR x ,
 192 and
 193 .B X
 194 format their arguments in decimal,
 195 octal, binary, hexadecimal, and upper case hexadecimal.
 196 Each interprets the flags
 197 .BR 0 ,
 198 .BR h ,
 199 .BR hh ,
 200 .BR l ,
 201 .BR ll ,
 202 .BR u ,
 203 .BR + ,
 204 .BR - ,
 205 .BR , ,
 206 and
 207 .B #
 208 to mean pad with zeros,
 209 short, byte, long, vlong, unsigned, always print a sign, left justified, commas every three digits,
 210 and alternate format.
 211 Also, a space character in the flag
 212 position is like
 213 .BR + ,
 214 but prints a space instead of a plus sign for non-negative values.
 215 If neither
 216 short nor long is specified,
 217 then the argument is an
 218 .BR int .
 219 If unsigned is specified,
 220 then the argument is interpreted as a
 221 positive number and no sign is output.
 222 If
 223 .I precision
 224 is not omitted, the number is padded on the left with zeros
 225 until at least
 226 .I precision
 227 digits appear.
 228 Then, if alternate format is specified,
 229 for
 230 .B o
 231 conversion, the number is preceded by a
 232 .B 0
 233 if it doesn't already begin with one;
 234 for
 235 .B x
 236 conversion, the number is preceded by
 237 .BR 0x ;
 238 for
 239 .B X
 240 conversion, the number is preceded by
 241 .BR 0X .
 242 Finally, if
 243 .I width
 244 is not omitted, the number is padded on the left (or right, if
 245 left justification is specified) with enough blanks to
 246 make the field at least
 247 .I width
 248 characters long.
 249 .PP
 250 The floating point verbs
 251 .BR f ,
 252 .BR e ,
 253 .BR E ,
 254 .BR g ,
 255 and
 256 .B G
 257 take a
 258 .B double
 259 argument.
 260 Each interprets the flags
 261 .BR + ,
 262 .BR - ,
 263 and
 264 .B #
 265 to mean
 266 always print a sign,
 267 left justified,
 268 and
 269 alternate format.
 270 .I Width
 271 is the minimum field width and,
 272 if the converted value takes up less than
 273 .I width
 274 characters, it is padded on the left (or right, if `left justified')
 275 with spaces.
 276 .I Precision
 277 is the number of digits that are converted after the decimal place for
 278 .BR e ,
 279 .BR E ,
 280 and
 281 .B f
 282 conversions,
 283 and
 284 .I precision
 285 is the maximum number of significant digits for
 286 .B g
 287 and
 288 .B G
 289 conversions.
 290 The
 291 .B f
 292 verb produces output of the form
 293 .RB [ - ] digits [ .digits\fR].
 294 .B E
 295 conversion appends an exponent
 296 .BR E [ - ] digits ,
 297 and
 298 .B e
 299 conversion appends an exponent
 300 .BR e [ - ] digits .
 301 The
 302 .B g
 303 verb will output the argument in either
 304 .B e
 305 or
 306 .B f
 307 with the goal of producing the smallest output.
 308 Also, trailing zeros are omitted from the fraction part of
 309 the output, and a trailing decimal point appears only if it is followed
 310 by a digit.
 311 The
 312 .B G
 313 verb is similar, but uses
 314 .B E
 315 format instead of
 316 .BR e .
 317 When alternate format is specified, the result will always contain a decimal point,
 318 and for
 319 .B g
 320 and
 321 .B G
 322 conversions, trailing zeros are not removed.
 323 .PP
 324 The
 325 .B s
 326 verb copies a nul-terminated string
 327 (pointer to
 328 .BR char )
 329 to the output.
 330 The number of characters copied
 331 .RI ( n )
 332 is the minimum
 333 of the size of the string and
 334 .IR precision .
 335 These
 336 .I n
 337 characters are justified within a field of
 338 .I width
 339 characters as described above.
 340 If a
 341 .I precision
 342 is given, it is safe for the string not to be nul-terminated
 343 as long as it is at least
 344 .I precision
 345 characters (not bytes!) long.
 346 The
 347 .B S
 348 verb is similar, but it interprets its pointer as an array
 349 of runes (see
 350 .IR utf (6));
 351 the runes are converted to
 352 .SM UTF
 353 before output.
 354 .PP
 355 The
 356 .B c
 357 verb copies a single
 358 .B char
 359 (promoted to
 360 .BR int )
 361 justified within a field of
 362 .I width
 363 characters as described above.
 364 The
 365 .B C
 366 verb is similar, but works on runes.
 367 .PP
 368 The
 369 .B p
 370 verb formats a single pointer or pointer-sized integer
 371 .RB ( uintptr ,
 372 see
 373 .IR intro (2))
 374 in hexadecimal.
 375 .PP
 376 The
 377 .B r
 378 verb takes no arguments; it copies the error string returned by a call to
 379 .IR errstr (2).
 380 .PP
 381 Custom verbs may be installed using
 382 .IR fmtinstall (2).
 383 .SH EXAMPLE
 384 This function prints an error message with a variable
 385 number of arguments and then quits.
 386 .IP
 387 .EX
 388 .ta 6n +6n +6n
 389 void fatal(char *msg, ...)
 390 {
 391         char buf[1024], *out;
 392         va_list arg;
 393
 394         out = seprint(buf, buf+sizeof(buf), "Fatal error: ");
 395         va_start(arg, msg);
 396         out = vseprint(out, buf+sizeof(buf), msg, arg);
 397         va_end(arg);
 398         write(2, buf, out-buf);
 399         exits("fatal error");
 400 }
 401 .EE
 402 .SH SOURCE
 403 .B /sys/src/libc/fmt
 404 .SH SEE ALSO
 405 .IR fmtinstall (2),
 406 .IR fprintf (2),
 407 .IR utf (6),
 408 .IR errstr (2)
 409 .SH DIAGNOSTICS
 410 Routines that write to a file descriptor or call
 411 .IR malloc
 412 set
 413 .IR errstr .
 414 .SH BUGS
 415 The formatting is close to that specified for ANSI
 416 .IR fprintf (2);
 417 the main difference is that
 418 .B b
 419 is not in ANSI and
 420 .B u
 421 is a flag here instead of a verb.
 422 Also, and distinctly not a bug,
 423 .I print
 424 and friends generate
 425 .SM UTF
 426 rather than
 427 .SM ASCII.
 428 .PP
 429 There is no
 430 .BR runeprint ,
 431 .BR runefprint ,
 432 etc. because runes are byte-order dependent and should not be written directly to a file; use the
 433 UTF output of
 434 .I print
 435 or
 436 .I fprint
 437 instead.
 438 Also,
 439 .I sprint
 440 is deprecated for safety reasons; use
 441 .IR snprint ,
 442 .IR seprint ,
 443 or
 444 .I smprint
 445 instead.
 446 Safety also precludes the existence of
 447 .IR runesprint .