usr/src/lib/libast/common/man/fmt.3

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