print.3

.\"
.\" $Id: print.3,v 1.17 1995/07/04 18:24:52 schwartz Exp $ -*-nroff-*-
.\"
.TH PRINT 3
.SH NAME
print \- string formatting and printing library
.SH SYNOPSYS
.LP
.nf
.ft B
#include <print.h>
.ft
.fi
.LP
.nf
typedef struct Format Format;
typedef int (*Fmtconv)(Format *, int);

struct Format {
	// For the formatting routines.
	va_list args;
	long flags, f1, f2;
	Fmtconv *fmttab;
	// For the buffer maintainence routines.
	char *buf, *bufbegin, *bufend;
	int flushed;
	int (*grow)(Format *, size_t);
	int error;
	int reqlen;
	union {
		int n;
		void *p;
	} u;
	// For the sake of reentrancy.
	void *client_data;
};
.fi
.LP
.nf
int print (const char *fmt,...)
int eprint (const char *fmt,...)
int fprint (int fd, const char *fmt,...)
int vfprint (int fd, const char *fmt, va_list)
.fi
.LP
.nf
int sprint (char *buf, const char *fmt,...)
int snprint (char *buf, int buflen, const char *fmt,...)
int vsnprint (char *buf, int buflen, const char *fmt, va_list)
.fi
.LP
.nf
char *mprint (const char *fmt,...)
char *smprint (Alloc alloc, size_t *len, const char *fmt, ...)
char *vsmprint (Alloc alloc, size_t *len, const char *fmt, va_list)
char *palloc (char *p, size_t size)
.fi
.LP
.nf
Fmtconv fmtinstall (int c, Fmtconv f)
.fi
.LP
.nf
int fmtputc (Format *f, const char c)
int fmtappend (Format *format, const char *s, size_t len)
int fmtcat (Format *format, const char *s)
.fi
.LP
.nf
int fmtengine (Format *format, const char *fmt)
int fmtprint (Format *format, const char *fmt,...)
.fi
.SH SUMMARY
These routines format strings similarly to the printf family of
functions.  Unlike printf, they support user supplied format specifiers,
they can format into memory that is allocated as needed (using a user
supplied allocation function), they are reentrant (except for errno, the
global table of format specifiers, and possibly malloc if you choose to
use it), and they are 8 bit clean ('\\0' bytes can be printed).
Print is also space efficient.  The program text is about 5K
when compiled for a sparc.

.B fprint
writes formatted text to a file descriptor
and returns the number of bytes written, or -1 on error.
.B print
writes text to stdout
while
.B eprint
writes text to stderr.
.B vfprint
formats arguments supplied in a
.I va_list
obtained from
.B stdargs.

.B sprint
writes text into a user supplied buffer.  It writes at most
FMT_SPRINT_BUFSIZ bytes including the terminating '\\0'.  It returns
the number of bytes requested
(not including the terminating '\\0').  Note that one must
check for truncation by comparing this value to the
size of the buffer.
.B snprint
writes at most
.I n
bytes into a user supplied buffer.
.B vsnprint
does the same, but takes its  arguments from a
.I va_list.

.B mprint
formats into a dynamically allocated buffer, to which it returns
a pointer.
The space is obtained
from
.B malloc
and should be freed when no longer needed.
.B smprint
takes a user supplied allocation function as an argument.  This
function should behave as ANSI-\fBrealloc\fP
does.  Some pre-ANSI systems' realloc fails to treat
realloc(0,\fIn\fP)
as equivalent to
malloc(\fIn\fP),
so we provide a routine
.B palloc
which does.
smprint also returns the number of bytes generated by writing
into the *len argument if it is a non-null pointer.
.B vsmprint
is like smprint, but that it reads arguments from a va_list.

.B fmtinstall
installs a user supplied conversion function for a given character,
and returns the old value.  A conversion function takes a pointer
to a format structure and the character that induced the call.
It must return FMT_flag if the format character signals
setting a flag and FMT_verb if it signals performing a conversion.

A conversion function can use
.B fmtappend
to put new text into the output buffer;
.B fmtputc
and
.B fmtcat
are supplied for convenience.

.B fmtengine
is the entry point for the actual formatting engine.  Given a properly
initialized format structure and a format string, it will do the
specified work.

.B fmtprint
is a very general interface to
.B fmtengine.
Its arguments are a properly initialized format structure, a format
string, and a matching number of parameters.
.B fmtprint
saves and restores the argument list stored in the format structure, so
it can be used inside a conversion function to perform arbitrary
formatting operations.  This usage avoids the temporary buffers
that
.B fmtappend
would require.
.B fmtengine
and
.B fmtprint
return the number of characters that they generated.

.LP
The format structure contains three kinds of information.
First, variables used by the formatting routines.
These are:
.I args,
the argument list containing the data to be formatted.
.I flags,
a bitmask storing the flags set at the time each conversion
function is called.  Possible values are given in print.h.
.I "f1, f2"
are the field width and precision of each conversion.
The flags, f1, and f2 are zeroed before each conversion begins.
.I "fmttab"
is a pointer to the per-format array of conversion functions, indexed
by conversion character.  If it is
zero, the global table will be used instead.

Second, variables used for buffer maintainance:
These are:
.I buf,
.I bufbegin,
.I bufend,
pointers to the insertion point in the output buffer,
the buffer itself, and the end of the buffer.
.I flushed,
the number of characters that have been transmitted to their
ultimate destination thus far.
.I grow,
the buffer growing function, called when the buffer is nearly full
so that it can be flushed or reallocated.
.I error,
nonzero if an error has occurred during formatting.
Formatting will stop after the first error is noticed.
.I u.n,
.I u.p,
the name of the file descriptor to write to, or the
realloc function to call to resize a buffer.

