365 lines
12 KiB
Groff
365 lines
12 KiB
Groff
'\"macro stdmacro
|
|
.nr X
|
|
.if \nX=0 .ds x} PAR 1 "" "\&"
|
|
.if \nX=1 .ds x} PAR 1 ""
|
|
.if \nX=2 .ds x} PAR 1 "" "\&"
|
|
.if \nX=3 .ds x} PAR "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4par\fP \- process activity reporter / truss-like system call tracer
|
|
.SH SYNOPSIS
|
|
\f4par\f1
|
|
[\f4\-ABOsricdluSQ\^\f1]
|
|
[\f4\-P \f2pid\f1\^]
|
|
[\f4\-n \f2nbr\f1\^]
|
|
[\f4\-N \f2name\f1\^]
|
|
[\f4\-o \f2file\f1\^]
|
|
.br
|
|
.ti +10
|
|
[\f4\-a \f2len\f1\^]
|
|
[\f4\-b \f2len\f1\^]
|
|
[\f2cmd args ...\f1\^]
|
|
.sp
|
|
\f4par\f1
|
|
[\f4\-ABOsricdluSQ\^\f1]
|
|
[\f4\-P \f2pid\f1\^]
|
|
[\f4\-n \f2nbr\f1\^]
|
|
[\f4\-N \f2name\f1\^]
|
|
.br
|
|
.ti +10
|
|
[\f4\-a \f2len\f1\^]
|
|
[\f4\-b \f2len\f1\^]
|
|
[\f4\-o \f2file\f1\^]
|
|
[\f4\-p \f2pid\f1\^]
|
|
[\f4\-p \f2...\f1\^]
|
|
.sp
|
|
\f4par\f1
|
|
[\f4\-ABOsricdluSQ\^\f1]
|
|
[\f4\-P \f2pid\f1\^]
|
|
[\f4\-n \f2nbr\f1\^]
|
|
[\f4\-N \f2name\f1\^]
|
|
[\f4\-t \f2time\f1\^]
|
|
.br
|
|
.ti +10
|
|
[\f4\-a \f2len\f1\^]
|
|
[\f4\-b \f2len\f1\^]
|
|
[\f4\-o \f2file\f1\^]
|
|
.sp
|
|
\f4par\f1
|
|
[\f4\-ABOsricdluSQ\^\f1]
|
|
[\f4\-P \f2pid\f1\^]
|
|
[\f4\-n \f2nbr\f1\^]
|
|
[\f4\-N \f2name\f1\^]
|
|
[\f4\-o \f2file\f1\^]
|
|
.br
|
|
.ti +10
|
|
[\f4\-a \f2len\f1\^]
|
|
[\f4\-b \f2len\f1\^]
|
|
.SH DESCRIPTION
|
|
\f4par\fP
|
|
is a system utility program which has the ability to trace
|
|
system call and scheduling activity.
|
|
It can be used to trace the activity of a single process,
|
|
a related group of processes or the system as a whole.
|
|
See the \f4EXAMPLES\fP section near the end for some examples
|
|
on how par is commonly used.
|
|
.PP
|
|
When tracing system calls, \f4par\fP(1) prints a report showing
|
|
all system calls made by the subject processes complete with
|
|
arguments and return values.
|
|
In this mode, \f4par\fP(1) also reports all signals delivered
|
|
to the subject processes.
|
|
In schedule tracing mode, \f4par\fP(1) prints a report showing
|
|
all scheduling events taking place in the system during the
|
|
measurement period. The report shows each time a process is
|
|
put on the run queue, started on a processor, descheduled
|
|
from a processor, including the reason that the process
|
|
was descheduled. The events include timestamps.
|
|
.PP
|
|
\f4par\fP(1) works by processing the output of \f4padc\fP(1).
|
|
This can be done in two ways: \f4padc\fP can be run separately
|
|
and the output saved in a file to be fed to \f4par\fP as a
|
|
separate operation or \f4padc\fP can be invoked by \f4par\fP
|
|
to perform the data collection and reporting in one step.
|
|
\f4par\fP can provide different types of reports from a
|
|
given set of \f4padc\fP data depending on the reporting
|
|
options that are specified. This is a reason why it is
|
|
sometimes desirable to run the data collection as a separate
|
|
step.
|
|
.PP
|
|
There are three things that need to be specified on the \f4par\fP
|
|
command line: data collection options, reporting options and
|
|
object to be monitored.
|
|
.PP
|
|
\f4Data Collection Options\fP
|
|
.PP
|
|
.TP 10
|
|
\f4\-s\fP
|
|
Collect system call and signal trace.
|
|
.TP
|
|
\f4\-r\fP
|
|
Collect scheduler activity trace.
|
|
Note that only the superuser can perform scheduler tracing.
|
|
.TP
|
|
\f4\-i\fP
|
|
Inherit tracing to forked children of object processes.
|
|
.PP
|
|
\f4Input options\fP
|
|
.TP 10
|
|
\."XXX DEPRECATED BACKWARDS COMPATIBILITY -- THIS SHOULD GO AWAY
|
|
\f4\-O\fP
|
|
Read old ASCII padc output. This backwards compatibility is not likely to
|
|
be supported in the next major release.
|
|
.PP
|
|
\f4Reporting options\fP
|
|
.TP 10
|
|
\f4\-l\fP
|
|
Show system call output in long form.
|
|
.TP
|
|
\f4\-n \f2syscall-number\fP
|
|
Show records for the specified system call number. This option
|
|
may be specified multiple times.
|
|
.TP
|
|
\f4\-N \f2syscall-name\fP
|
|
Show records for the specified system call name. This option
|
|
may be specified multiple times.
|
|
.TP
|
|
\f4\-P \f2pid\fP
|
|
List system calls only for the process specified by \f2pid\fP.
|
|
Note that this is markedly different from the \f4\-p\fP \f2pid\fP option
|
|
which requests that the named \f2pid\fP be traced. Thus one could request
|
|
that processes 100 and 101 be traced, but only report system calls for
|
|
process 101 (note that scheduling events would still be reported for process
|
|
100 if scheduling reporting options had been selected). This reporting
|
|
option is typically used when \f4padc\fP has been used to collect data on a
|
|
number of processes \(em often either by collecting for all processes on the
|
|
system or all processes descended from a specified process.
|
|
.TP
|
|
\f4\-S\fP
|
|
Print summary of system calls and signal counts.
|
|
.TP
|
|
\f4\-SS\fP
|
|
Print detailed system call trace and summary of system calls and signal counts.
|
|
.TP
|
|
\f4\-Q\f2
|
|
Print scheduling summary.
|
|
Note that this option is only meaningful
|
|
when the \f4\-r\fP data collection option is specified.
|
|
.TP
|
|
\f4\-QQ\f2
|
|
Print detailed scheduling trace.
|
|
Note that this option is only meaningful
|
|
when the \f4\-r\fP data collection option is specified.
|
|
.TP
|
|
\f4\-QQQ\f2
|
|
In addition to the detailed scheduling trace, print the contents
|
|
of the run queue after each scheduler operation.
|
|
Note that this option is only meaningful
|
|
when the \f4\-r\fP data collection option is specified.
|
|
.TP
|
|
\f4\-k\fP
|
|
Print trace of disk activity.
|
|
.TP
|
|
\f4\-c\f2
|
|
Do not print cpu numbers.
|
|
.TP
|
|
\f4\-d\f2
|
|
Show any system call time deltas.
|
|
Normally, if possible, system calls are printed on one line, showing
|
|
input arguments, output arguments and return values.
|
|
The time displayed is the time of the start of the system call.
|
|
With the \f4\-d\fP option, if the start and end times of the system call
|
|
are not equal the printing is split into 2 lines showing the start
|
|
and end time of the system call.
|
|
.TP
|
|
\f4\-u\f2
|
|
Show relative time between events in microseconds.
|
|
.TP
|
|
\f4\-o\fP \f2file\fP
|
|
Print all output (including errors) to \f4file\fP.
|
|
This is useful when monitoring a program that itself does output.
|
|
.TP
|
|
\f4\-a\fP \f2len\fP
|
|
Set the maximum number of bytes printed in character format for data
|
|
(e.g. from a \f4read\fP call) to \f2len\fP.
|
|
This value defaults to 30.
|
|
The larger of the value for this option and the \f4\-b\fP option is used
|
|
to inform \f4padc\fP, if appropriate, how much data to collect (see the
|
|
\f4\-I\fP option of \f4padc\fP).
|
|
The maximum value for this option is 4096 bytes.
|
|
.TP
|
|
\f4\-b\fP \f2len\fP
|
|
Set the maximum number of bytes printed in binary format for data
|
|
(e.g. from a \f4read\fP call) to \f2len\fP.
|
|
This value defaults to 16.
|
|
The maximum value for this option is 4096 bytes.
|
|
.TP
|
|
\f4\-B\fP
|
|
Show data (e.g. from a \f4read\fP call) in hex binary format.
|
|
Normally, \f4par\fP attempts to output data in an appropriate format.
|
|
.TP
|
|
\f4\-A\fP
|
|
Show data (e.g. from a \f4read\fP call) in character format.
|
|
Non printable characters are output in hex.
|
|
.PP
|
|
\f4Object specification\fP
|
|
.TP 10
|
|
\f4\-p \f2pid\fP
|
|
Trace the process specified by \f2pid\fP. Also affected by \f4\-i\fP
|
|
flag above.
|
|
In this mode, \f4padc\f1(1) is automatically invoked
|
|
by \f4par\f1.
|
|
Multiple \f4\-p\fP options may be given.
|
|
.TP 10
|
|
\f4\-t \f2time\fP
|
|
Terminate the trace after \f2time\fP seconds. Primarily useful
|
|
when tracing the system as a whole.
|
|
.TP 10
|
|
\f4[\f2command arguments ...\^\f4]\f1
|
|
Runs the specified command with tracing enabled.
|
|
If the \f4\-i\fP option is specified, any child processes that are
|
|
created will also be traced.
|
|
In this mode, \f4padc\f1(1) is automatically invoked
|
|
by \f4par\f1.
|
|
.TP 10
|
|
\f2nothing\f1
|
|
If no specification of an object is given, all specified activity
|
|
will be traced for the system as a whole.
|
|
Note that only the superuser can trace the system as a whole.
|
|
In this mode, \f4padc\f1(1) is automatically invoked
|
|
by \f4par\f1.
|
|
.TP 10
|
|
If no data collection options are specified and no object is
|
|
specified, \f4par\f1 will read standard input as output from \f4padc\f1
|
|
and report the data according to the reporting options selected.
|
|
.PP
|
|
.SH "INTERPRETING THE DISPLAY"
|
|
The system call trace output displays the following:
|
|
.TP 15
|
|
\f2timestamp\fP
|
|
The relative time of the event in milliseconds.
|
|
If the \f4\-u\fP option is set, following the time stamp will be the
|
|
number of microseconds from the last event to the current event (enclosed
|
|
in parenthesis).
|
|
.TP 15
|
|
\f2cpu\fP
|
|
The cpu number the event was generated on.
|
|
The value is enclosed in brackets \f4[]\fP.
|
|
This is displayed if one is doing a long listing, there is more than
|
|
one cpu in the system that \f4par\fP is run on, and the \f\-c\fP has not
|
|
been specified.
|
|
A long listing is in effect if the \f4\-l\fP option is specified or
|
|
one is doing schedule tracing (\f4\-Q\fP option) or the inherit option
|
|
(\f4\-i\fP) is specified, or one is asking for information about more
|
|
than one pid (more than one \f4\-P\fP option) or one is tracing all
|
|
processes.
|
|
.TP 15
|
|
\f2name\fP
|
|
The name of the process (as displayed by \f4ps\fP(1)).
|
|
This is only displayed when in long listing mode (see above).
|
|
.TP 15
|
|
\f2pid\fP
|
|
The pid of the process (enclosed in parenthesis).
|
|
This is only displayed when in long listing mode (see above).
|
|
.TP 15
|
|
\f2system_call_name\fP
|
|
The system call name.
|
|
If the system call being displayed is split into 2 events, the event
|
|
marking the end of the system call will have \f4END-\fP prepended to
|
|
the name.
|
|
See below for some help in decoding system call names.
|
|
\f4par\fP attempts to print an entire system call - input arguments,
|
|
output arguments, and error return on a single line.
|
|
It can't do this if the \f4\-d\fP option is given or there is a system
|
|
call by another process that comes between the start and end of the call
|
|
\f4par\fP is printing.
|
|
.TP 15
|
|
\f2args\fP
|
|
The system call arguments are printed (enclosed in parenthesis, separated
|
|
by commas).
|
|
Various amounts of decoding of arguments is done.
|
|
Some system calls have complex arguments that are both input and output
|
|
arguments.
|
|
If the entire system call is being printed on a single line, these
|
|
input/output arguments have the words \f4IN:\fP or \f4OUT:\fP printed
|
|
before the decoding of the argument.
|
|
.TP 15
|
|
\f2error_value\fP
|
|
The error status or return value of the call.
|
|
For system calls that simply return success or failure, \f4OK\fP
|
|
is printed for success, and the error value for failure.
|
|
System calls that return values have those values printed.
|
|
.PP
|
|
Since \f4par\fP's information comes straight from the operating
|
|
system at the system call level, some calls that \f4par\fP presents
|
|
may not seem to correspond to the calls that the application made.
|
|
This is because some system calls are implemented in \f4libc\fP on top
|
|
of more primitive system calls.
|
|
Some of these are noted below.
|
|
.TP 15
|
|
\f4waitsys\fP
|
|
is the underlying system call for all wait-like calls.
|
|
Its arguments are the same as \f4waitid\fP(2) except that it takes as a
|
|
fifth argument a pointer to a \f2struct rusage\fP.
|
|
.TP
|
|
\f4?xstat\fP
|
|
These stat calls are the same as the application entry points except
|
|
that the first argument is a version number.
|
|
.TP
|
|
\f4sigaction\fP
|
|
is used to implement all type signal routines.
|
|
It takes one additional parameter than the application entry point -
|
|
the address of the library handler that all signals funnel through.
|
|
.TP
|
|
\f4sigreturn\fP
|
|
is used to return a process from its signal handler to the previous context.
|
|
.TP
|
|
\f4sigpoll\fP
|
|
is used to implement \f4sigwaitrt\fP(3) and \f4sigtimedwait\fP(3).
|
|
.TP
|
|
\f4ERESTART\fP
|
|
is returned when a system call should be automatically restarted after
|
|
being interrupted by a signal (see \f4sigaction\fP).
|
|
This error is never actually returned to the user but \f4par\fP reports
|
|
the re-invocation of a system call as an error.
|
|
.PP
|
|
.SH EXAMPLES
|
|
.Ex
|
|
\f4par -s -SS ls\fP
|
|
.Ee
|
|
Displays a detailed system call trace for the 'ls' command.
|
|
.Ex
|
|
\f4par -s -r -SS -QQ ls\fP
|
|
.Ee
|
|
Displays a detailed system call trace and a detailed scheduling
|
|
trace for the 'ls' command.
|
|
.Ex
|
|
\f4par -o outfile -s -SS -N open -N close ps -elf\fP
|
|
.Ee
|
|
Trace only the open and close system calls. Write the resulting
|
|
output to \f2outfile\fP.
|
|
.Ex
|
|
\f4par -o outfile -s -SS -i -p 1
|
|
.Ee
|
|
Trace all processes started directly by process 1 (which is the
|
|
\f3init\fP process, the ancestor of all user processes), and store
|
|
tien output in the file \f2outfile\fP.
|
|
.PP
|
|
.SH FILES
|
|
\f4/dev/par\fP
|
|
.SH LIMITATIONS
|
|
To avoid deadlock and resource exhaustion problems, events generated by
|
|
\f4padc\fP(1) are not recorded.
|
|
This can lead to some inexplicable gaps in the schedule trace.
|
|
.SH "SEE ALSO"
|
|
\f4padc\fP(1),
|
|
\f4schedctl\fP(2),
|
|
\f4gettimeofday\fP(3B),
|
|
\f4par\fP(7).
|
|
.SH BUGS
|
|
Only one instance of \f4padc\fP may be running at a time on a given system.
|
|
.PP
|
|
If one gets a trace from \f4padc\fP on a system with multiple cpus and
|
|
runs \f4par\fP on the data on a system with only one cpu, the cpu
|
|
id field won't be printed.
|