system_cmds-643.30.1.tar.gz

[apple/system_cmds.git] / sa.tproj / sa.8

diff --git a/sa.tproj/sa.8 b/sa.tproj/sa.8
index 288df04cd87d98a1acd0c0771574a638b4d54c15..1e9540c0d6b3ca9b334e11e8b353224d6f140f74 100644 (file)
--- a/sa.tproj/sa.8
+++ b/sa.tproj/sa.8
@@ -27,28 +27,30 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" (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
 .Dt SA 8
 .Os
 .Sh NAME
 .Nm sa
 .Nd print system accounting statistics
 .Sh SYNOPSIS

-.Nm sa
+.Nm

 .Op Fl abcdDfijkKlmnqrstu
 .Op Fl abcdDfijkKlmnqrstu

+.Op Fl P Ar file
+.Op Fl U Ar file

 .Op Fl v Ar cutoff
 .Op Ar
 .Sh DESCRIPTION
 The
 .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
 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
 utility is able to condense the information in
 .Pa /var/account/acct
 into the summary files


@@ -69,139 +71,132 @@ If file names are supplied, they are read instead of
 .Pa /var/account/acct .
 After each file is read, if the summary
 files are being updated, an updated summary will
 .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
 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 avio
 Average number of I/O operations per execution

-.\" ==========

 .It Dv cp
 Sum of user and system time, in minutes
 .It Dv cp
 Sum of user and system time, in minutes

-.\" ==========

 .It Dv cpu
 Same as
 .Dv cp
 .It Dv cpu
 Same as
 .Dv cp

-.\" ==========

 .It Dv k
 CPU-time averaged core usage, in 1k units
 .It Dv k
 CPU-time averaged core usage, in 1k units

-.\" ==========

 .It Dv k*sec
 CPU storage integral, in 1k-core seconds
 .It Dv k*sec
 CPU storage integral, in 1k-core seconds

-.\" ==========

 .It Dv re
 Real time, in minutes
 .It Dv re
 Real time, in minutes

-.\" ==========

 .It Dv s
 System time, in minutes
 .It Dv s
 System time, in minutes

-.\" ==========

 .It Dv tio
 Total number of I/O operations
 .It Dv tio
 Total number of I/O operations

-.\" ==========

 .It Dv u
 User time, in minutes
 .El
 .Pp
 The options to
 .It Dv u
 User time, in minutes
 .El
 .Pp
 The options to

-.Nm sa
+.Nm

 are:
 .Bl -tag -width Ds
 are:
 .Bl -tag -width Ds

-.\" ==========

 .It Fl a
 List all command names, including those containing unprintable
 .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''.
 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 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 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
 .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.
 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 f
 Force no interactive threshold comparison with the
 .Fl v
 option.

-.\" ==========

 .It Fl i
 Do not read in the summary files.
 .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 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
 .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.
 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 l
 Separate system and user time; normally they are combined.

-.\" ==========

 .It Fl m
 Print per-user statistics rather than per-command statistics.
 .It Fl m
 Print per-user statistics rather than per-command statistics.

-.\" ==========

 .It Fl n
 Sort by number of calls.
 .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 q
 Create no output other than error messages.

-.\" ==========

 .It Fl r
 Reverse order of sort.
 .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 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 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 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
 .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
 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
 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
 .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
 option is specified, the uid, user and system time (in seconds),
 CPU storage integral, I/O usage, and command name will be printed


@@ -211,7 +206,8 @@ If the
 .Fl u
 flag is specified, all flags other than
 .Fl q
 .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 ,
 .Fl m
 flag is specified, only the
 .Fl b ,


@@ -222,8 +218,6 @@ flag is specified, only the
 and
 .Fl s
 flags are honored.
 and
 .Fl s
 flags are honored.

-.Sh DIAGNOSTICS
-.Ex -std

 .Sh FILES
 .Bl -tag -width /var/account/usracct -compact
 .It Pa /var/account/acct
 .Sh FILES
 .Bl -tag -width /var/account/usracct -compact
 .It Pa /var/account/acct


@@ -233,23 +227,19 @@ per-command accounting summary database
 .It Pa /var/account/usracct
 per-user accounting summary database
 .El
 .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 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
 .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
 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
 particular, the
 .Fl q
 option has been added, and the


@@ -257,9 +247,16 @@ 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
 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
 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.