.fp 5 CW
.de Af
.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
..
.de aF
.ie \\$3 .ft \\$1
.el \{\
.ds ;G \&
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
.ft \\n(;G \}
..
.de L
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de LR
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de RL
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.de EX		\" start example
.ta 1i 2i 3i 4i 5i 6i
.PP
.RS 
.PD 0
.ft 5
.nf
..
.de EE		\" end example
.fi
.ft
.PD
.RE
.PP
..
.TH FMT 3
.SH NAME
fmt \- string formatting routines
.SH SYNOPSIS
.EX
#include <ast.h>
#include <ls.h>

char*      fmtbase(long \fInumber\fP, int \fIbase\fP, int \fIprefix\fP);
char*      fmtdev(struct stat* \fIst\fP);
char*      fmtelapsed(unsigned long \fIcount\fP, int \fIpersec\fP)
char*      fmterror(int \fIerrno\fP);
char*      fmtesc(const char* \fIstring\fP);
char*      fmtfs(struct stat* \fIst\fP);
char*      fmtgid(int \fIgid\fP);
char*      fmtmatch(const char* \fIre\fP);
char*      fmtmode(int \fImode\fP, int \fIexternal\fP);
char*      fmtperm(int \fIperm\fP);
char*      fmtre(const char* \fIpattern\fP);
char*      fmtsignal(int \fIsig\fP);
char*      fmttime(const char* \fIformat\fP, time_t \fItm\fP);
char*      fmtuid(int \fIuid\fP);
.EE
.SH DESCRIPTION
These routines return a pointer to a formatted string for various numeric
and string entities.
Some routines may cache information to speed up the next call.
Most of the routines return a pointer to a private buffer, the
contents of which are overwritten on the next call to that routine.
Most
.L fmt
routines have a corresponding
.L str
routine that converts in the other direction.
There is nothing spectacular about this collection other than that
it provides a single place where the exact format is spelled out.
.PP
.L fmtbase
formats a base
.I base
representation for
.IR number .
If
.I "prefix != 0"
then the base prefix is included in the formatted string.
If
.I "number == 0"
or
.I "base == 0"
then the output is signed base 10.
.PP
.L fmtdev
returns the device handle name specified by the
.L stat
structure
.IR st .
This is the device information displayed by
.IR "ls \-l" .
.PP
.L fmtelapsed
formats the elapsed time for
.I (count/persec)
seconds.
The two largest time units are used, limiting the return value length
to at most 6 characters.
The units are:
.RS
.TP
.B s
seconds
.TP
.B m
minutes
.TP
.B h
hours
.TP
.B days
.TP
.B weeks
.TP
.B M
months
.TP
.B Y
years
.TP
.B S
scores
.RE
.PP
.L fmterror
returns the system error message text for the error number
.IR errno .
.PP
.L fmtesc
formats non-ASCII characters in
.I string
into C-style
.B \e
sequences.
These sequences are understood by
.L chresc
and
.LR chrtoi .
.PP
.L fmtfs
returns the file system type name corresponding to the
.L stat
structure
.IR st .
.PP
.L fmtgid
returns the group name for
.IR gid .
.PP
.L fmtmatch
returns the
.L strmatch
equivalent pattern for the regular expression pattern
.IR re .
0 is returned for invalid
.IR re .
.PP
.L fmtmode
returns the
.I "ls \-l"
mode string for the file mode bits in
.IR mode .
If
.I "external != 0"
then 
.I mode
is
.IR modecanon (3)
canonical.
.PP
.L fmtperm
returns the
.I chmod
permission string for the permission bits in
.IR perm .
.PP
.L fmtre
returns the regular expression
equivalent pattern for the
.L strmatch
pattern
.IR pattern .
0 is returned for invalid
.IR pattern .
.PP
.L fmtsignal
returns the signal name, sans
.LR SIG ,
for the signal number 
.IR sig .
If
.I "sig < 0"
then the description text for
.I \-sig
is returned.
.PP
.L fmttime
returns the results of
.I "tmfmt(buf,sizeof(buf),format,tm)"
in the private buffer
.IR buf .
.PP
.L fmtuid
returns the user name for
.IR uid .
.SH "SEE ALSO"
modecanon(3),
str(3)