.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
#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:
.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
.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)