Performance Management Guide

Starting and Controlling Trace from a Program

The trace facility can be started from a program, through a subroutine call. The subroutine is trcstart() and is in the librts.a library. The syntax of the trcstart() subroutine is as follows:

int trcstart(char *args)

where args is the options list that you would have entered for the trace command. By default, the system trace (channel 0) is started. If you want to start a generic trace, include a -g option in the args string. On successful completion, the trcstart() subroutine returns the channel ID. For generic tracing, this channel ID can be used to record to the private generic channel.

When compiling a program using this subroutine, the link to the librts.a library must be specifically requested (use -l rts as a compile option).

Controlling Trace with Trace Subroutine Calls

The controls for the trace routine are available as subroutines from the librts.a library. The subroutines return zero on successful completion. The subroutines are:

int trcon()

Begins or resumes collection of trace data.

int trcoff()

Suspends collection of trace data.

int trcstop()

Stops collection of trace data and terminates the trace routine.

Controlling Trace with ioctl() Calls

Each of the above subroutines for controlling trace performs the following tasks:

• Opens the trace control device (/dev/systrctl)
• Issues the appropriate ioctl() subroutine
• Closes the control device
• Returns to the calling program

To turn tracing on and off around individual sections of code, it may be more efficient for a program to issue the ioctl() controls directly. This method avoids the repetitive opening and closing of the trace control device. To use the ioctl() interface in a program, include sys/trcctl.h to define the ioctl() commands. The syntax of the ioctl() subroutine is as follows:

ioctl (fd, CMD, Channel)

where:

fd

is the file descriptor returned from opening /dev/systrctl

CMD

is one of: TRCON, TRCOFF, or TRCSTOP

Channel

is the trace channel (0 for system trace)

The following code example shows how to start a trace from a program and only trace around a specified section of code:

#include <fcntl.h>
#include <sys/trcctl.h>
extern int trcstart(char *arg);
char *ctl_dev ="/dev/systrctl";
int ctl_fd;
main()
{
     printf("configuring trace collection \n");
     if (trcstart("-ad")){
         perror("trcstart");
         exit(1);
     }
 
     printf("opening the trace device \n");
     if((ctl_fd =open (ctl_dev,O_RDWR))<0){
         perror("open ctl_dev");
         exit(1);
     }
 
     printf("turning data collection on \n");
     if(ioctl(ctl_fd,TRCON,0)){
         perror("TRCON");
         exit(1);
     }
 
     /* *** code here will be traced *** */
     printf("The code to print this line will be traced.");
 
     printf("turning data collection off\n");
     if (ioctl(ctl_fd,TRCOFF,0)){
         perror("TRCOFF");
         exit(1);
     }
 
     printf("stopping the trace daemon \n");
     if (trcstop(0)){
         perror("trcstop");
         exit(1);
     }
 
     exit(0);
}

Because no output file was specified in the parameter to the trcstart() subroutine, the output of the trace is in /var/adm/ras/trcfile, which is also the default input file of the trcrpt command.