trc_open Subroutine

Purpose

Opens a trace log object.

Library

libtrace.a

Syntax

#include <sys/libtrace.h>

int trc_open (log_object_name, template_file_name, type, handlep)
char *log_object_name, template_file_name;
int type;
trc_log_handle_t *handlep;

Description

The trc_open subroutine opens a trace log object. A log object may only be opened for reading.

Two object types are supported, raw and processed. As their names imply, a raw object consists of the raw trace data as it was traced. A processed object consists of data as processed by a trace formatting template file such as the /etc/trcfmt file.

Parameters

Item Description
log_object_name Specifies the log object to be opened. If this is NULL or an empty string, the default log object, /var/adm/ras/trcfile, is opened. If it is a dash, the input is read from standard input. In this case, the file must be a sequential trace file such as one produced by the trcrpt -r command, the -o trace option, or the trcdead command.

If the file is the base file for a multi-CPU trace, the trace events are merged by the trcrpt command, unless the TRC_NOTEMPLATES option was specified. Also, if the file is a single CPU's trace file, it is treated as a single log file.

If multiple files are specified for merging, the TRC_MULTI_MERGE option must be specified. Each file must be separated from the previous one by a colon. For example, merging 3 files (f1, f2 and f3) is accomplished by setting the log_object_name parameter to f1:f2:f3.
template_file_name This names the template file. The template file is used if the TRC_LOGPROC type is specified. If NULL, /etc/trcfmt (the default template file) is used. The template file specification is ignored if the TRC_NOTEMPLATES option is specified.
type Consists of flag bits OR'd together. One open type and one object type flag must be specified.
The following is the open type flag:
TRC_LOGREAD
Open for reading
The following are the object type flags:
TRC_LOGRAW
Specifies that raw trace data is to be read. This data is defined in Debug and Performance Tracing and in the /etc/trcfmt file.
TRC_LOGPROC
This processes a raw trace log file, one produced by the trace command, using either the trace templates found in the /etc/trcfmt file, or the template file specified by the template_file_name parameter on the trc_open command.
The following are the modifier type flags:
TRC_LOGVERBATIM
Returns the file data verbatim, exactly as traced. This is how trcrpt -r returns data. See also the TRC_NOTEMPLATES modifier.
TRC_LIBDEBUG
Turns on debug mode. This is for IBM® customer support use only.
TRC_LOGLIVE
The data returned in the trc_read_t structure is not a unique copy, it is live data. Such data may only be used until the next retrieval API operation. It is not necessary to call the trc_free subroutine to free such data. The TRC_LOGLIVE modifier is used to improve performance when the data read does not need to be retained.
TRC_RETAIN_HANDLE
Don't free the handle after an open failure. This allows errors to be processed by the trc_perror or trc_strerror subroutines. The trc_close subroutine must be used to free the file handle.
TRC_NOTEMPLATES
Ignore any template file. This is used with the TRC_LOGRAW object flag to prevent any template processing, such as merging multi-CPU trace files. When used in conjunction with the TRC_LOGVERBATIM flag, it causes the retrieval API to return the same data reported with trcrpt -r.
TRC_MULTI_MERGE
Perform a merge operation on the files specified. Multiple files must be specified.
TRC_REMOVE_DUPS
If set, duplicate entries are eliminated when possible. Duplicate entries can only be detected when the CPU ID is known from the trace entry itself, not when it must be inferred. You can find out what the CPU ID is from the following trace sources:
  • A lightweight memory trace
  • A multi-processor system trace (For example, use trace -C all.)
  • A 64-bit system trace initiated with the -p option
  • A 64-bit component trace
This flag is valid only when TRC_MULTI_MERGE is specified.
handlep Points to the handle returned from a successful call to the trc_open subroutine.

Return Values

Upon successful completion, the trc_open subroutine returns a 0 and puts the trace log object handle into the memory pointed to by the handlep parameter.

Error Codes

Upon error, the trc_open subroutine sets the errno global variable to a value in the errno.h file, and returns either an errno.h value, or an error value defined in the libtrace.h file.
Item Description
EINVAL Invalid parameter.
ENOMEM Cannot allocate memory.
TRCE_BADFORMAT The file is not a valid trace file, and errno is set to EINVAL.
TRCE_WARN The template file contains errors. The errno global variable is set to EINVAL if TRCE_TMPLTFORMAT is returned. If TRCE_WARN is returned, the open succeeded.
TRCE_TMPLTFORMAT The template file contains errors. The errno global variable is set to EINVAL if TRCE_TMPLTFORMAT is returned. If TRCE_WARN is returned, the open succeeded.
TRCE_TOOMANY An internal limit is exceeded. The errno global variable is set to ENOMEM in this case.