accounting.texi

\input texinfo   @c -*-texinfo-*-
@setfilename accounting.info
@settitle Accounting Utilities Manual

@dircategory GNU Utilities

@direntry
* acct: (accounting).          The GNU Accounting utilities for process and login accounting
@end direntry


@include version.texi

@dircategory Miscellaneous
@direntry
* acct: (accounting).                   User specific process accounting.
@end direntry

@ifinfo
GNU Accounting Utilities
Copyright (C) 1993, 1996, 1997, 1998, 2005, 2008, 2009, 2010
Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
@end ifinfo

@titlepage
@title GNU Accounting Utilities
@subtitle Version @value{VERSION}
@subtitle @value{UPDATED}
@author Noel Cragg @code{(noel@@gnu.ai.mit.edu)}
@author Markus Gothe @code{(nietzsche@@lysator.liu.se)}
@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1993, 1996, 1997, 1998, 2005, 2008, 2009, 2010
Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.
@end titlepage

@c ----------------------------------------------------------------------
@ifnottex
@node Top, Preface, (dir), (dir)

Welcome to the GNU Accounting Utilities!  If you don't have a clue about
the accounting utilities, read the introduction.  For specfic
information about any of the applications, see the chapter with the
program's name.

This is version @value{VERSION} of the GNU Accounting Utilities.
@end ifnottex

@menu
* Preface::                     general information about the accounting utilities

* ac::                          print statistics about connect time
* accton::                      turns accounting on or off
* lastcomm::                    list last commands executed
* sa::                          print accounting statistics
* dump-acct::                   print accounting file in human-readable form




@end menu

@c ----------------------------------------------------------------------
@node Preface, ac, Top, Top
@unnumbered Preface

Way back a long time ago, Thompson and Ritchie were sitting opposite one
another at the commissary, sipping coffees and discussing their evolving
behemoth.

``This behemoth of ours,'' said Ken, ``is becoming rather popular,
wouldn't you say?''  ``Yes,'' said Dennis.  ``Every time I want to do a
compilation, I have to wait for hours and hours.  It's infuriating.''
They both agreed that the load on their system was too great.  Both
sighed, picked up their mugs, and went back to the workbench.  Little
did they know that an upper-management type was sitting just within
earshot of their conversation.

``We are AT&T Bell Laboratories, aren't we?'' the upper-management type
thought to himself.  ``Well, what is our organization best known for?''
The brill-cream in his hair glistened.  ``Screwing people out of lots of
money, of course!  If there were some way that we could keep tabs on
users and charge them through the nose for their CPU time...''

The accounting utilities were born.

Seriously though, the accouting utilities can provide a system
administrator with useful information about system usage---connections,
programs executed, and utilization of system resources.

Information about users---their connect time, location, programs
executed, and the like---is automatically recored in files by
@code{init} and @code{login}.  Four of them are of interest to us:
@code{wtmp}, which has records for each login and logout;
@code{acct}, which records each command that was run;
@code{usracct} and @code{savacct}, which contain
summaries of the information in @code{acct} by user and
command, respectively.  Each of the accounting utilities reports or
summarizes information stored in these files.

@table @code
@item ac
prints statistics about users' connect time.  @code{ac} can tell you how
long a particular user or group of users were connected to your system,
printing totals by day or for all of the entries in the
@code{wtmp} file.

@item accton
turns accounting on or off.

@item lastcomm
lists the commands executed on the system, most recent first, showing
the run state of each command.  With @code{last}, you can search the
@code{acct} file for a particular user, terminal, or command.

@item sa
summarizes the information in the @code{acct} file into the
@code{savacct} and @code{usracct} file.  It also
generates reports about commands, giving the number of invocations, cpu
time used, average core usage, etc.

@item dump-acct
@itemx dump-utmp
display @code{acct} and @code{utmp} files in a human-readable format.

@end table

For more detailed information on any of these programs, check the
chapter with the program title.

@unnumberedsec A Note on File Names and Locations

The @code{wtmp} and @code{acct} files seem to live in different places
and have different names for every variant of u*x that exists.  The name
@code{wtmp} seems to be standard for the login accounting file, but the
process accounting file might be @code{acct} or @code{pacct} on your
system.  To find the actual locations and names of these files on your
system, specify the @code{--help} flag to any of the programs in this
package and the information will dumped to standard output.

