From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/print.html | 309 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 309 insertions(+) create mode 100644 man/man3/print.html (limited to 'man/man3/print.html') diff --git a/man/man3/print.html b/man/man3/print.html new file mode 100644 index 00000000..8640efc7 --- /dev/null +++ b/man/man3/print.html @@ -0,0 +1,309 @@ + +print(3) - Plan 9 from User Space + + + + +
+
+
PRINT(3)PRINT(3) +
+
+

NAME
+ +
+ + print, fprint, sprint, snprint, seprint, smprint, runesprint, + runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, + vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted + output
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> +
+ + #include <libc.h> +
+ + int     print(char *format, ...) +
+ + int     fprint(int fd, char *format, ...) +
+ + int     sprint(char *s, char *format, ...) +
+ + int     snprint(char *s, int len, char *format, ...) +
+ + char* seprint(char *s, char *e, char *format, ...) +
+ + char* smprint(char *format, ...) +
+ + int     runesprint(Rune *s, char *format, ...) +
+ + int     runesnprint(Rune *s, int len, char *format, ...) +
+ + Rune* runeseprint(Rune *s, Rune *e, char *format, ...) +
+ + Rune* runesmprint(char *format, ...) +
+ + int     vfprint(int fd, char *format, va_list v) +
+ + int     vsnprint(char *s, int len, char *format, va_list v) +
+ + char* vseprint(char *s, char *e, char *format, va_list v) +
+ + char* vsmprint(char *format, va_list v) +
+ + int     runevsnprint(Rune *s, int len, char *format, va_list v) +
+ + Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v) + +
+ + Rune* runevsmprint(Rune *format, va_list v) +
+ + +
+

