ack/modules/src/print/print.3

.TH PRINT 3 "$Revision$"
.ad
.SH NAME
print, fprint, sprint, doprnt -- very simple formatted-output routines
.SH SYNOPSIS
.nf
.B #include <system.h>
.B #include <print.h>
.PP
.B void print(format [, arg] ... )
.B char *format;
.PP
.B void fprint(filep, format [, arg] ... )
.B File *filep;
.B char *format;
.PP
.B char *sprint(s, format [, arg] ... )
.B char *s, *format;
.PP
.B void doprnt(filep, format, args)
.B File *filep;
.B char *format;
.B va_list args;
.PP
.B int _format(buf, format, args)
.B char *buf;
.B char *format;
.B va_list args;
.fi
.SH DESCRIPTION
.I Print
writes output on standard output.
.I Fprint
and
.I doprnt
place output on the open file known by
.IR filep .
.I filep could for instance be STDOUT or STDERR.
.I Sprint
places `output' in the string
.IR s ,
followed by the character `\\0'.
.PP
Each of these functions converts, formats and prints its arguments, following
the 
.I format
argument, under control of
.IR format .
.I Format
is a character string which contains two types of objects: plain characters,
which are simply copied to the output destination, and conversion
specifications, each of which causes conversion and printing of the next
successive argument.
.PP
A conversion specification is introduced by the character %.
Following the %, there may be
.IP \(bu
an optional row of decimal digits specifying the field width;
if the converted integral value has fewer characters than
the field width, it will be blank-padded on the left;
if the field width begins with a zero, zero-padding will be done;
.IP \(bu
the character
.B l
specifying that a following 
.BR b ,
.BR d ,
.BR o ,
.B u
or
.B x
corresponds to a long-integer argument;
.IP \(bu
a character which indicates the type of conversion to be applied.
.LP
.PP
The conversion characters and their meanings are
.IP \fBbdox\fP
The next argument is an integer and is converted to binary, decimal, octal
or hexadecimal notation respectively.
.IP \fBc\fP
Next argument is a character and is put directly into the resulting string.
the field width is one character.
.IP \fBs\fP
Next argument is taken to be a character pointer and characters from the
string are taken until a null character is reached; a specified field width
is not taken into account.
.IP \fBu\fP
The unsigned integer argument is converted to decimal.
.LP
.PP
Integral arguments are not truncated, even if their size exceeds the specified
field width.
Padding takes place only if the specified field width exceeds the actual width.
.PP
The printing routines build the string to be printed internally and use
.I sys_write
to print it.
.PP
The
.I _format
routine builds the string, but does not null-terminate it. It returns the
length of the string.
.PP
.I Doprnt
takes
.I args
as the address of the arguments of the format string.
.SH FILES
.nf
~em/modules/lib/libprint.a
.fi
.SH MODULES
system(3), string(3)
.SH DIAGNOSTICS
.PP
Each illegal conversion specification is replaced by the string "<bad\ format>".
.SH BUGS
The maximum length of the string to be printed is 1024 characters.
.SH SEE ALSO
printf(3)