Merge branch 'vendor/MPFR' into gcc441
[dragonfly.git] / usr.sbin / sa / sa.8
1 .\"
2 .\" Copyright (c) 1994 Christopher G. Demetriou
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\"    must display the following acknowledgement:
15 .\"      This product includes software developed by Christopher G. Demetriou.
16 .\" 3. The name of the author may not be used to endorse or promote products
17 .\"    derived from this software without specific prior written permission
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .\" $FreeBSD: src/usr.sbin/sa/sa.8,v 1.11.2.4 2003/03/11 22:31:33 trhodes Exp $
31 .\" $DragonFly: src/usr.sbin/sa/sa.8,v 1.4 2007/12/17 18:13:10 swildner Exp $
32 .\"
33 .Dd February 25, 1994
34 .Dt SA 8
35 .Os
36 .Sh NAME
37 .Nm sa
38 .Nd print system accounting statistics
39 .Sh SYNOPSIS
40 .Nm
41 .Op Fl abcdDfijkKlmnqrstu
42 .Op Fl v Ar cutoff
43 .Op Ar
44 .Sh DESCRIPTION
45 The
46 .Nm
47 utility reports on, cleans up,
48 and generally maintains system
49 accounting files.
50 .Pp
51 The
52 .Nm
53 utility is able to condense the information in
54 .Pa /var/account/acct
55 into the summary files
56 .Pa /var/account/savacct
57 and
58 .Pa /var/account/usracct ,
59 which contain system statistics according
60 to command name and login id, respectively.
61 This condensation is desirable because on a
62 large system,
63 .Pa /var/account/acct
64 can grow by hundreds of blocks per day.
65 The summary files are normally read before
66 the accounting file, so that reports include
67 all available information.
68 .Pp
69 If file names are supplied, they are read instead of
70 .Pa /var/account/acct .
71 After each file is read, if the summary
72 files are being updated, an updated summary will
73 be saved to disk.  Only one report is printed,
74 after the last file is processed.
75 .Pp
76 The labels used in the output indicate the following, except
77 where otherwise specified by individual options:
78 .Bl -tag -width ".Li k*sec"
79 .It Li avio
80 Average number of I/O operations per execution
81 .It Li cp
82 Sum of user and system time, in minutes
83 .It Li cpu
84 Same as
85 .Li cp
86 .It Li k
87 CPU-time averaged core usage, in 1k units
88 .It Li k*sec
89 CPU storage integral, in 1k-core seconds
90 .It Li re
91 Real time, in minutes
92 .It Li s
93 System time, in minutes
94 .It Li tio
95 Total number of I/O operations
96 .It Li u
97 User time, in minutes
98 .El
99 .Pp
100 The options to
101 .Nm
102 are:
103 .Bl -tag -width Ds
104 .It Fl a
105 List all command names, including those containing unprintable
106 characters and those used only once.  By default,
107 .Nm
108 places all names containing unprintable characters and
109 those used only once under the name ``***other''.
110 .It Fl b
111 If printing command statistics, sort output by the sum of user and system
112 time divided by number of calls.
113 .It Fl c
114 In addition to the number of calls and the user, system and real times
115 for each command, print their percentage of the total over all commands.
116 .It Fl d
117 If printing command statistics, sort by the average number of disk
118 I/O operations.  If printing user statistics, print the average number of
119 disk I/O operations per user.
120 .It Fl D
121 If printing command statistics, sort and print by the total number
122 of disk I/O operations.
123 .It Fl f
124 Force no interactive threshold comparison with the
125 .Fl v
126 option.
127 .It Fl i
128 Do not read in the summary files.
129 .It Fl j
130 Instead of the total minutes per category, give seconds per call.
131 .It Fl k
132 If printing command statistics, sort by the cpu-time average memory
133 usage.  If printing user statistics, print the cpu-time average
134 memory usage.
135 .It Fl K
136 If printing command statistics, print and sort by the cpu-storage integral.
137 .It Fl l
138 Separate system and user time; normally they are combined.
139 .It Fl m
140 Print per-user statistics rather than per-command statistics.
141 .It Fl n
142 Sort by number of calls.
143 .It Fl q
144 Create no output other than error messages.
145 .It Fl r
146 Reverse order of sort.
147 .It Fl s
148 Truncate the accounting files when done and merge their data
149 into the summary files.
150 .It Fl t
151 For each command, report the ratio of real time to the sum
152 of user and system cpu times.
153 If the cpu time is too small to report, ``*ignore*'' appears in
154 this field.
155 .It Fl u
156 Superseding all other flags, for each entry
157 in the accounting file, print the user ID, total seconds of cpu usage,
158 total memory usage, number of I/O operations performed, and
159 command name.
160 .It Fl v Ar cutoff
161 For each command used
162 .Ar cutoff
163 times or fewer, print the command name and await a reply
164 from the terminal.  If the reply begins with ``y'', add
165 the command to the category ``**junk**''.  This flag is
166 used to strip garbage from the report.
167 .El
168 .Pp
169 By default, per-command statistics will be printed.  The number of
170 calls, the total elapsed time in minutes, total cpu and user time
171 in minutes, average number of I/O operations, and CPU-time
172 averaged core usage will be printed.  If the
173 .Fl m
174 option is specified, per-user statistics will be printed, including
175 the user name, the number of commands invoked, total cpu time used
176 (in minutes), total number of I/O operations, and CPU storage integral
177 for each user.  If the
178 .Fl u
179 option is specified, the uid, user and system time (in seconds),
180 CPU storage integral, I/O usage, and command name will be printed
181 for each entry in the accounting data file.
182 .Pp
183 If the
184 .Fl u
185 flag is specified, all flags other than
186 .Fl q
187 are ignored.  If the
188 .Fl m
189 flag is specified, only the
190 .Fl b ,
191 .Fl d ,
192 .Fl i ,
193 .Fl k ,
194 .Fl q ,
195 and
196 .Fl s
197 flags are honored.
198 .Sh FILES
199 .Bl -tag -width /var/account/usracct -compact
200 .It Pa /var/account/acct
201 raw accounting data file
202 .It Pa /var/account/savacct
203 per-command accounting summary database
204 .It Pa /var/account/usracct
205 per-user accounting summary database
206 .El
207 .Sh EXIT STATUS
208 .Ex -std
209 .Sh SEE ALSO
210 .Xr lastcomm 1 ,
211 .Xr acct 5 ,
212 .Xr ac 8 ,
213 .Xr accton 8
214 .Sh AUTHORS
215 .An Chris G. Demetriou Aq cgd@postgres.berkeley.edu
216 .Sh CAVEATS
217 While the behavior of the options in this version of
218 .Nm
219 was modeled after the original version, there are some intentional
220 differences and undoubtedly some unintentional ones as well.  In
221 particular, the
222 .Fl q
223 option has been added, and the
224 .Fl m
225 option now understands more options than it used to.
226 .Pp
227 The formats of the summary files created by this version of
228 .Nm
229 are very different from the those used by the original version.
230 This is not considered a problem, however, because the accounting record
231 format has changed as well (since user ids are now 32 bits).
232 .Sh BUGS
233 The number of options to this program is absurd, especially considering
234 that there's not much logic behind their lettering.
235 .Pp
236 The field labels should be more consistent.
237 .Pp
238 The VM system does not record the CPU storage integral.