posix_trace_create_withlog Subroutine

Edit online

Purpose

Creates an active trace stream and associates it with a trace log.

Library

Posix Trace Library (libposixtrace.a)

Syntax

#include <sys/types.h>
#include <trace.h>

int posix_trace_create_withlog (pid, attr, file_desc, trid)
pid_t pid;
const trace_attr_t *restrict attr;
int file_desc;
trace_id_t *restrict trid;

Description

The posix_trace_create_withlog subroutine creates an active trace stream, as the posix_trace_create subroutine does, and associates the stream with a trace log.

The file_desc parameter must be the file descriptor designating the trace log destination. The subroutine fails if this file descriptor refers to a file opened with the O_APPEND flag or if this file descriptor refers to a file that is not regular.

The trid parameter points to the parameter where the posix_trace_create_withlog subroutine returns the trace stream identifier, which uniquely identifies the newly created trace stream. The trace stream identifier can be used in subsequent calls to control tracing. The trid parameter is only used by the following subroutines:
  • posix_trace_clear
  • posix_trace_eventid_equal
  • posix_trace_eventid_get_name
  • posix_trace_eventtypelist_getnext_id
  • posix_trace_eventtypelist_rewind
  • posix_trace_flush
  • posix_trace_get_attr
  • posix_trace_get_filter
  • posix_trace_get_status
  • posix_trace_set_filter
  • posix_trace_shutdown
  • posix_trace_start
  • posix_trace_stop
  • posix_trace_trid_eventid_open
Notice that the operations used by a trace analyzer process, such as the posix_trace_rewind or posix_trace_close subroutines, cannot be invoked using the trace stream identifier that is returned by the posix_trace_create_withlog subroutine.

For an active trace stream with log, when the posix_trace_shutdown subroutine is called, all trace events that have not been flushed to the trace log are flushed, as in the posix_trace_flush subroutine, and the trace log is closed.

When a trace log is closed, all the information that can be retrieved later from the trace log through the trace interface are written to the trace log. This information includes the trace attributes, the list of trace event types (with the mapping between trace event names and trace event type identifiers), and the trace status.

If the posix_trace_create_withlog subroutine is called with a non-initialized attributes object as parameter, the result is not specified.

Parameters

Item Description
pid Specifies the process ID of the traced process.
attr Specifies the trace attributes object.
file_desc Specifies the open file descriptor of the trace log.
trid Specifies the trace stream identifier.

Return Values

Upon successful completion, this subroutine returns a value of zero and stores the trace stream identifier value in the object pointed to by the trid parameter. Otherwise, it returns the corresponding error number.

Errors

Item Description
EAGAIN No more trace streams can be started now. The value of the TRACE_SYS_MAX has been exceeded.
EBADF The file_desc parameter is not a valid file descriptor open for writing.
EINVAL The attr parameter is null or the other parameters are invalid. The file_desc parameter refers to a file with a file type that does not support the log policy associated with the trace log.
ENOMEM No sufficient memory to create the trace stream with the specified parameters.
ENOSPC No space left on device. The device corresponding to the file_desc parameter does not contain the space required to create this trace log.
EPERM Does not have appropriate privilege to trace the process specified by the pid parameter.
ESRCH The pid parameter does not refer to an existing process.

Files

The trace.h and types.h files in the Files Reference