1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
.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)
|
