diff options
Diffstat (limited to 'man/man3/print.html')
| -rw-r--r-- | man/man3/print.html | 309 |
1 files changed, 0 insertions, 309 deletions
diff --git a/man/man3/print.html b/man/man3/print.html deleted file mode 100644 index 8640efc7..00000000 --- a/man/man3/print.html +++ /dev/null @@ -1,309 +0,0 @@ -<head> -<title>print(3) - Plan 9 from User Space</title> -<meta content="text/html; charset=utf-8" http-equiv=Content-Type> -</head> -<body bgcolor=#ffffff> -<table border=0 cellpadding=0 cellspacing=0 width=100%> -<tr height=10><td> -<tr><td width=20><td> -<tr><td width=20><td><b>PRINT(3)</b><td align=right><b>PRINT(3)</b> -<tr><td width=20><td colspan=2> - <br> -<p><font size=+1><b>NAME </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - print, fprint, sprint, snprint, seprint, smprint, runesprint, - runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, - vsmprint, runevsnprint, runevseprint, runevsmprint – print formatted - output<br> - -</table> -<p><font size=+1><b>SYNOPSIS </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <tt><font size=+1>#include <u.h> - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>#include <libc.h> - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int print(char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int fprint(int fd, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int sprint(char *s, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int snprint(char *s, int len, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>char* seprint(char *s, char *e, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>char* smprint(char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int runesprint(Rune *s, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int runesnprint(Rune *s, int len, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>Rune* runeseprint(Rune *s, Rune *e, char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>Rune* runesmprint(char *format, ...) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int vfprint(int fd, char *format, va_list v) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int vsnprint(char *s, int len, char *format, va_list v) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>char* vseprint(char *s, char *e, char *format, va_list v) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>char* vsmprint(char *format, va_list v) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>int runevsnprint(Rune *s, int len, char *format, va_list v) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v) - - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - <tt><font size=+1>Rune* runevsmprint(Rune *format, va_list v) - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - -</table> -<p><font size=+1><b>DESCRIPTION </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <i>Print</i> writes text to the standard output. <i>Fprint</i> writes to the - named output file descriptor: a buffered form is described in - <a href="../man3/bio.html"><i>bio</i>(3)</a>. <i>Sprint</i> places text followed by the NUL character (<tt><font size=+1>\0</font></tt>) - in consecutive bytes starting at <i>s</i>; 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 <i>sprint</i>), or a negative value if an output error was encountered. - - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - <i>Snprint</i> is like <i>sprint</i>, but will not place more than <i>len</i> bytes - in <i>s</i>. Its result is always NUL-terminated and holds the maximal - number of complete UTF-8 characters that can fit. <i>Seprint</i> is like - <i>snprint</i>, except that the end is indicated by a pointer <i>e</i> rather - than a count and the return value points to the terminating NUL - of - the resulting string. <i>Smprint</i> is like <i>sprint</i>, except that it prints - into and returns a string of the required length, which is allocated - by <a href="../man3/malloc.html"><i>malloc</i>(3)</a>. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The routines <i>runesprint</i>, <i>runesnprint</i>, <i>runeseprint</i>, and <i>runesmprint</i> - are the same as <i>sprint</i>, <i>snprint</i>, <i>seprint</i> and <i>smprint</i> except that - their output is rune strings instead of byte strings. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - Finally, the routines <i>vfprint</i>, <i>vsnprint</i>, <i>vseprint</i>, <i>vsmprint</i>, <i>runevsnprint</i>, - <i>runevseprint</i>, and <i>runevsmprint</i> are like their <tt><font size=+1>v−less</font></tt> relatives - except they take as arguments a <tt><font size=+1>va_list</font></tt> parameter, so they can - be called within a variadic function. The Example section shows - a representative usage. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - Each of these functions converts, formats, and prints its trailing - arguments under control of a <i>format</i> 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. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - Each conversion specification has the following format:<br> - - <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <tt><font size=+1>% [flags] verb - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - </font></tt> - - </table> - 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 <i>width</i>, the second <i>precision</i>. A period - can be used to separate them, and if the period is present then - <i>width</i> and <i>precision</i> are taken to be zero if missing, otherwise - they are ‘omitted’. Either or both of the numbers may be replaced - with the character <tt><font size=+1>*</font></tt>, meaning that the actual number will be obtained - from the argument list as an integer. The flags and numbers are - arguments to the <i>verb</i> described below. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The numeric verbs <tt><font size=+1>d</font></tt>, <tt><font size=+1>o</font></tt>, <tt><font size=+1>b</font></tt>, <tt><font size=+1>x</font></tt>, and <tt><font size=+1>X</font></tt> format their arguments in - decimal, octal, binary, hexadecimal, and upper case hexadecimal. - Each interprets the flags <tt><font size=+1>0</font></tt>, <tt><font size=+1>h</font></tt>, <tt><font size=+1>hh</font></tt>, <tt><font size=+1>l</font></tt>, <tt><font size=+1>u</font></tt>, <tt><font size=+1>+</font></tt>, <tt><font size=+1>−</font></tt>, <tt><font size=+1>,</font></tt>, and <tt><font size=+1>#</font></tt> 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 <tt><font size=+1>+</font></tt>, 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 <tt><font size=+1>int</font></tt>. If unsigned - is specified, then the argument is interpreted as a positive number - and no sign is output. If two <tt><font size=+1>l</font></tt> flags are given, then - the argument is interpreted as a <tt><font size=+1>vlong</font></tt> (usually an 8-byte, sometimes - a 4-byte integer). If <i>precision</i> is not omitted, the number is - padded on the left with zeros until at least <i>precision</i> digits - appear. If <i>precision</i> 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 <tt><font size=+1>o</font></tt> conversion, the number - is preceded by a <tt><font size=+1>0</font></tt> if it doesn’t already begin with one; for <tt><font size=+1>x</font></tt> - conversion, the number is preceded by <tt><font size=+1>0x</font></tt>; for <tt><font size=+1>X</font></tt> conversion, the - number is preceded by <tt><font size=+1>0X</font></tt>. Finally, if <i>width</i> 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 <i>width</i> characters - long. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The floating point verbs <tt><font size=+1>f</font></tt>, <tt><font size=+1>e</font></tt>, <tt><font size=+1>E</font></tt>, <tt><font size=+1>g</font></tt>, and <tt><font size=+1>G</font></tt> take a <tt><font size=+1>double</font></tt> argument. - Each interprets the flags <tt><font size=+1>0</font></tt>, <tt><font size=+1>L +</font></tt>, <tt><font size=+1>−</font></tt>, and <tt><font size=+1>#</font></tt> to mean pad with zeros, - long double argument, always print a sign, left justified, and - alternate format. <i>Width</i> is the minimum field width and, if the - converted value takes up less than <i>width</i> characters, it is - padded on the left (or right, if ‘left justified’) with spaces. - <i>Precision</i> is the number of digits that are converted after the - decimal place for <tt><font size=+1>e</font></tt>, <tt><font size=+1>E</font></tt>, and <tt><font size=+1>f</font></tt> conversions, and <i>precision</i> is the - maximum number of significant digits for <tt><font size=+1>g</font></tt> and <tt><font size=+1>G</font></tt> conversions. - The <tt><font size=+1>f</font></tt> verb produces output of the form [<tt><font size=+1>−</font></tt>]<tt><font size=+1>digits</font></tt>[<tt><font size=+1>.digits</font></tt>]. <tt><font size=+1>E - </font></tt>conversion appends an exponent <tt><font size=+1>E</font></tt>[<tt><font size=+1>−</font></tt>]<tt><font size=+1>digits</font></tt>, and <tt><font size=+1>e</font></tt> conversion appends - an exponent <tt><font size=+1>e</font></tt>[<tt><font size=+1>−</font></tt>]<tt><font size=+1>digits</font></tt>. The <tt><font size=+1>g</font></tt> verb will output the argument in - either <tt><font size=+1>e</font></tt> or <tt><font size=+1>f</font></tt> 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 <tt><font size=+1>G</font></tt> verb is similar, but uses <tt><font size=+1>E</font></tt> format - instead of <tt><font size=+1>e</font></tt>. When alternate format is specified, the result will - always contain a decimal point, and for <tt><font size=+1>g</font></tt> and <tt><font size=+1>G</font></tt> conversions, trailing - zeros are not removed. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The <tt><font size=+1>s</font></tt> verb copies a NUL-terminated string (pointer to <tt><font size=+1>char</font></tt>) to - the output. The number of characters copied (<i>n</i>) is the minimum - of the size of the string and <i>precision</i>. These <i>n</i> characters are - justified within a field of <i>width</i> characters as described above. - If a <i>precision</i> is given, it is safe for the string not to be nul- - terminated as long as it is at least <i>precision</i> characters (not - bytes!) long. The <tt><font size=+1>S</font></tt> verb is similar, but it interprets its pointer - as an array of runes (see <a href="../man7/utf.html"><i>utf</i>(7)</a>); the runes are converted to - UTF before output. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The <tt><font size=+1>c</font></tt> verb copies a single <tt><font size=+1>char</font></tt> (promoted to <tt><font size=+1>int</font></tt>) justified within - a field of <i>width</i> characters as described above. The <tt><font size=+1>C</font></tt> verb is - similar, but works on runes. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The <tt><font size=+1>p</font></tt> verb formats a pointer value. At the moment, it is a synonym - for <tt><font size=+1>x</font></tt>, but that will change if pointers and integers are different - sizes. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - The <tt><font size=+1>r</font></tt> verb takes no arguments; it copies the error string returned - by a call to <a href="../man3/errstr.html"><i>errstr</i>(3)</a>. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - Custom verbs may be installed using <a href="../man3/fmtinstall.html"><i>fmtinstall</i>(3)</a>.<br> - -</table> -<p><font size=+1><b>EXAMPLE </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - This function prints an error message with a variable number of - arguments and then quits.<br> - - <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <tt><font size=+1>void fatal(char *msg, ...)<br> - {<br> - - <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - char buf[1024], *out;<br> - va_list arg;<br> - out = seprint(buf, buf+sizeof buf, "Fatal error: ");<br> - va_start(arg, msg);<br> - out = vseprint(out, buf+sizeof buf, msg, arg);<br> - va_end(arg);<br> - write(2, buf, out−buf);<br> - exits("fatal error");<br> - - </table> - }<br> - </font></tt> - </table> - -</table> -<p><font size=+1><b>SOURCE </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <tt><font size=+1>/usr/local/plan9/src/lib9/libfmt<br> - </font></tt> -</table> -<p><font size=+1><b>SEE ALSO </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - <a href="../man3/fmtinstall.html"><i>fmtinstall</i>(3)</a>, <a href="../man3/fprintf.html"><i>fprintf</i>(3)</a>, <a href="../man7/utf.html"><i>utf</i>(7)</a><br> - -</table> -<p><font size=+1><b>DIAGNOSTICS </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - Routines that write to a file descriptor or call <i>malloc</i> set <i>errstr</i>.<br> - -</table> -<p><font size=+1><b>BUGS </b></font><br> - -<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> - - The formatting is close to that specified for ANSI <a href="../man3/fprintf.html"><i>fprintf</i>(3)</a>; - the main difference is that <tt><font size=+1>b</font></tt> and <tt><font size=+1>r</font></tt> are not in ANSI and <tt><font size=+1>u</font></tt> is a - flag here instead of a verb. Also, and distinctly not a bug, <i>print</i> - and friends generate UTF rather than ASCII. - <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> - - There is no <i>runeprint</i>, <i>runefprint</i>, etc. because runes are byte-order - dependent and should not be written directly to a file; use the - UTF output of <i>print</i> or <i>fprint</i> instead. Also, <i>sprint</i> is deprecated - for safety reasons; use <i>snprint</i>, <i>seprint</i>, or <i>smprint</i> instead. - Safety also precludes the existence of <i>runesprint</i>. - -</table> - -<td width=20> -<tr height=20><td> -</table> -<!-- TRAILER --> -<table border=0 cellpadding=0 cellspacing=0 width=100%> -<tr height=15><td width=10><td><td width=10> -<tr><td><td> -<center> -<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> -</center> -</table> -<!-- TRAILER --> -</body></html> |