Regardless of the names and locations of files on your system, this
manual will refer to the login accounting file as @code{wtmp} and the
process accounting files as @code{acct}, @code{savacct}, and
@code{usracct}.

@unnumberedsec Support for Multiple Accounting File Formats under Linux

The detailed format of the @code{acct} file written by the Linux kernel
varies depending on the kernel's version and configuration:
Linux kernels 2.6.7 and earlier write a v0 format @code{acct} file
which unfortunately cannot store user and group ids (@code{uid}/@code{gid})
larger than 65535.
Kernels 2.6.8 and later write the @code{acct} file in v1, v2 or v3 formats.
(v3 if @code{BSD_PROCESS_ACCT_V3} is selected in the kernel configuration,
otherwise v1 if on the m68k architecture or v2 everywhere else).

Since version 6.4 the GNU accounting utilities on Linux systems are
able to read all of the v0, v2 and v3 file formats (v1 is not supported).
Thus you do not need to worry about the details given above. You can even
read @code{acct} files where different records were written by differently
configured kernels (you can find out about the format of each entry by
using the @code{dump-acct} utility). In case you ever need to convert
an @code{acct} file to a different format, the @code{--raw} option of
@code{dump-acct} does that together with the new @code{--format} and
@code{--byteswap} options that determine format and byte order of the
output file.

Multiformat support under Linux is intended to be a temporary solution
to aid in switching to the v3 @code{acct} file format. So do not expect
GNU acct 6.7 to still contain Multiformat support. In a few years
time, when everybody uses the v3 format, the ability to read multiple
formats at runtime will probably be dropped again from the GNU accounting
utilities.
This does not, however, affect the ability to adapt to the @code{acct} file
format at compile time (when @code{./configure} is run). Even GNU acct 6.3.5
(that does not know about multiple file formats) will yield working binary
programs when compiled under a (as yet hypothetical) Linux kernel 2.6.62
that is only able to write the v3 format.

@unnumberedsec History of the Accounting Utilities

I don't have any idea who originally wrote these utilities.  If anybody
does, please send some mail to @code{noel@@gnu.ai.mit.edu} and I'll add
your information here!

Since the first alpha versions of this software in late 1993, many
people have contributed to the package.  They are (in alphabetical
order):

@c If you've changed something in this package, add your name here!

@table @code
@item Eric Backus <ericb@@lsid.hp.com>
Suggested fixes for HP-UX 9.05 using /bin/cc: configure assumed you were
using @code{gcc} and tacked on @code{-Wall} etc.  He also noticed that
@code{file_rd.c} was doing pointer arithmetic on a @code{void *} pointer
(non-ANSI).

@item Christoph Badura <bad@@flatlin.ka.sub.org>
Christoph was a BIG HELP in computing statistics, most notably k*sec
stuff!  He also did Xenix testing and contributed some Makefile fixes
and output optimizations.

@item Michael Calwas <calwas@@ttd.teradyne.com>
Fixed bugs in mktime.c.

@item Derek Clegg <dclegg@@apple.com>
Suggested the simple, elegant fix for *_rd_never_used brain-damage.

@item Alan Cox <iiitac@@pyr.swan.ac.uk>
Original Linux kernel accounting patches.

@item Scott Crosby <root@@hypercube.res.cmu.edu>
Suggested idea behind @code{--sort-real-time} for @code{sa}.

@item Solar Designer <solar@@false.com>
Added code for @code{--ahz} flag in @code{lastcomm} and @code{sa}.

@item Dirk Eddelbuettel <edd@@miles.econ.queensu.ca>
Managed bug-fixes & etc. for Debian distribution, as well as the
architect of merge of GNU + Debian distributions.  A big thanks to Dirk
for kicking me back into gear again after a long period of no work on
this project.

@item Jason Grant <jamalcol@@pc-5530.bc.rogers.wave.ca>
Identified a buffer-overrun bug in @code{sa}.

@item Kaveh R. Ghazi <ghazi@@caip.rutgers.edu>
Tested the package on many systems with compilers other than gcc.  Fixed
K&R C support.

@item Susan Kleinmann <sgk@@sgk.tiac.net>
Contributed excellent man pages!

