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 u ,
 202 .BR + ,
 203 .BR - ,
 204 .BR , ,
 205 and
 206 .B #
 207 to mean pad with zeros,
 208 short, byte, long, unsigned, always print a sign, left justified, commas every three digits,
 209 and alternate format.
 210 Also, a space character in the flag
 211 position is like
 212 .BR + ,
 213 but prints a space instead of a plus sign for non-negative values.
 214 If neither
 215 short nor long is specified,
 216 then the argument is an
 217 .BR int .
 218 If unsigned is specified,
 219 then the argument is interpreted as a
 220 positive number and no sign is output.
 221 If two
 222 .B l
 223 flags are given,
 224 then the argument is interpreted as a
 225 .B vlong
 226 (usually an 8-byte, sometimes a 4-byte integer).
 227 If
 228 .I precision
 229 is not omitted, the number is padded on the left with zeros
 230 until at least
 231 .I precision
 232 digits appear.
 233 Then, if alternate format is specified,
 234 for
 235 .B o
 236 conversion, the number is preceded by a
 237 .B 0
 238 if it doesn't already begin with one;
 239 for
 240 .B x
 241 conversion, the number is preceded by
 242 .BR 0x ;
 243 for
 244 .B X
 245 conversion, the number is preceded by
 246 .BR 0X .
 247 Finally, if
 248 .I width
 249 is not omitted, the number is padded on the left (or right, if
 250 left justification is specified) with enough blanks to
 251 make the field at least
 252 .I width
 253 characters long.
 254 .PP
 255 The floating point verbs
 256 .BR f ,
 257 .BR e ,
 258 .BR E ,
 259 .BR g ,
 260 and
 261 .B G
 262 take a
 263 .B double
 264 argument.
 265 Each interprets the flags
 266 .BR + ,
 267 .BR - ,
 268 and
 269 .B #
 270 to mean
 271 always print a sign,
 272 left justified,
 273 and
 274 alternate format.
 275 .I Width
 276 is the minimum field width and,
 277 if the converted value takes up less than
 278 .I width
 279 characters, it is padded on the left (or right, if `left justified')
 280 with spaces.
 281 .I Precision
 282 is the number of digits that are converted after the decimal place for
 283 .BR e ,
 284 .BR E ,
 285 and
 286 .B f
 287 conversions,
 288 and
 289 .I precision
 290 is the maximum number of significant digits for
 291 .B g
 292 and
 293 .B G
 294 conversions.
 295 The
 296 .B f
 297 verb produces output of the form
 298 .RB [ - ] digits [ .digits\fR].
 299 .B E
 300 conversion appends an exponent
 301 .BR E [ - ] digits ,
 302 and
 303 .B e
 304 conversion appends an exponent
 305 .BR e [ - ] digits .
 306 The
 307 .B g
 308 verb will output the argument in either
 309 .B e
 310 or
 311 .B f
 312 with the goal of producing the smallest output.
 313 Also, trailing zeros are omitted from the fraction part of
 314 the output, and a trailing decimal point appears only if it is followed
 315 by a digit.
 316 The
 317 .B G
 318 verb is similar, but uses
 319 .B E
 320 format instead of
 321 .BR e .
 322 When alternate format is specified, the result will always contain a decimal point,
 323 and for
 324 .B g
 325 and
 326 .B G
 327 conversions, trailing zeros are not removed.
 328 .PP
 329 The
 330 .B s
 331 verb copies a nul-terminated string
 332 (pointer to
 333 .BR char )
 334 to the output.
 335 The number of characters copied
 336 .RI ( n )
 337 is the minimum
 338 of the size of the string and
 339 .IR precision .
 340 These
 341 .I n
 342 characters are justified within a field of
 343 .I width
 344 characters as described above.
 345 If a
 346 .I precision
 347 is given, it is safe for the string not to be nul-terminated
 348 as long as it is at least
 349 .I precision
 350 characters (not bytes!) long.
 351 The
 352 .B S
 353 verb is similar, but it interprets its pointer as an array
 354 of runes (see
 355 .IR utf (6));
 356 the runes are converted to
 357 .SM UTF
 358 before output.
 359 .PP
 360 The
 361 .B c
 362 verb copies a single
 363 .B char
 364 (promoted to
 365 .BR int )
 366 justified within a field of
 367 .I width
 368 characters as described above.
 369 The
 370 .B C
 371 verb is similar, but works on runes.
 372 .PP
 373 The
 374 .B p
 375 verb formats a single pointer or pointer-sized integer
 376 .RB ( uintptr ,
 377 see
 378 .IR intro (2))
 379 in hexadecimal.
 380 .PP
 381 The
 382 .B r
 383 verb takes no arguments; it copies the error string returned by a call to
 384 .IR errstr (2).
 385 .PP
 386 Custom verbs may be installed using
 387 .IR fmtinstall (2).
 388 .SH EXAMPLE
 389 This function prints an error message with a variable
 390 number of arguments and then quits.
 391 .IP
 392 .EX
 393 .ta 6n +6n +6n
 394 void fatal(char *msg, ...)
 395 {
 396         char buf[1024], *out;
 397         va_list arg;
 398
 399         out = seprint(buf, buf+sizeof(buf), "Fatal error: ");
 400         va_start(arg, msg);
 401         out = vseprint(out, buf+sizeof(buf), msg, arg);
 402         va_end(arg);
 403         write(2, buf, out-buf);
 404         exits("fatal error");
 405 }
 406 .EE
 407 .SH SOURCE
 408 .B /sys/src/libc/fmt
 409 .SH SEE ALSO
 410 .IR fmtinstall (2),
 411 .IR fprintf (2),
 412 .IR utf (6),
 413 .IR errstr (2)
 414 .SH DIAGNOSTICS
 415 Routines that write to a file descriptor or call
 416 .IR malloc
 417 set
 418 .IR errstr .
 419 .SH BUGS
 420 The formatting is close to that specified for ANSI
 421 .IR fprintf (2);
 422 the main difference is that
 423 .B b
 424 is not in ANSI and
 425 .B u
 426 is a flag here instead of a verb.
 427 Also, and distinctly not a bug,
 428 .I print
 429 and friends generate
 430 .SM UTF
 431 rather than
 432 .SM ASCII.
 433 .PP
 434 There is no
 435 .BR runeprint ,
 436 .BR runefprint ,
 437 etc. because runes are byte-order dependent and should not be written directly to a file; use the
 438 UTF output of
 439 .I print
 440 or
 441 .I fprint
 442 instead.
 443 Also,
 444 .I sprint
 445 is deprecated for safety reasons; use
 446 .IR snprint ,
 447 .IR seprint ,
 448 or
 449 .I smprint
 450 instead.
 451 Safety also precludes the existence of
 452 .IR runesprint .