10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
462 lines
8.9 KiB
Groff
462 lines
8.9 KiB
Groff
.TH PRINT 3
|
|
.SH NAME
|
|
print, fprint, sprint, snprint, seprint, smprint, runesprint, runesnprint, runeseprint, runesmprint, vfprint, vsnprint, vseprint, vsmprint, runevsnprint, runevseprint, runevsmprint \- print formatted output
|
|
.SH SYNOPSIS
|
|
.B #include <u.h>
|
|
.PP
|
|
.B #include <libc.h>
|
|
.PP
|
|
.ta \w'\fLchar* 'u
|
|
.B
|
|
int print(char *format, ...)
|
|
.PP
|
|
.B
|
|
int fprint(int fd, char *format, ...)
|
|
.PP
|
|
.B
|
|
int sprint(char *s, char *format, ...)
|
|
.PP
|
|
.B
|
|
int snprint(char *s, int len, char *format, ...)
|
|
.PP
|
|
.B
|
|
char* seprint(char *s, char *e, char *format, ...)
|
|
.PP
|
|
.B
|
|
char* smprint(char *format, ...)
|
|
.PP
|
|
.B
|
|
int runesprint(Rune *s, char *format, ...)
|
|
.PP
|
|
.B
|
|
int runesnprint(Rune *s, int len, char *format, ...)
|
|
.PP
|
|
.B
|
|
Rune* runeseprint(Rune *s, Rune *e, char *format, ...)
|
|
.PP
|
|
.B
|
|
Rune* runesmprint(char *format, ...)
|
|
.PP
|
|
.B
|
|
int vfprint(int fd, char *format, va_list v)
|
|
.PP
|
|
.B
|
|
int vsnprint(char *s, int len, char *format, va_list v)
|
|
.PP
|
|
.B
|
|
char* vseprint(char *s, char *e, char *format, va_list v)
|
|
.PP
|
|
.B
|
|
char* vsmprint(char *format, va_list v)
|
|
.PP
|
|
.B
|
|
int runevsnprint(Rune *s, int len, char *format, va_list v)
|
|
.PP
|
|
.B
|
|
Rune* runevseprint(Rune *s, Rune *e, char *format, va_list v)
|
|
.PP
|
|
.B
|
|
Rune* runevsmprint(Rune *format, va_list v)
|
|
.PP
|
|
.B
|
|
.SH DESCRIPTION
|
|
.I Print
|
|
writes text to the standard output.
|
|
.I Fprint
|
|
writes to the named output
|
|
file descriptor:
|
|
a buffered form
|
|
is described in
|
|
.MR bio 3 .
|
|
.I Sprint
|
|
places text
|
|
followed by the NUL character
|
|
.RB ( \e0 )
|
|
in consecutive bytes starting at
|
|
.IR 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
|
|
.IR sprint ),
|
|
or
|
|
a negative value if an output error was encountered.
|
|
.PP
|
|
.I Snprint
|
|
is like
|
|
.IR sprint ,
|
|
but will not place more than
|
|
.I len
|
|
bytes in
|
|
.IR s .
|
|
Its result is always NUL-terminated and holds the maximal
|
|
number of complete UTF-8 characters that can fit.
|
|
.I Seprint
|
|
is like
|
|
.IR snprint ,
|
|
except that the end is indicated by a pointer
|
|
.I e
|
|
rather than a count and the return value points to the terminating NUL of the
|
|
resulting string.
|
|
.I Smprint
|
|
is like
|
|
.IR sprint ,
|
|
except that it prints into and returns a string of the required length, which is
|
|
allocated by
|
|
.MR malloc 3 .
|
|
.PP
|
|
The routines
|
|
.IR runesprint ,
|
|
.IR runesnprint ,
|
|
.IR runeseprint ,
|
|
and
|
|
.I runesmprint
|
|
are the same as
|
|
.IR sprint ,
|
|
.IR snprint ,
|
|
.IR seprint
|
|
and
|
|
.I smprint
|
|
except that their output is rune strings instead of byte strings.
|
|
They return a rune count rather than a byte count.
|
|
.PP
|
|
Finally, the routines
|
|
.IR vfprint ,
|
|
.IR vsnprint ,
|
|
.IR vseprint ,
|
|
.IR vsmprint ,
|
|
.IR runevsnprint ,
|
|
.IR runevseprint ,
|
|
and
|
|
.I runevsmprint
|
|
are like their
|
|
.BR v-less
|
|
relatives except they take as arguments a
|
|
.B va_list
|
|
parameter, so they can be called within a variadic function.
|
|
The Example section shows a representative usage.
|
|
.PP
|
|
Each of these functions
|
|
converts, formats, and prints its
|
|
trailing arguments
|
|
under control of a
|
|
.IR 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.
|
|
.PP
|
|
Each conversion specification has the following format:
|
|
.IP
|
|
.B "% [flags] verb
|
|
.PP
|
|
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
|
|
.IR width ,
|
|
the second
|
|
.IR precision .
|
|
A period can be used to separate them, and if the period is
|
|
present then
|
|
.I width
|
|
and
|
|
.I precision
|
|
are taken to be zero if missing, otherwise they are `omitted'.
|
|
Either or both of the numbers may be replaced with the character
|
|
.BR * ,
|
|
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
|
|
described below.
|
|
.PP
|
|
The numeric verbs
|
|
.BR d ,
|
|
.BR o ,
|
|
.BR b ,
|
|
.BR x ,
|
|
and
|
|
.B X
|
|
format their arguments in decimal,
|
|
octal, binary, hexadecimal, and upper case hexadecimal.
|
|
Each interprets the flags
|
|
.BR 0 ,
|
|
.BR h ,
|
|
.BR hh ,
|
|
.BR l ,
|
|
.BR u ,
|
|
.BR + ,
|
|
.BR - ,
|
|
.BR , ,
|
|
and
|
|
.B #
|
|
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
|
|
.BR + ,
|
|
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
|
|
.BR int .
|
|
If unsigned is specified,
|
|
then the argument is interpreted as a
|
|
positive number and no sign is output.
|
|
If two
|
|
.B l
|
|
flags are given,
|
|
then the argument is interpreted as a
|
|
.B vlong
|
|
(usually an 8-byte, sometimes a 4-byte integer).
|
|
If
|
|
.I precision
|
|
is not omitted, the number is padded on the left with zeros
|
|
until at least
|
|
.I precision
|
|
digits appear.
|
|
If
|
|
.I 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
|
|
.B o
|
|
conversion, the number is preceded by a
|
|
.B 0
|
|
if it doesn't already begin with one;
|
|
for
|
|
.B x
|
|
conversion, the number is preceded by
|
|
.BR 0x ;
|
|
for
|
|
.B X
|
|
conversion, the number is preceded by
|
|
.BR 0X .
|
|
Finally, if
|
|
.I 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
|
|
.I width
|
|
characters long.
|
|
.PP
|
|
The floating point verbs
|
|
.BR f ,
|
|
.BR e ,
|
|
.BR E ,
|
|
.BR g ,
|
|
and
|
|
.B G
|
|
take a
|
|
.B double
|
|
argument.
|
|
Each interprets the flags
|
|
.BR 0 ,
|
|
.BR L
|
|
.BR + ,
|
|
.BR - ,
|
|
and
|
|
.B #
|
|
to mean pad with zeros,
|
|
long double argument,
|
|
always print a sign,
|
|
left justified,
|
|
and
|
|
alternate format.
|
|
.I Width
|
|
is the minimum field width and,
|
|
if the converted value takes up less than
|
|
.I width
|
|
characters, it is padded on the left (or right, if `left justified')
|
|
with spaces.
|
|
.I Precision
|
|
is the number of digits that are converted after the decimal place for
|
|
.BR e ,
|
|
.BR E ,
|
|
and
|
|
.B f
|
|
conversions,
|
|
and
|
|
.I precision
|
|
is the maximum number of significant digits for
|
|
.B g
|
|
and
|
|
.B G
|
|
conversions.
|
|
The
|
|
.B f
|
|
verb produces output of the form
|
|
.RB [ - ] digits [ .digits\fR].
|
|
.B E
|
|
conversion appends an exponent
|
|
.BR E [ - ] digits ,
|
|
and
|
|
.B e
|
|
conversion appends an exponent
|
|
.BR e [ - ] digits .
|
|
The
|
|
.B g
|
|
verb will output the argument in either
|
|
.B e
|
|
or
|
|
.B 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
|
|
.B G
|
|
verb is similar, but uses
|
|
.B E
|
|
format instead of
|
|
.BR e .
|
|
When alternate format is specified, the result will always contain a decimal point,
|
|
and for
|
|
.B g
|
|
and
|
|
.B G
|
|
conversions, trailing zeros are not removed.
|
|
.PP
|
|
The
|
|
.B s
|
|
verb copies a NUL-terminated string
|
|
(pointer to
|
|
.BR char )
|
|
to the output.
|
|
The number of characters copied
|
|
.RI ( n )
|
|
is the minimum
|
|
of the size of the string and
|
|
.IR precision .
|
|
These
|
|
.I n
|
|
characters are justified within a field of
|
|
.I width
|
|
characters as described above.
|
|
If a
|
|
.I precision
|
|
is given, it is safe for the string not to be nul-terminated
|
|
as long as it is at least
|
|
.I precision
|
|
characters (not bytes!) long.
|
|
The
|
|
.B S
|
|
verb is similar, but it interprets its pointer as an array
|
|
of runes (see
|
|
.MR utf 7 );
|
|
the runes are converted to
|
|
.SM UTF
|
|
before output.
|
|
.PP
|
|
The
|
|
.B c
|
|
verb copies a single
|
|
.B char
|
|
(promoted to
|
|
.BR int )
|
|
justified within a field of
|
|
.I width
|
|
characters as described above.
|
|
The
|
|
.B C
|
|
verb is similar, but works on runes.
|
|
.PP
|
|
The
|
|
.B p
|
|
verb formats a pointer value.
|
|
At the moment, it is a synonym for
|
|
.BR x ,
|
|
but that will change if pointers and integers are different sizes.
|
|
.PP
|
|
The
|
|
.B r
|
|
verb takes no arguments; it copies the error string returned by a call to
|
|
.MR errstr 3 .
|
|
.PP
|
|
Custom verbs may be installed using
|
|
.MR fmtinstall 3 .
|
|
.SH EXAMPLE
|
|
This function prints an error message with a variable
|
|
number of arguments and then quits.
|
|
.IP
|
|
.EX
|
|
.ta 6n +6n +6n
|
|
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");
|
|
}
|
|
.EE
|
|
.SH SOURCE
|
|
.B \*9/src/lib9/fmt
|
|
.SH SEE ALSO
|
|
.MR fmtinstall 3 ,
|
|
.MR fprintf 3 ,
|
|
.MR utf 7
|
|
.SH DIAGNOSTICS
|
|
Routines that write to a file descriptor or call
|
|
.IR malloc
|
|
set
|
|
.IR errstr .
|
|
.SH BUGS
|
|
The formatting is close to that specified for ANSI
|
|
.MR fprintf 3 ;
|
|
the main difference is that
|
|
.B b
|
|
and
|
|
.B r
|
|
are not in ANSI and
|
|
.B u
|
|
is a flag here instead of a verb.
|
|
Also, and distinctly not a bug,
|
|
.I print
|
|
and friends generate
|
|
.SM UTF
|
|
rather than
|
|
.SM ASCII.
|
|
.PP
|
|
There is no
|
|
.IR runeprint ,
|
|
.IR runefprint ,
|
|
etc. because runes are byte-order dependent and should not be written directly to a file; use the
|
|
UTF output of
|
|
.I print
|
|
or
|
|
.I fprint
|
|
instead.
|
|
Also,
|
|
.I sprint
|
|
is deprecated for safety reasons; use
|
|
.IR snprint ,
|
|
.IR seprint ,
|
|
or
|
|
.I smprint
|
|
instead.
|
|
Safety also precludes the existence of
|
|
.IR runesprint .
|