posix_trace_create Subroutine

Purpose

Creates an active trace stream.

Library

Posix Trace Library (libposixtrace.a)

Syntax

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

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

Description

The posix_trace_create subroutine creates an active trace stream. It allocates all of the resources needed by the trace stream being created for tracing the process specified by the pid parameter in accordance with the attr parameter.

The attr parameter represents the initial attributes of the trace stream and must be initialized by the posix_trace_attr_init subroutine before the posix_trace_create subroutine is called. If the attr parameter is NULL, the default attributes are used.

The attr attributes object can be manipulated through a set of subroutines described in the posix_trace_attr family of subroutines. If the attributes of the object pointed to by the attr parameter are modified later, the attributes of the trace stream are not affected.

The creation-time attribute of the newly created trace stream is set to the value of the CLOCK_REALTIME clock.

The pid parameter represents the target process to be traced. If the pid parameter is zero, the calling process is traced. If the process executing this subroutine does not have appropriate privileges to trace the process identified by pid, an error is returned.

The posix_trace_create subroutine stores the trace stream identifier of the new trace stream in the object pointed to by the trid parameter. This trace stream identifier can be used in subsequent calls to control tracing. The trid parameter is used only 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_get_attr
posix_trace_get_filter
posix_trace_get_status
posix_trace_getnext_event
posix_trace_set_filter
posix_trace_shutdown
posix_trace_start
posix_trace_stop
posix_trace_timedgetnext_event
posix_trace_trid_eventid_open
posix_trace_trygetnext_event

Notice that the operations normally 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 returned by the posix_trace_create subroutine.

A trace stream is created in a suspended state with an empty trace event type filter.

The posix_trace_create subroutine can be called multiple times from the same or different processes, with the system-wide limit indicated by the runtime invariant value TRACE_SYS_MAX, which has the minimum value _POSIX_TRACE_SYS_MAX.

The trace stream identifier returned by the posix_trace_create subroutine in the parameter pointed to by the trid parameter is valid only in the process that made the subroutine call. If it is used from another process, that is a child process, in subroutines defined in the IEEE Standard 1003.1-2001, these subroutines return with the EINVAL error.

If the posix_trace_create 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.
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.
EINVAL	The attr parameter is null or the other parameters are invalid.
ENOMEM	No sufficient memory to create the trace stream with the specified parameters.
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