@item Alexander Kourakos <Alexander@@Kourakos.com>
Inspired the @code{--wide} option for @code{last}.

@item Marek Michalkiewicz <marekm@@i17linuxb.ists.pwr.wroc.pl>
Suggested the @code{--ip-address} flag for @code{last}.

@item David S. Miller <davem@@caip.rutgers.edu>
Noticed missing GNU-standard makefile rules.

@item Walter Mueller <walt@@pi4.informatik.uni-mannheim.de>
Noticed install target was missing, and corrected a typo for prefix in
Makefile.in.

@item Ian Murdock <imurdock@@gnu.ai.mit.edu> 
Tracked down miscellaneous bugs in sa.c under Linux.  Added Debian
package maintenance files.

@item Tuomo Pyhala <tuomo@@lesti.kpnet.fi>
Reported buggy @code{--strict-match} flag in @code{lastcomm}.

@item Tim Schmielau <tim@@physik3.uni-rostock.de>
Added Linux multiformat support.

@item Luc I. Suryo <root@@patriots.nl.mugnet.org>
Suggested the @code{--user} flag for @code{lastcomm}.

@item Pedro A M Vazquez <vazquez@@iqm.unicamp.br>
Fixed bugs in sa.c and tested under FreeBSD.

@item Marco van Wieringen <Marco.van.Wieringen@@mcs.nl.mugnet.org>
Modified (wrote?) Linux kernel accounting patches.
@end table

@c ----------------------------------------------------------------------
@node ac, accton, Preface, Top
@chapter @code{ac}
@cindex ac
@cindex connect time

The @code{ac} command prints out a report of connect time (in hours)
based on the logins/logouts in the current @code{wtmp} file.
A total is also printed out.

The accounting file @code{wtmp} is maintained by @code{init}
and @code{login}.  Neither of these programs creates the file; if the
file is not there, no accounting is done.  To begin accounting, create
the file with a length of zero. Note that the
@code{wtmp} file can get really big, really fast.  You might
want to trim it every once and a while.

GNU @code{ac} works nearly the same u*x @code{ac}, though it's a little
smarter in its printing out of daily totals---it actually prints
@emph{every} day, rather than skipping to the date of the next entry in
the @code{wtmp} file.

@section Flags

All of the original @code{ac}'s options have been implemented, and a few have
been added.  Normally, when @code{ac} is invoked, the output looks like
this:
@example
        total 93867.14
@end example
@noindent
where total is the number of hours of connect time for every entry in
the @code{wtmp} file.  The rest of the flags modify the
output in one way or another.

@table @code
@item -d
@itemx --daily-totals
Print totals for each day rather than just one big total at the end.
The output looks like this:
@example
Jul  3  total     1.17
Jul  4  total     2.10
Jul  5  total     8.23
Jul  6  total     2.10
Jul  7  total     0.30
@end example

@item -p
@itemx --individual-totals
Print time totals for each user in addition to the usual
everything-lumped-into-one value.  It looks like:
@example
        bob       8.06
        goff      0.60
        maley     7.37
        root      0.12
        total    16.15
@end example

@item @var{people}
Print out the sum total of the connect time used by all of the users
included in people.  Note that people is a space separated list of valid
user names; wildcards are not allowed.

@item -f @var{filename}
@itemx --file @var{filename}
Read from the file @var{filename} instead of the system's
@code{wtmp} file.

@item --complain
When the @code{wtmp} file has a problem (a time-warp, missing
record, or whatever), print out an appropriate error.

