1.fp 5 CW
2.de Af
3.ds ;G \\*(;G\\f\\$1\\$3\\f\\$2
4.if !\\$4 .Af \\$2 \\$1 "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
5..
6.de aF
7.ie \\$3 .ft \\$1
8.el \{\
9.ds ;G \&
10.nr ;G \\n(.f
11.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
12\\*(;G
13.ft \\n(;G \}
14..
15.de L
16.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
17..
18.de LR
19.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
20..
21.de RL
22.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
23..
24.de EX		\" start example
25.ta 1i 2i 3i 4i 5i 6i
26.PP
27.RS 
28.PD 0
29.ft 5
30.nf
31..
32.de EE		\" end example
33.fi
34.ft
35.PD
36.RE
37.PP
38..
39.TH FMT 3
40.SH NAME
41fmt \- string formatting routines
42.SH SYNOPSIS
43.EX
44#include <ast.h>
45#include <ls.h>
46
47char*      fmtbase(long \fInumber\fP, int \fIbase\fP, int \fIprefix\fP);
48char*      fmtdev(struct stat* \fIst\fP);
49char*      fmtelapsed(unsigned long \fIcount\fP, int \fIpersec\fP)
50char*      fmterror(int \fIerrno\fP);
51char*      fmtesc(const char* \fIstring\fP);
52char*      fmtfs(struct stat* \fIst\fP);
53char*      fmtgid(int \fIgid\fP);
54char*      fmtmatch(const char* \fIre\fP);
55char*      fmtmode(int \fImode\fP, int \fIexternal\fP);
56char*      fmtperm(int \fIperm\fP);
57char*      fmtre(const char* \fIpattern\fP);
58char*      fmtsignal(int \fIsig\fP);
59char*      fmttime(const char* \fIformat\fP, time_t \fItm\fP);
60char*      fmtuid(int \fIuid\fP);
61.EE
62.SH DESCRIPTION
63These routines return a pointer to a formatted string for various numeric
64and string entities.
65Some routines may cache information to speed up the next call.
66Most of the routines return a pointer to a private buffer, the
67contents of which are overwritten on the next call to that routine.
68Most
69.L fmt
70routines have a corresponding
71.L str
72routine that converts in the other direction.
73There is nothing spectacular about this collection other than that
74it provides a single place where the exact format is spelled out.
75.PP
76.L fmtbase
77formats a base
78.I base
79representation for
80.IR number .
81If
82.I "prefix != 0"
83then the base prefix is included in the formatted string.
84If
85.I "number == 0"
86or
87.I "base == 0"
88then the output is signed base 10.
89.PP
90.L fmtdev
91returns the device handle name specified by the
92.L stat
93structure
94.IR st .
95This is the device information displayed by
96.IR "ls \-l" .
97.PP
98.L fmtelapsed
99formats the elapsed time for
100.I (count/persec)
101seconds.
102The two largest time units are used, limiting the return value length
103to at most 6 characters.
104The units are:
105.RS
106.TP
107.B s
108seconds
109.TP
110.B m
111minutes
112.TP
113.B h
114hours
115.TP
116.B days
117.TP
118.B weeks
119.TP
120.B M
121months
122.TP
123.B Y
124years
125.TP
126.B S
127scores
128.RE
129.PP
130.L fmterror
131returns the system error message text for the error number
132.IR errno .
133.PP
134.L fmtesc
135formats non-ASCII characters in
136.I string
137into C-style
138.B \e
139sequences.
140These sequences are understood by
141.L chresc
142and
143.LR chrtoi .
144.PP
145.L fmtfs
146returns the file system type name corresponding to the
147.L stat
148structure
149.IR st .
150.PP
151.L fmtgid
152returns the group name for
153.IR gid .
154.PP
155.L fmtmatch
156returns the
157.L strmatch
158equivalent pattern for the regular expression pattern
159.IR re .
1600 is returned for invalid
161.IR re .
162.PP
163.L fmtmode
164returns the
165.I "ls \-l"
166mode string for the file mode bits in
167.IR mode .
168If
169.I "external != 0"
170then 
171.I mode
172is
173.IR modecanon (3)
174canonical.
175.PP
176.L fmtperm
177returns the
178.I chmod
179permission string for the permission bits in
180.IR perm .
181.PP
182.L fmtre
183returns the regular expression
184equivalent pattern for the
185.L strmatch
186pattern
187.IR pattern .
1880 is returned for invalid
189.IR pattern .
190.PP
191.L fmtsignal
192returns the signal name, sans
193.LR SIG ,
194for the signal number 
195.IR sig .
196If
197.I "sig < 0"
198then the description text for
199.I \-sig
200is returned.
201.PP
202.L fmttime
203returns the results of
204.I "tmfmt(buf,sizeof(buf),format,tm)"
205in the private buffer
206.IR buf .
207.PP
208.L fmtuid
209returns the user name for
210.IR uid .
211.SH "SEE ALSO"
212modecanon(3),
213str(3)
214