.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.\" $FreeBSD: src/usr.sbin/sa/sa.8,v 1.15 2002/07/14 14:46:01 charnier Exp $
+.\" $FreeBSD: src/usr.sbin/sa/sa.8,v 1.20 2007/05/18 12:36:10 dds Exp $
.\"
-.Dd February 25, 1994
+.Dd May 18, 2007
.Dt SA 8
.Os
.Sh NAME
.Nm sa
.Nd print system accounting statistics
.Sh SYNOPSIS
-.Nm sa
+.Nm
.Op Fl abcdDfijkKlmnqrstu
+.Op Fl P Ar file
+.Op Fl U Ar file
.Op Fl v Ar cutoff
.Op Ar
.Sh DESCRIPTION
The
-.Nm sa
+.Nm
utility reports on, cleans up,
and generally maintains system
accounting files.
.Pp
The
-.Nm sa
+.Nm
utility is able to condense the information in
.Pa /var/account/acct
into the summary files
.Pa /var/account/acct .
After each file is read, if the summary
files are being updated, an updated summary will
-be saved to disk. Only one report is printed,
+be saved to disk.
+Only one report is printed,
after the last file is processed.
.Pp
The labels used in the output indicate the following, except
where otherwise specified by individual options:
.Bl -tag -width k*sec
-.\" ==========
.It Dv avio
Average number of I/O operations per execution
-.\" ==========
.It Dv cp
Sum of user and system time, in minutes
-.\" ==========
.It Dv cpu
Same as
.Dv cp
-.\" ==========
.It Dv k
CPU-time averaged core usage, in 1k units
-.\" ==========
.It Dv k*sec
CPU storage integral, in 1k-core seconds
-.\" ==========
.It Dv re
Real time, in minutes
-.\" ==========
.It Dv s
System time, in minutes
-.\" ==========
.It Dv tio
Total number of I/O operations
-.\" ==========
.It Dv u
User time, in minutes
.El
.Pp
The options to
-.Nm sa
+.Nm
are:
.Bl -tag -width Ds
-.\" ==========
.It Fl a
List all command names, including those containing unprintable
-characters and those used only once. By default,
-.Nm sa
+characters and those used only once.
+By default,
+.Nm
places all names containing unprintable characters and
those used only once under the name ``***other''.
-.\" ==========
.It Fl b
If printing command statistics, sort output by the sum of user and system
time divided by number of calls.
-.\" ==========
.It Fl c
In addition to the number of calls and the user, system and real times
for each command, print their percentage of the total over all commands.
-.\" ==========
-.It Fl D
-If printing command statistics, sort and print by the total number
-of disk I/O operations.
-.\" ==========
.It Fl d
If printing command statistics, sort by the average number of disk
-I/O operations. If printing user statistics, print the average number of
+I/O operations.
+If printing user statistics, print the average number of
disk I/O operations per user.
-.\" ==========
+.It Fl D
+If printing command statistics, sort and print by the total number
+of disk I/O operations.
.It Fl f
Force no interactive threshold comparison with the
.Fl v
option.
-.\" ==========
.It Fl i
Do not read in the summary files.
-.\" ==========
.It Fl j
Instead of the total minutes per category, give seconds per call.
-.\" ==========
-.It Fl K
-If printing command statistics, print and sort by the cpu-storage integral.
-.\" ==========
.It Fl k
If printing command statistics, sort by the cpu-time average memory
-usage. If printing user statistics, print the cpu-time average
+usage.
+If printing user statistics, print the cpu-time average
memory usage.
-.\" ==========
+.It Fl K
+If printing command statistics, print and sort by the cpu-storage integral.
.It Fl l
Separate system and user time; normally they are combined.
-.\" ==========
.It Fl m
Print per-user statistics rather than per-command statistics.
-.\" ==========
.It Fl n
Sort by number of calls.
-.\" ==========
+.It Fl P Ar file
+Use the specified
+.Ar file
+for accessing the per-command accounting summary database,
+instead of the default
+.Pa /var/account/savacct .
.It Fl q
Create no output other than error messages.
-.\" ==========
.It Fl r
Reverse order of sort.
-.\" ==========
.It Fl s
Truncate the accounting files when done and merge their data
into the summary files.
-.\" ==========
.It Fl t
For each command, report the ratio of real time to the sum
of user and system cpu times.
If the cpu time is too small to report, ``*ignore*'' appears in
this field.
-.\" ==========
+.It Fl U Ar file
+Use the specified
+.Ar file
+for accessing the per-user accounting summary database,
+instead of the default
+.Pa /var/account/usracct .
.It Fl u
Superseding all other flags, for each entry
in the accounting file, print the user ID, total seconds of cpu usage,
total memory usage, number of I/O operations performed, and
command name.
-.\" ==========
.It Fl v Ar cutoff
For each command used
.Ar cutoff
times or fewer, print the command name and await a reply
-from the terminal. If the reply begins with ``y'', add
-the command to the category ``**junk**''. This flag is
+from the terminal.
+If the reply begins with ``y'', add
+the command to the category ``**junk**''.
+This flag is
used to strip garbage from the report.
.El
.Pp
-By default, per-command statistics will be printed. The number of
+By default, per-command statistics will be printed.
+The number of
calls, the total elapsed time in minutes, total cpu and user time
in minutes, average number of I/O operations, and CPU-time
-averaged core usage will be printed. If the
+averaged core usage will be printed.
+If the
.Fl m
option is specified, per-user statistics will be printed, including
the user name, the number of commands invoked, total cpu time used
(in minutes), total number of I/O operations, and CPU storage integral
-for each user. If the
+for each user.
+If the
.Fl u
option is specified, the uid, user and system time (in seconds),
CPU storage integral, I/O usage, and command name will be printed
.Fl u
flag is specified, all flags other than
.Fl q
-are ignored. If the
+are ignored.
+If the
.Fl m
flag is specified, only the
.Fl b ,
and
.Fl s
flags are honored.
-.Sh DIAGNOSTICS
-.Ex -std
.Sh FILES
.Bl -tag -width /var/account/usracct -compact
.It Pa /var/account/acct
.It Pa /var/account/usracct
per-user accounting summary database
.El
+.Sh EXIT STATUS
+.Ex -std
.Sh SEE ALSO
.Xr lastcomm 1 ,
.Xr acct 5 ,
.Xr ac 8 ,
.Xr accton 8
-.Sh BUGS
-The number of options to this program is absurd, especially considering
-that there's not much logic behind their lettering.
-.Pp
-The field labels should be more consistent.
-.Pp
-The VM system does not record the CPU storage integral.
.Sh CAVEATS
While the behavior of the options in this version of
-.Nm sa
+.Nm
was modeled after the original version, there are some intentional
-differences and undoubtedly some unintentional ones as well. In
+differences and undoubtedly some unintentional ones as well.
+In
particular, the
.Fl q
option has been added, and the
option now understands more options than it used to.
.Pp
The formats of the summary files created by this version of
-.Nm sa
+.Nm
are very different from the those used by the original version.
This is not considered a problem, however, because the accounting record
format has changed as well (since user ids are now 32 bits).
.Sh AUTHORS
.An Chris G. Demetriou Aq cgd@postgres.berkeley.edu
+.Sh BUGS
+The number of options to this program is absurd, especially considering
+that there is not much logic behind their lettering.
+.Pp
+The field labels should be more consistent.
+.Pp
+The VM system does not record the CPU storage integral.
projects / apple / system_cmds.git / blobdiff