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 .