Finally,
.I client_data
provides access to other arguments
in a reentrant way.

.LP
A simple format function, the one for  %c, looks like this:

.nf
static int cconv(Format *format, int c) {
    fmtputc(format, va_arg(format->args, int));
    return FMT_verb;
}
.fi
.LP
A more interesting example is a conversion function that formats
a string with all unprintable characters quoted as in C.

.nf
int print_cquote_conv (Format *format, int c)
{
    unsigned char *s = va_arg (format->args, unsigned char*);
    unsigned char ch;

    while ((ch = *s++)) {
	if (isascii (ch) && isalnum (ch)) {
	    if (ch == '\\\\')
		fmtputc (format, ch);
	    fmtputc (format, ch);
	} else {
	    fmtprint (format, "\\\\%03uo", ch);
	}
    }
    return FMT_verb;
}
.fi


.SH STANDARD CONVERSIONS
.SS verbs
.LP
.PD 0
.TP 10
.B %
A literal percent.
.TP
.B s
A string.  With the # flag, use f2 for size and don't assume '\\0' termination.
.TP
.B c
A single character.
.TP
.B "d, i"
A decimal integer.
.TP
.B o
An octal integer. With #, prefix 0.
.TP
.B x
A hex integer. With #, prefix 0x.
.TP
.B "e, f, g"
Floating point conversions (not implemented).
.TP
.B "r, m"
sys_errlist[errno].  With # flag, errno.
.TP
.B "n"
writes the number of characters emitted thus far into into an
int *argument.  Note!  Since transput stops if an error occurs,
this verb may not be executed.
.PD
.SS flags
.PD 0
.TP 10
.B u
Arg is unsigned.
.TP
.B h
Arg is short.
.TP
.B l
Arg is long.
.TP
.B q
Arg is quad (not implemented).
.TP
.B #
Select alternate output format.
.TP
.B -
Left justify output.
.TP
.B 0
Zero pad output.
.TP
.B 1-9
Set the f1 (field width) specifier.
.TP
.B .
The f2 (precision) specifier follows.
.TP
.B *
Set f1 or f2 from int arg.
.PD
.LP

.SH OPTIONAL CONVERSIONS
Calling
.I fmt_install_runeconv()
installs conversion functions which support Unicode 16 bit "Runes"
by transforming them to the UTF-8 multibyte encoding.
The %C operator transforms a single Rune, while %S transforms
a 0 terminated array, analagously to %c and %s.

.SH NOTES
Unlike printf, flags like 'u' need to be followed by a verb like 'd'.

This code is derived from the print routines  that Paul Haahr wrote for
Byron Rakitzis' implementation of
.I rc.

.SH AUTHORS
.LP
libprint:
Paul Haahr,
Byron Rakitzis,
Scott Schwartz.
.LP
runes:
Rob Pike, Howard Trickey
.LP
runeconv:
Erik Quanstrom

.SH BUGS
.LP
What to do when an invalid print char is detected?  BSD printf emits
the character without comment.  We print a warning to stderr and stop
formatting.
.LP
What should snprint return?
.LP
The namespace
for installable format specifiers
is very small, so collisions and mistakes will probably cause trouble.
.LP
No floating point conversion functions (%e, %f, %g) yet.
.LP
Quadword conversions (%qd) would be nice too.
.LP
Does %d really work in boundary cases (signed/unsigned long/int/short
maxint, minint)?
.LP
What should snprint return?  Number of bytes requested, or transferred?
.LP
fmtputc still feels kludgy.  It used to directly write bytes into
the buffer, in an attempt at efficiency, but that turned out to
complicate snprint. Now it just calls fmtappend.

.SH COPYRIGHT
All files in this library except rune.c and rune.h are
covered by the following copyright notice:

.RS
.ps -2
.\" ---------- ---------- ---------- ----------
Copyright 1994 Paul Haahr, Scott Schwartz, Byron Rakitzis.
All rights reserved.

This software is not subject to any license of the American Telephone
and Telegraph Company or of the Regents of the University of California.

Permission is granted to anyone to use this software for any purpose on
any computer system, and to alter it and redistribute it freely, subject
to the following restrictions:

1. The author is not responsible for the consequences of use of this
software, no matter how awful, even if they arise from flaws in it.

2. The origin of this software must not be misrepresented, either by
explicit claim or by omission.  Since few users ever read sources,
credits must appear in the documentation.

3. Altered versions must be plainly marked as such, and must not be
misrepresented as being the original software.  Since few users
ever read sources, credits must appear in the documentation.

4. This notice may not be removed or altered.

[this copyright notice is adapted from Henry Spencer's
"awf" copyright notice.]
.\" ---------- ---------- ---------- ----------
.ps
.RE

The files rune.c and rune.h, originally distributed
as part of the sam editor, are covered by
the following copyright notice:

.RS
.ps -2
.\" ---------- ---------- ---------- ----------
The authors of this software are Rob Pike and Howard Trickey.
Copyright (c) 1992 by AT&T.
Permission to use, copy, modify, and distribute this software for any
purpose without fee is hereby granted, provided that this entire notice
is included in all copies of any software which is or includes a copy
or modification of this software and in all copies of the supporting
documentation for such software.
THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
WARRANTY.  IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T MAKE ANY
REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.
.\" ---------- ---------- ---------- ----------
.ps
.RE