@item --reboots
Reboot records are @emph{not} written at the time of a reboot, but when
the system restarts; therefore, it is impossible to know @var{exactly}
when the reboot occurred.  Users may have been logged into the system at
the time of the reboot, and many @code{ac}'s automatically count the
time between the login and the reboot record against the user (even
though all of that time @emph{shouldn't} be, perhaps, if the system is
down for a long time, for instance).  If you want to count this time,
include the flag.  @strong{To make @code{ac} behave like the one that
was distributed with your OS, include this flag.}

@item --supplants
Sometimes a logout record is not written for a specific terminal, so the
time that the last user accrued cannot be calculated.  If you want to
include the time from the user's login to the next login on the terminal
(though probably incorrect), include this flag.  @strong{To make
@code{ac} behave like the one that was distributed with your OS, include
this flag.}

@item --timewarps
Sometimes, entries in a @code{wtmp} file will suddenly jump
back into the past without a clock change record occurring.  It is
impossible to know how long a user was logged in when this occurs.  If
you want to count the time between the login and the time warp against
the user, include this flag.  @strong{To make @code{ac} behave like the
one that was distributed with your OS, include this flag.}

@item --compatibility
This is shorthand for typing out the three above options.

@item -a
@itemx --all-days
If we're printing daily totals, print a record for every day instead of
skipping intervening days where there is no login activity.  Without
this flag, time accrued during those intervening days gets listed under
the next day where there is login activity.

@item -y
@itemx --print-year
Print out the year when displaying dates.

@item --print-zeros
If a total for any category (save the grand total) is zero, print it.
The default is to suppress printing.

@item --debug
Print verbose internal information.

@item --tw-leniency @var{value}
Set the time warp leniency value (in seconds).  Records in
@code{wtmp} files might be slightly out of order (most
notably when two logins occur within a one-second period -- the second
one gets written first).  By default, this value is set to 1 second.
Some @code{wtmp}'s are really screwed up (Suns) and require a
larger value here.  If the program notices this problem, time is not
assigned to users unless the @code{--timewarps} flag is used.  See the
Problems section for more information.

@item --tw-suspicious @var{value}
Set the time warp suspicious value (in seconds).  If two records in the
@code{wtmp} file are farther than this number of seconds
apart, there is a problem with the wtmp file (or your machine
hasn't been used in a year).  If the program notices this problem, time
is not assigned to users unless the @code{--timewarps} flag is used.

@item -V
@itemx --version
Print @code{ac}'s version number.

@item -h
@itemx --help
Print @code{ac}'s usage string and default locations of system files to
standard output.
@end table

@section Problems

For no fault of @code{ac}'s, if two logins occur at the same time
(within a second of each other), each @code{login} process will try to
write an entry to the @code{wtmp} file.  With file system
overhead, it is forseeable that the entries would get written in the
wrong order.  GNU @code{ac} automatically compensates for this, but some
other @code{ac}s may not...  beware.

@unnumberedsubsec The FTP Problem

I've tested the standard @code{ac} in Ultrix 4.2 (DECstation/DECsystem),
SunOS 4.1.1 (Sun3, Sun4, Sparc), Mach 2.5 (Omron/Luna), and DomainOS
10.3 (DN3500).  All of these @code{ac}s have trouble parsing entries in
which the line is @code{ftp}@var{xxxx} (@var{xxxx} being some number).
Whenever these @code{ac}s see one of these entries, they log everyone
out at the time of the entry.

@noindent
@strong{HOW IT HAPPENS:} if there is a user logged into the machine when
an ftp connection occurs, (minimally) you'll get a login record for the
user, a login record for the ftp connection, and the logouts for both
afterwards (in either order).

@noindent
@strong{TANGIBLE RESULT:} the user who was logged in gets 'logged out'
at the time the ftp connection begins, and none of the time spent during
or after the ftp connection.  Therefore, when you run GNU @code{ac},
the totals will most likely be greater than those of your system's
@code{ac} (provided you specify the other flags that will make GNU
@code{ac} behave like the system's).

@unnumberedsubsubsec The Shutdown/Reboot Problem

On Suns, @code{init} is a little screwed up.  For some reason, after a
shutdown record is written, a reboot record is written with a time-stamp
@emph{before} the shutdown (less than 30 seconds, usually).

@noindent
@strong{TANGIBLE RESULT:} GNU @code{ac} will notice the problem, log
everyone out (you can specify if you want the time to be added to the
user's total) and begin a new day entry based on the time of the
out-of-sync record.  If you try to print out daily totals, you'll notice
that some days might have two or more entries.

@noindent
@strong{SOLUTION:} To fix this, a timewarp leniency value has been
implemented.  If any record is out of order by this number of seconds
(defaults to 60) it gets ignored.  If you need to change this value (if
you think the totals are off because the value is too high), you can
change it using the @samp{--timewarp-value} flag.  The rationale for the
60 second default is that of all of the machines with this problem, the
largest timewarp was 45.

@unnumberedsubsubsec Stupid System V Machines

Some @code{ac}'s on System V machines (I've tried SGI Indigo & SGI Indy)
forget to pay attention to the @code{ut_type} field in a @code{struct
utmp}.  As such, they chalk up a lot of time to non-existant processes
called @code{LOGIN} or @code{runlevel}.  

@noindent
@strong{TANGIBLE RESULT:} The amount of total time reported by the
system's @code{ac} is @strong{really} off.  Often, it's several times
greater than what it should be.

@noindent
@strong{SOLUTION:} GNU @code{ac} always pays attention to the
@code{ut_type} record, so there's no possibility of chalking up time to
anything but user processes.

@c ----------------------------------------------------------------------
@node accton, lastcomm, ac, Top
@chapter @code{accton}

@code{accton} turns process accounting on or off.  To save process
accounting information in @var{accountingfile}, use:

@code{accton @var{accountingfile}}

@section Flags

@table @code

@item -V
@itemx --version
Print @code{accton}'s version number.

@item -h
@itemx --help
Print @code{accton}'s usage string and default locations of system files
to standard output.

@item on
Turns on process accounting using the default accounting file.

@item off
Turns off process accounting.

@end table

@c ----------------------------------------------------------------------
@node lastcomm, sa, accton, Top
@chapter @code{lastcomm}

@code{lastcomm} prints out information about previously executed
commands.  If no arguments are specified, @code{lastcomm} will print
info about all of the commands in the @code{acct} file (the
record file).  If called with a command name, user name, or tty name,
only records containing those items will be displayed.  For example, to
find out which users used command @samp{a.out} and which users were
logged into @samp{tty0}, type:

@code{lastcomm a.out tty0}

This will print any entry for which @samp{a.out} or @samp{tty0} matches
in any of the record's fields (command, name, or tty).  If you want to
find only items that match ALL of the arguments on the command line, you
must use the '--strict-match' option.  For example, to list all of the
executions of command @samp{a.out} by user @samp{root} on terminal
@samp{tty0}, type:

@code{lastcomm --strict-match a.out root tty0}

The order of the arguments is not important.

For each entry the following information is printed:

@itemize @bullet
@item
command name of the process
@item
flags, as recorded by the system accounting routines:
@itemize @minus
@item
@strong{S} command executed by super-user
@item
@strong{F} command executed after a fork but without a following exec
@item
@strong{C} command run in PDP-11 compatibility mode (VAX only)
@item
@strong{D} command terminated with the generation of a core file
@item
@strong{X} command was terminated with the signal SIGTERM
@end itemize
@item
the name of the user who ran the process
@item
time the process exited
@end itemize

@section Flags

This program implements the features of regular u*x @code{lastcomm} with
a few extra flags.  When @code{lastcomm} is invoked without arguments,
the output looks like this:
@example
nslookup         jberman  ttypb      0.03 secs Tue Feb 16 19:23
comsat           root     __         0.03 secs Tue Feb 16 19:19
uptime           ctilburg __         0.11 secs Tue Feb 16 19:23
sh          F    ctilburg __         0.02 secs Tue Feb 16 19:23
sleep            ctilburg __         0.02 secs Tue Feb 16 19:22
ls               noel     ttyp4      0.19 secs Tue Feb 16 19:23
@end example

@table @code
@item --strict-match
Print only entries that match @emph{all} of the arguments on the command
line.

@item --user @var{name}
List records for user with @var{name}.  This is useful if you're trying
to match a username that happens to be the same as a command (e.g.,
@code{ed}).

@item --command @var{name}
List records for command @var{name}.

@item --tty @var{name}
List records for tty @var{name}.

@item -f @var{filename}
@itemx --file @var{filename}
Read from the file @var{filename} instead of the system's
@code{acct} file.

@item --ahz @var{hz}
Use this flag to tell the program what @code{AHZ} should be (in hertz).
This option is useful if you are trying to view an @code{acct} file
created on another machine which has the same byte order and file format
as your current machine, but has a different value for @code{AHZ}.

@item -p
@itemx --show-paging
Print paging statistics

@item --debug
Print verbose internal information.

@item --version
Print @code{lastcomm}'s version number.

@item --help
Print @code{lastcomm}'s usage string and default locations of system
files to standard output.
@end table

@c ----------------------------------------------------------------------
@node sa, dump-acct, lastcomm, Top
@chapter @code{sa}

@code{sa} summarizes information about previously executed commands as
recorded in the @code{acct} file.  In addition, it condenses this data
into the @code{savacct} summary file, which contains the
number of times the command was called and the system resources used.
The information can also be summarized on a per-user basis; @code{sa}
will save this information into @code{usracct}.  Usage:

@code{sa [@var{opts}] [@var{file}]}

If no arguments are specified, @code{sa} will print information about
all of the commands in the @code{acct} file.  If command
names have unprintable characters, or are only called once, @code{sa}
will sort them into a group called @code{***other}.  Overall totals for
each field are gathered and printed with a blank command name.

If called with a file name as the last argument, @code{sa} will use that
file instead of @code{acct}.

By default, @code{sa} will sort the output by sum of user and system
time.

The output fields are labeled as follows:

@table @code

@item cpu
sum of system and user time in cpu seconds

@item re
``real time'' in cpu seconds

@item k
cpu-time averaged core usage, in 1k units

@item avio
average number of I/O operations per execution

@item tio
total number of I/O operations

@item k*sec
cpu storage integral (kilo-core seconds)

@item u
user cpu time in cpu seconds

@item s
system time in cpu seconds

@end table

Note that these column titles do not appear in the first row of the
table, but after each numeric entry (as units of measurement) in every
row.  For example, you might see @code{79.29re}, meaning 79.29 cpu
seconds of ``real time.''

An asterisk will appear after the name of commands that forked but
didn't call @code{exec}.

@section Flags

The availability of these program options depends on your operating
system.  In specific, the members that appear in the @code{struct acct}
of your system's process accounting header file (usually @code{acct.h})
determine which flags will be present.  For example, if your system's
@code{struct acct} doesn't have the @code{ac_mem} field, the installed
version of @code{sa} will not support the @code{--sort-cpu-avmem},
@code{--sort-ksec}, @code{-k}, or @code{-K} options.

In short, all of these flags may not be available on your machine.

@table @code

@item -a
@itemx --list-all-names
Force @code{sa} not to sort those command names with unprintable
characters and those used only once into the `@code{***other}' group.

@item -b
@itemx --sort-sys-user-div-calls
Sort the output by the sum of user and system time divided by the number
of calls.

@item -c
@itemx --percentages
Print percentages of total time for the command's user, system, and real
time values.

@item -d
@itemx --sort-avio
Sort the output by the average number of disk I/O operations.

@item -D
@itemx --sort-tio
Print and sort the output by the total number of disk I/O operations.

@item -f
@itemx --not-interactive
When using the @code{--threshold} option, assume that all answers to
interactive queries will be affirmative.

@item -i
@itemx --dont-read-summary-file
Don't read the information in @code{savacct}.

@item -j
@itemx --print-seconds
Instead of printing total minutes for each category, print seconds per
call.

@item -k
@itemx --sort-cpu-avmem
Sort the output by cpu time average memory usage.

@item -K
@itemx --sort-ksec
Print and sort the output by the cpu-storage integral.

@item -l
@itemx --separate-times
Print separate columns for system and user time; usually the two are
added together and listed as @code{cpu}.

@item -m
@itemx --user-summary
Print the number of processes and number of CPU minutes on a per-user
basis.

@item -n
@itemx --sort-num-calls
Sort the output by the number of calls.  This is the default sorting
method.

@item -p
@itemx --show-paging
Print the number of minor and major pagefaults and swaps.

@item -P
@itemx --show-paging-avg
Print the number of minor and major pagefaults and swaps divided by
the number of calls.

@item -r
@itemx --reverse-sort
Sort output items in reverse order.

@item -s
@itemx --merge
Merge the summarized accounting data into the summary files
@code{savacct} and @code{usracct}.

@item -t
@itemx --print-ratio
For each entry, print the ratio of real time to the sum of system and
user times.  If the sum of system and user times is too small to
report---the sum is zero---@code{*ignore*} will appear in this field.

@item -u
@itemx --print-users
For each command in the accounting file, print the userid and command
name.  After printing all entries, quit.  @strong{Note}: this flag
supersedes all others.

@item -v @var{num}
@itemx --threshold @var{num}
Print commands which were executed @var{num} times or fewer and await a
reply from the terminal.  If the response begins with @code{y}, add the
command to the @code{**junk**} group.

@item --separate-forks
It really doesn't make any sense to me that the stock version of
@code{sa} separates statistics for a particular executable depending on
whether or not that command forked.  Therefore, GNU @code{sa} lumps this
information together unless this option is specified.

@item --sort-real-time
Sort the output by the ``real time'' (elapsed time) for each command.

@item --ahz @var{hz}
Use this flag to tell the program what @code{AHZ} should be (in hertz).
This option is useful if you are trying to view an @code{acct} file
created on another machine which has the same byte order and file format
as your current machine, but has a different value for @code{AHZ}.

@item --debug
Print verbose internal information.

@item -V
@itemx --version
Print @code{sa}'s version number.

@item -h
@itemx --help
Print @code{sa}'s usage string and default locations of system files to
standard output.
@end table

@strong{Note}: if more than one sorting option is specified, the list
will be sorted by the one specified last on the command line.

@section Problems

I haven't been able to test this on many different machines because the
data files grow so big in a short time; our sysadmin would rather save
the disk space.

Most versions of @code{sa} that I've tested don't pay attention to flags
like @code{--print-seconds} and @code{--sort-num-calls} when printing
out commands when combined with the @code{--user-summary} or
@code{--print-users} flags.  GNU @code{sa} pays attention to these flags
if they are applicable.

@subsection mips sa

The average memory use is stored as a short rather than a double, so we
suffer from round-off errors.  GNU @code{sa} uses double the whole way
through.


@c ----------------------------------------------------------------------
@node dump-acct,  , sa, Top
@chapter @code{dump-acct}

@code{dump-acct} dumps some of the contents of one or more @code{acct}
files in human readable form.  Usage:

@code{dump-acct [@var{opts}] @var{files}}

Unless called with the @code{--raw} option, it prints a table with the
following fields, separated by vertical bars(@code{|}):

@table @code

@item ac_comm
name of the executed program

@item ac_version
version of the @code{acct} file format

@item ac_utime
user time

@item ac_stime
system time

@item ac_etime
elapsed time

@item ac_uid
user id

@item ac_gid
group id

@item ac_mem
(average) memory usage

@item ac_io
number of characters transferred on input/output

@item ac_pid
process id

@item ac_ppid
parent's process id

@end table

All times will be given in platform dependent units (``@code{AHZ}'').
Not all of the above columns will actually appear, depending on what
information your operating system provides in it's @code{struct acct}.

@section Flags

@table @code

@item --ahz @var{hz}
Use this flag to tell the program what @code{AHZ} should be (in Hertz).
This option is useful if you are trying to view an @code{acct} file
created on another machine which has a different value for @code{AHZ}.

@item --byteswap
Swap the bytes (relative to your system's native byte order) in
@code{--raw} output.

@item --format
Set output format with @code{--raw} option.

@item -n @var{num}
@itemx --num @var{num}
Limit the number of lines (or records with @code{--raw}) to print.

@item -r
@itemx --reverse
Read the accounting file backwards (print latest record first).

@item -R
@itemx --raw
Don't print human readable output, dump the raw record instead.
Useful to convert between different Linux file formats (see below).

@item -h
@itemx --help
Print @code{dump-acct}'s usage string and default location of
the accouning file to standard output.

@end table

@code{--byteswap} and @code{--format} options are only available with
Linux multiformat support. They only affect @emph{output} with
the @code{--raw} option, format and byte order of the input are
automatically detected.
Thus they are useful to convert between different file formats.

The @code{--ahz} option affects input and output (except for v3 file
format, which by definition is fixed to @code{AHZ=100}).
If you ever need to convert between different @code{AHZ} values,
use a two-step process:
First convert to v3 format with the @emph{old} @code{AHZ} value, then
convert to the desired output format with the @emph{new} @code{AHZ}
setting.


@c ----------------------------------------------------------------------
@c @node Index,  , dump-acct, Top
@c @unnumbered Index
@c 
@c @printindex cp
@c 

@contents

@bye