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