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