posix_trace_shutdown Subroutine

Purpose

Shuts down a trace stream.

Library

Posix Trace Library (libposixtrace.a)

Syntax

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

int posix_trace_shutdown (trid)
trace_id_t trid;

Description

The posix_trace_shutdown subroutine stops the tracing of trace events in the trace stream identified by the trid parameter, as if the posix_trace_stop subroutine had been invoked. The posix_trace_shutdown subroutine frees all the resources associated with the trace stream.

The posix_trace_shutdown subroutine does not return until all the resources associated with the trace stream have been freed. When the posix_trace_shutdown subroutine returns, the trid parameter becomes an invalid trace stream identifier. A call to this subroutine deallocates the resources regardless of whether all trace events have been retrieved by the analyzer process. Any thread blocked on the posix_trace_getnext_event, posix_trace_timedgetnext_event or the posix_trace_trygetnext_event subroutines before this call is unblocked and the EINVAL error is returned.

The trace streams are automatically shut down when the processes that create them start any subroutines of the exec subroutines, or when the processes are terminated.

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.

The posix_trace_shutdown subroutine does not return until all trace events have been flushed.

Parameters

Item Description
trid Specifies the trace stream identifier.

Return Values

Upon successful completion, this subroutine returns a value of zero. Otherwise, it returns the corresponding error number.

Errors

Item Description
EINVAL The value of the trid parameter does not correspond to an active trace stream with log.
ENOSPC No space left on device.

Files

The trace.h and types.h files in AIX® Version 7.1 Files Reference