wmii

git clone git://oldgit.suckless.org/wmii/
Log | Files | Refs | README | LICENSE

print.3 (9420B)


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