DESCRIPTION
+ +
+ + Print writes text to the standard output. Fprint writes to the + named output file descriptor: a buffered form is described in + bio(3). Sprint places text followed by the NUL character (\0) + in consecutive bytes starting at s; it is the user’s responsibility + to ensure that enough storage is available. Each function returns + the + number of bytes transmitted (not including the NUL in the case + of sprint), or a negative value if an output error was encountered. + +
+ + Snprint is like sprint, but will not place more than len bytes + in s. Its result is always NUL-terminated and holds the maximal + number of complete UTF-8 characters that can fit. Seprint is like + snprint, except that the end is indicated by a pointer e rather + than a count and the return value points to the terminating NUL + of + the resulting string. Smprint is like sprint, except that it prints + into and returns a string of the required length, which is allocated + by malloc(3). +
+ + The routines runesprint, runesnprint, runeseprint, and runesmprint + are the same as sprint, snprint, seprint and smprint except that + their output is rune strings instead of byte strings. +
+ + Finally, the routines vfprint, vsnprint, vseprint, vsmprint, runevsnprint, + runevseprint, and runevsmprint are like their v−less relatives + except they take as arguments a va_list parameter, so they can + be called within a variadic function. The Example section shows + a representative usage. +
+ + Each of these functions converts, formats, and prints its trailing + arguments under control of a format string. The format contains + two types of objects: plain characters, which are simply copied + to the output stream, and conversion specifications, each of which + results in fetching of zero or more arguments. The results + are undefined if there are arguments of the wrong type or too + few arguments for the format. If the format is exhausted while + arguments remain, the excess is ignored. +
+ + Each conversion specification has the following format:
+ +
+ + % [flags] verb +
+ + +
+ The verb is a single character and each flag is a single character + or a (decimal) numeric string. Up to two numeric strings may be + used; the first is called width, the second precision. A period + can be used to separate them, and if the period is present then + width and precision are taken to be zero if missing, otherwise + they are ‘omitted’. Either or both of the numbers may be replaced + with the character *, meaning that the actual number will be obtained + from the argument list as an integer. The flags and numbers are + arguments to the verb described below. +
+ + The numeric verbs d, o, b, x, and X format their arguments in + decimal, octal, binary, hexadecimal, and upper case hexadecimal. + Each interprets the flags 0, h, hh, l, u, +, −, ,, and # to mean + pad with zeros, short, byte, long, unsigned, always print a sign, + left justified, commas every three digits, and alternate format. + Also, a space character in the flag position is like +, but prints + a space instead of a plus sign for non-negative values. If neither + short nor long is specified, then the argument is an int. If unsigned + is specified, then the argument is interpreted as a positive number + and no sign is output. If two l flags are given, then + the argument is interpreted as a vlong (usually an 8-byte, sometimes + a 4-byte integer). If precision is not omitted, the number is + padded on the left with zeros until at least precision digits + appear. If precision is explicitly 0, and the number is 0, no + digits are generated, and alternate formatting does not apply. + Then, + if alternate format is specified, for o conversion, the number + is preceded by a 0 if it doesn’t already begin with one; for x + conversion, the number is preceded by 0x; for X conversion, the + number is preceded by 0X. Finally, if width is not omitted, the + number is padded on the left (or right, if left justification + is specified) + with enough blanks to make the field at least width characters + long. +
+ + The floating point verbs f, e, E, g, and G take a double argument. + Each interprets the flags 0, L +, −, and # to mean pad with zeros, + long double argument, always print a sign, left justified, and + alternate format. Width is the minimum field width and, if the + converted value takes up less than width characters, it is + padded on the left (or right, if ‘left justified’) with spaces. + Precision is the number of digits that are converted after the + decimal place for e, E, and f conversions, and precision is the + maximum number of significant digits for g and G conversions. + The f verb produces output of the form [−]digits[.digits]. E + conversion appends an exponent E[−]digits, and e conversion appends + an exponent e[−]digits. The g verb will output the argument in + either e or f with the goal of producing the smallest output. + Also, trailing zeros are omitted from the fraction part of the + output, and a trailing decimal point appears only if it is + followed by a digit. The G verb is similar, but uses E format + instead of e. When alternate format is specified, the result will + always contain a decimal point, and for g and G conversions, trailing + zeros are not removed. +
+ + The s verb copies a NUL-terminated string (pointer to char) to + the output. The number of characters copied (n) is the minimum + of the size of the string and precision. These n characters are + justified within a field of width characters as described above. + If a precision is given, it is safe for the string not to be nul- + terminated as long as it is at least precision characters (not + bytes!) long. The S verb is similar, but it interprets its pointer + as an array of runes (see utf(7)); the runes are converted to + UTF before output. +
+ + The c verb copies a single char (promoted to int) justified within + a field of width characters as described above. The C verb is + similar, but works on runes. +
+ + The p verb formats a pointer value. At the moment, it is a synonym + for x, but that will change if pointers and integers are different + sizes. +
+ + The r verb takes no arguments; it copies the error string returned + by a call to errstr(3). +
+ + Custom verbs may be installed using fmtinstall(3).
+ +
+

EXAMPLE
+ +
+ + This function prints an error message with a variable number of + arguments and then quits.
+ +
+ + void fatal(char *msg, ...)
+ {
+ +
+ + char buf[1024], *out;
+ va_list arg;
+ out = seprint(buf, buf+sizeof buf, "Fatal error: ");
+ va_start(arg, msg);
+ out = vseprint(out, buf+sizeof buf, msg, arg);
+ va_end(arg);
+ write(2, buf, out−buf);
+ exits("fatal error");
+ +
+ }
+ +
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/lib9/libfmt
+ +
+

SEE ALSO
+ +
+ + fmtinstall(3), fprintf(3), utf(7)
+ +
+

DIAGNOSTICS
+ +
+ + Routines that write to a file descriptor or call malloc set errstr.
+ +
+

BUGS
+ +
+ + The formatting is close to that specified for ANSI fprintf(3); + the main difference is that b and r are not in ANSI and u is a + flag here instead of a verb. Also, and distinctly not a bug, print + and friends generate UTF rather than ASCII. +
+ + There is no runeprint, runefprint, etc. because runes are byte-order + dependent and should not be written directly to a file; use the + UTF output of print or fprint instead. Also, sprint is deprecated + for safety reasons; use snprint, seprint, or smprint instead. + Safety also precludes the existence of runesprint. + +
+ +

 +
+
+ + +
+
+
+Space Glenda +
+
+ + -- cgit v1.2.3