trc_start, trc_stop
Purpose
Starts and stops a trace daemon.
Library
Run-time Services Library (librts.a)
Syntax
#include <sys/trace.h>
trc_start (outpath, entsize, numents, lastonly, trcinfo)
char *outpath;
int entsize, numents, lastonly;
struct t_struct *trcinfo;
trc_stop (pid)
int pid;
Description
The trc_start subroutine starts a trace daemon process
when called from within a running application program.
This subroutine can be used to start an ordinary
(monitor) trace session or a VRM-specific generic trace
session. In a generic trace session, as many as seven
daemons can trace different devices simultaneously. In a
monitor trace session, only one daemon can run at any one
time since monitor trace classes are fixed. For informa-
tion about generic and monitor traces, see the trace
command in AIX Operating System Commands Reference.
The outpath parameter is a pointer to the path name of
the trace output file. For generic traces, the data from
each device can be saved in a separate file by specifying
a unique file name when starting each daemon. If the
outpath parameter is a NULL pointer, then the default
file name is used. The default file name is the value of
the file keyword in the /dev/trace stanza of the
/etc/rasconf file.
The entsize parameter indicates the size in bytes of each
trace entry that the application intends to send to the
VRM trace collector. If entsize is 0, then the default
entry size, 40 bytes, is used.
Warning: You must specify a file name in the outpath
parameter if the value of entsize is not 0, that is, if
you specify a trace entry size other than the default.
Failure to give a file name in this case results in unus-
able data if another trace daemon uses the default file
name.
The numents parameter indicates the maximum number of
entries to keep in the kernel's trace buffer. If numents
is 0, then the default value is used. The default number
of entries is the value of the buffer keyword in the
/dev/trace stanza of the /etc/rasconf file.
The lastonly parameter can have a value of 1, indicating
that only the last buffer of data is to be saved in the
trace file, or a value of 0, instructing the daemon to
save all data continuously.
The trcinfo parameter is a pointer to a t_struct struc-
ture into which the trc_start subroutine stores informa-
tion about the trace daemon that it starts. This
structure is defined in the sys/trace.h header file, and
it contains the following members:
t_PID The process ID of the daemon.
buff_addr The address of the trace buffer allocated in
the AIX kernel for use in a generic trace
session.
buff_len The size in bytes of the trace buffer allo-
cated in the AIX kernel.
channel_ID The bit mask to use in the traceid field
when recording trace data. This value is
the channel number shifted left 11 bits with
a hook ID of 0, as described in "trcunix."
The trc_stop subroutine kills a trace daemon process that
was started by trc_start. Its only parameter is the
process ID of the trace daemon, which trc_start provides
by storing it in trcinfo->t_PID.
Return Value
The trc_start subroutine returns a value of 0 upon suc-
cessful completion. If unsuccessful, then trc_start
returns the value of errno that was set by the failing
system call, and an error message is written to the
standard error output. trc_start can fail when it
invokes the pipe, fork, exec, or read system call.
The trc_stop subroutine returns 0 if successful, or -1 if
the kill system call fails.
Related Information
In this book: "trace_on," "trcunix," "rasconf," and
"trace."
The trace command in AIX Operating System Commands Refer-
ence.
The discussion about using the trace subroutines in AIX
Operating System Programming Tools and Interfaces.