Creates an active trace stream.
Posix Trace Library (libposixtrace.a)
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.
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.
Item | Description |
---|---|
pid | Specifies the process ID of the traced process. |
attr | Specifies the trace attributes object. |
trid | Specifies the trace stream identifier. |
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.
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. |