trace
PURPOSE
Starts the trace function.
SYNOPSIS
trace [ profile ]
DESCRIPTION
The trace command starts the trace function in the back-
ground. This trace function provides a base for debug-
ging the system. trace monitors the occurrence of
selected events in the system and records on disk impor-
tant data specific to each of these events. You can
format this output with the trcrpt command.
Any user or program that needs the trace process enabled
for debugging or error determination can start trace.
When starting trace, you must provide a profile. This
allows you to tailor the output of the trace session to
individual needs. The default profile is
/etc/trcprofile.
There may be more than one trace profile in the file
system at a time. The trace profile contains the classes
of events that you can select to trace, listed by event
class and by a descriptive label. See "Example" for a
sample profile. You may keep different profiles to trace
different combinations of event classes. trace also
takes additional information about the trace session from
the configuration file /etc/rasconf (see AIX Operating
System Technical Reference for a discussion of this
file). You set the name and size of the output file in
this configuration file.
In a multi-user environment, trace records all system
events, not just events at one virtual terminal.
FLAGS
-g filedes Indicates that this is a generic trace
session. Generic tracing applies only to
the VRM. In this type of session, events
to be recorded do not necessarily have a
fixed event class, but are allocated to a
temporary event channel by the trace device
driver, /de v/vrmtrace. Thus, starting a
generic trace does not require a trace
profile. Generic traces are started and
stopped by other processes, such as commu-
nications session managers. Therefore, the
interface to the daemon is somewhat dif-
ferent. The -g flag is useful only when
trace is started by another process.
The filedes parameter is a file descriptor
from the parent process. trace writes this
following information to this file
descriptor:
o The process ID of the trace demon
o The address of the trace buffer
o The size (in bytes) of the trace buffer
o The temporary channel bit allocated to
this event.
When tracing a generic event, the trace
demon does not record its process ID so
that it can be stopped by the trcstop
command. Thus, more than one trace demon
may be running at any time, but there may
be as many as seven traces in the system at
once (one normal trace and from one to six
generic traces).
Use the trc_start and trc_stop subroutines
to start and stop a generic trace.
-l Indicates that the VRM trace device driver
should log only the last buffer filled
before the trace demon stops. This flag is
valid only during a generic trace (-g).
-o name Specifies the name of the log file into
which the trace demon stores the trace
data. For generic traces (-g), this name
must be different from the default file
name specified in the configuration file
/etc/rasconf.
-n num Specifies the number of entries in the
trace buffer. trace multiplies this number
by the size of the entries (see the -s
flag) and uses the resulting value to size
the trace buffer. If you do not specify
this flag, trace uses the buffer size spec-
ified in the configuration file
/etc/rasconf.
-s size Specifies the size (in bytes) of the
entries that the trace demon will be han-
dling. The default size is 40 bytes. The
size can be no less than 20, which is the
number of bytes in the trace header for
each entry. All entries must be the same
size in a particular trace log file.
EXAMPLE
*****************************************************************************
* SYSTEM TRACE PROFILE
*****************************************************************************
* To set trace on for an event class, remove the comment mark (*) from the
* first column of the line containing the event you wish to trace.
* Add a comment mark (*) in the first column of lines containing event types
* you wish to stop tracing.
***** Event
* Type Description
***** Applications
***** AIX Extensions
* 36 Config
***** AIX System Calls
* 60 Shared Memory
* 61 Messages
* 62 Semaphores
* 63 Signals
* 64 Time
* 65 File System
* 66 File Handling
* 67 Directory Handling
* 68 Process
***** VRM Components
* 100 SVC Handler
* 110 Async/5080 Peripherals
* 112 Async/5080 Peripheral Interrupts
* 113 Virtual Terminal Manager
* 114 Keyboard Interrupts
* 115 Locator Interrupts
* 150 User-Defined Events
FILES
/etc/trcprofile Default profile.
/usr/adm/ras/trcfile Output file defined in
/etc/rasconf.
/etc/rasconf Configuration file.
RELATED INFORMATION
The following commands: "trcstop" and "trcrpt."
The rasconf configuration file in AIX Operating System
Technical Reference.
The discussion of trace in AIX Operating System Program-
ming Tools and Interfaces.