print.3 (9107B)
1 .TH PRINT 3 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 .PP 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 .MR bio (3) . 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 .MR malloc (3) . 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 They return a rune count rather than a byte count. 123 .PP 124 Finally, the routines 125 .IR vfprint , 126 .IR vsnprint , 127 .IR vseprint , 128 .IR vsmprint , 129 .IR runevsnprint , 130 .IR runevseprint , 131 and 132 .I runevsmprint 133 are like their 134 .BR v-less 135 relatives except they take as arguments a 136 .B va_list 137 parameter, so they can be called within a variadic function. 138 The Example section shows a representative usage. 139 .PP 140 Each of these functions 141 converts, formats, and prints its 142 trailing arguments 143 under control of a 144 .IR format 145 string. 146 The 147 format 148 contains two types of objects: 149 plain characters, which are simply copied to the 150 output stream, 151 and conversion specifications, 152 each of which results in fetching of 153 zero or more 154 arguments. 155 The results are undefined if there are arguments of the 156 wrong type or too few 157 arguments for the format. 158 If the format is exhausted while 159 arguments remain, the excess 160 is ignored. 161 .PP 162 Each conversion specification has the following format: 163 .IP 164 .B "% [flags] verb 165 .PP 166 The verb is a single character and each flag is a single character or a 167 (decimal) numeric string. 168 Up to two numeric strings may be used; 169 the first is called 170 .IR width , 171 the second 172 .IR precision . 173 A period can be used to separate them, and if the period is 174 present then 175 .I width 176 and 177 .I precision 178 are taken to be zero if missing, otherwise they are `omitted'. 179 Either or both of the numbers may be replaced with the character 180 .BR * , 181 meaning that the actual number will be obtained from the argument list 182 as an integer. 183 The flags and numbers are arguments to 184 the 185 .I verb 186 described below. 187 .PP 188 The numeric verbs 189 .BR d , 190 .BR o , 191 .BR b , 192 .BR x , 193 and 194 .B X 195 format their arguments in decimal, 196 octal, binary, hexadecimal, and upper case hexadecimal. 197 Each interprets the flags 198 .BR 0 , 199 .BR h , 200 .BR hh , 201 .BR l , 202 .BR u , 203 .BR + , 204 .BR - , 205 .BR , , 206 and 207 .B # 208 to mean pad with zeros, 209 short, byte, long, 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 two 223 .B l 224 flags are given, 225 then the argument is interpreted as a 226 .B vlong 227 (usually an 8-byte, sometimes a 4-byte integer). 228 If 229 .I precision 230 is not omitted, the number is padded on the left with zeros 231 until at least 232 .I precision 233 digits appear. 234 If 235 .I precision 236 is explicitly 0, and the number is 0, 237 no digits are generated, and alternate formatting 238 does not apply. 239 Then, if alternate format is specified, 240 for 241 .B o 242 conversion, the number is preceded by a 243 .B 0 244 if it doesn't already begin with one; 245 for 246 .B x 247 conversion, the number is preceded by 248 .BR 0x ; 249 for 250 .B X 251 conversion, the number is preceded by 252 .BR 0X . 253 Finally, if 254 .I width 255 is not omitted, the number is padded on the left (or right, if 256 left justification is specified) with enough blanks to 257 make the field at least 258 .I width 259 characters long. 260 .PP 261 The floating point verbs 262 .BR f , 263 .BR e , 264 .BR E , 265 .BR g , 266 and 267 .B G 268 take a 269 .B double 270 argument. 271 Each interprets the flags 272 .BR 0 , 273 .BR L 274 .BR + , 275 .BR - , 276 and 277 .B # 278 to mean pad with zeros, 279 long double argument, 280 always print a sign, 281 left justified, 282 and 283 alternate format. 284 .I Width 285 is the minimum field width and, 286 if the converted value takes up less than 287 .I width 288 characters, it is padded on the left (or right, if `left justified') 289 with spaces. 290 .I Precision 291 is the number of digits that are converted after the decimal place for 292 .BR e , 293 .BR E , 294 and 295 .B f 296 conversions, 297 and 298 .I precision 299 is the maximum number of significant digits for 300 .B g 301 and 302 .B G 303 conversions. 304 The 305 .B f 306 verb produces output of the form 307 .RB [ - ] digits [ .digits\fR]. 308 .B E 309 conversion appends an exponent 310 .BR E [ - ] digits , 311 and 312 .B e 313 conversion appends an exponent 314 .BR e [ - ] digits . 315 The 316 .B g 317 verb will output the argument in either 318 .B e 319 or 320 .B f 321 with the goal of producing the smallest output. 322 Also, trailing zeros are omitted from the fraction part of 323 the output, and a trailing decimal point appears only if it is followed 324 by a digit. 325 The 326 .B G 327 verb is similar, but uses 328 .B E 329 format instead of 330 .BR e . 331 When alternate format is specified, the result will always contain a decimal point, 332 and for 333 .B g 334 and 335 .B G 336 conversions, trailing zeros are not removed. 337 .PP 338 The 339 .B s 340 verb copies a NUL-terminated string 341 (pointer to 342 .BR char ) 343 to the output. 344 The number of characters copied 345 .RI ( n ) 346 is the minimum 347 of the size of the string and 348 .IR precision . 349 These 350 .I n 351 characters are justified within a field of 352 .I width 353 characters as described above. 354 If a 355 .I precision 356 is given, it is safe for the string not to be nul-terminated 357 as long as it is at least 358 .I precision 359 characters (not bytes!) long. 360 The 361 .B S 362 verb is similar, but it interprets its pointer as an array 363 of runes (see 364 .MR utf (7) ); 365 the runes are converted to 366 .SM UTF 367 before output. 368 .PP 369 The 370 .B c 371 verb copies a single 372 .B char 373 (promoted to 374 .BR int ) 375 justified within a field of 376 .I width 377 characters as described above. 378 The 379 .B C 380 verb is similar, but works on runes. 381 .PP 382 The 383 .B p 384 verb formats a pointer value. 385 At the moment, it is a synonym for 386 .BR x , 387 but that will change if pointers and integers are different sizes. 388 .PP 389 The 390 .B r 391 verb takes no arguments; it copies the error string returned by a call to 392 .MR errstr (3) . 393 .PP 394 Custom verbs may be installed using 395 .MR fmtinstall (3) . 396 .SH EXAMPLE 397 This function prints an error message with a variable 398 number of arguments and then quits. 399 .IP 400 .EX 401 .ta 6n +6n +6n 402 void fatal(char *msg, ...) 403 { 404 char buf[1024], *out; 405 va_list arg; 406 407 out = seprint(buf, buf+sizeof buf, "Fatal error: "); 408 va_start(arg, msg); 409 out = vseprint(out, buf+sizeof buf, msg, arg); 410 va_end(arg); 411 write(2, buf, out-buf); 412 exits("fatal error"); 413 } 414 .EE 415 .SH SOURCE 416 .B \*9/src/lib9/fmt 417 .SH SEE ALSO 418 .MR fmtinstall (3) , 419 .MR fprintf (3) , 420 .MR utf (7) 421 .SH DIAGNOSTICS 422 Routines that write to a file descriptor or call 423 .IR malloc 424 set 425 .IR errstr . 426 .SH BUGS 427 The formatting is close to that specified for ANSI 428 .MR fprintf (3) ; 429 the main difference is that 430 .B b 431 and 432 .B r 433 are not in ANSI and 434 .B u 435 is a flag here instead of a verb. 436 Also, and distinctly not a bug, 437 .I print 438 and friends generate 439 .SM UTF 440 rather than 441 .SM ASCII. 442 .PP 443 There is no 444 .IR runeprint , 445 .IR runefprint , 446 etc. because runes are byte-order dependent and should not be written directly to a file; use the 447 UTF output of 448 .I print 449 or 450 .I fprint 451 instead. 452 Also, 453 .I sprint 454 is deprecated for safety reasons; use 455 .IR snprint , 456 .IR seprint , 457 or 458 .I smprint 459 instead. 460 Safety also precludes the existence of 461 .IR runesprint .