mirror of https://github.com/mkerrisk/man-pages
229 lines
8.0 KiB
Plaintext
229 lines
8.0 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "POSIX_TRACE_ATTR_GETINHERITED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" posix_trace_attr_getinherited
|
||
|
.SH NAME
|
||
|
posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy,
|
||
|
posix_trace_attr_getstreamfullpolicy,
|
||
|
posix_trace_attr_setinherited, posix_trace_attr_setlogfullpolicy,
|
||
|
posix_trace_attr_setstreamfullpolicy \- retrieve and set the
|
||
|
behavior of a trace stream (\fBTRACING\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <trace.h>
|
||
|
.br
|
||
|
.sp
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBint posix_trace_attr_getinherited(const trace_attr_t *restrict\fP
|
||
|
\fIattr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ int *restrict\fP \fIinheritancepolicy\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBint posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict\fP
|
||
|
\fIattr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ int *restrict\fP \fIlogpolicy\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBint posix_trace_attr_getstreamfullpolicy(const trace_attr_t *\fP\fIattr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ int *\fP\fIstreampolicy\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBint posix_trace_attr_setinherited(trace_attr_t *\fP\fIattr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ int\fP \fIinheritancepolicy\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBint posix_trace_attr_setlogfullpolicy(trace_attr_t *\fP\fIattr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ int\fP \fIlogpolicy\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBint posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fP\fIattr\fP\fB,
|
||
|
.br
|
||
|
\ \ \ \ \ \ int\fP \fIstreampolicy\fP\fB); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIposix_trace_attr_getinherited\fP() and \fIposix_trace_attr_setinherited\fP()
|
||
|
functions, respectively, shall get and set
|
||
|
the inheritance policy stored in the \fIinheritance\fP attribute for
|
||
|
traced processes across the \fIfork\fP() and \fIspawn\fP() operations.
|
||
|
The \fIinheritance\fP attribute of the attributes object
|
||
|
pointed to by the \fIattr\fP argument shall be set to one of the following
|
||
|
values defined by manifest constants in the \fI<trace.h>\fP header:
|
||
|
.TP 7
|
||
|
POSIX_TRACE_CLOSE_FOR_CHILD
|
||
|
.sp
|
||
|
After a \fIfork\fP() or \fIspawn\fP() operation, the child shall not
|
||
|
be traced, and tracing
|
||
|
of the parent shall continue.
|
||
|
.TP 7
|
||
|
POSIX_TRACE_INHERITED
|
||
|
.sp
|
||
|
After a \fIfork\fP() or \fIspawn\fP() operation, if the parent is
|
||
|
being traced, its child
|
||
|
shall be concurrently traced using the same trace stream.
|
||
|
.sp
|
||
|
.LP
|
||
|
The default value for the \fIinheritance\fP attribute is POSIX_TRACE_CLOSE_FOR_CHILD.
|
||
|
.LP
|
||
|
The \fIposix_trace_attr_getlogfullpolicy\fP() and \fIposix_trace_attr_setlogfullpolicy\fP()
|
||
|
functions, respectively, shall get
|
||
|
and set the trace log full policy stored in the \fIlog-full-policy\fP
|
||
|
attribute of the attributes object pointed to by the
|
||
|
\fIattr\fP argument.
|
||
|
.LP
|
||
|
The \fIlog-full-policy\fP attribute shall be set to one of the following
|
||
|
values defined by manifest constants in the \fI<trace.h>\fP header:
|
||
|
.TP 7
|
||
|
POSIX_TRACE_LOOP
|
||
|
.sp
|
||
|
The trace log shall loop until the associated trace stream is stopped.
|
||
|
This policy means that when the trace log gets full, the
|
||
|
file system shall reuse the resources allocated to the oldest trace
|
||
|
events that were recorded. In this way, the trace log will
|
||
|
always contain the most recent trace events flushed.
|
||
|
.TP 7
|
||
|
POSIX_TRACE_UNTIL_FULL
|
||
|
.sp
|
||
|
The trace stream shall be flushed to the trace log until the trace
|
||
|
log is full. This condition can be deduced from the
|
||
|
\fIposix_log_full_status\fP member status (see the \fBposix_trace_status_info\fP
|
||
|
structure defined in \fI<trace.h>\fP). The last recorded trace event
|
||
|
shall be the POSIX_TRACE_STOP trace
|
||
|
event.
|
||
|
.TP 7
|
||
|
POSIX_TRACE_APPEND
|
||
|
.sp
|
||
|
The associated trace stream shall be flushed to the trace log without
|
||
|
log size limitation. If the application specifies
|
||
|
POSIX_TRACE_APPEND, the implementation shall ignore the \fIlog-max-size\fP
|
||
|
attribute.
|
||
|
.sp
|
||
|
.LP
|
||
|
The default value for the \fIlog-full-policy\fP attribute is POSIX_TRACE_LOOP.
|
||
|
.LP
|
||
|
The \fIposix_trace_attr_getstreamfullpolicy\fP() and \fIposix_trace_attr_setstreamfullpolicy\fP()
|
||
|
functions, respectively,
|
||
|
shall get and set the trace stream full policy stored in the \fIstream-full-policy\fP
|
||
|
attribute of the attributes object pointed
|
||
|
to by the \fIattr\fP argument.
|
||
|
.LP
|
||
|
The \fIstream-full-policy\fP attribute shall be set to one of the
|
||
|
following values defined by manifest constants in the \fI<trace.h>\fP
|
||
|
header:
|
||
|
.TP 7
|
||
|
POSIX_TRACE_LOOP
|
||
|
.sp
|
||
|
The trace stream shall loop until explicitly stopped by the \fIposix_trace_stop\fP()
|
||
|
function. This policy means that when the trace stream is full,
|
||
|
the trace system shall reuse the resources allocated to the oldest
|
||
|
trace events recorded. In this way, the trace stream will always
|
||
|
contain the most recent trace events recorded.
|
||
|
.TP 7
|
||
|
POSIX_TRACE_UNTIL_FULL
|
||
|
.sp
|
||
|
The trace stream will run until the trace stream resources are exhausted.
|
||
|
Then the trace stream will stop. This condition can be
|
||
|
deduced from \fIposix_stream_status\fP and \fIposix_stream_full_status\fP
|
||
|
(see the \fBposix_trace_status_info\fP structure
|
||
|
defined in \fI<trace.h>\fP). When this trace stream is read, a POSIX_TRACE_STOP
|
||
|
trace
|
||
|
event shall be reported after reporting the last recorded trace event.
|
||
|
The trace system shall reuse the resources allocated to any
|
||
|
trace events already reported-see the \fIposix_trace_getnext_event\fP(),
|
||
|
\fIposix_trace_trygetnext_event\fP(), and \fIposix_trace_timedgetnext_event\fP()
|
||
|
functions-or already flushed for an
|
||
|
active trace stream with log if the Trace Log option is supported;
|
||
|
see the \fIposix_trace_flush\fP() function. The trace system shall
|
||
|
restart the trace stream when
|
||
|
it is empty and may restart it sooner. A POSIX_TRACE_START trace event
|
||
|
shall be reported before reporting the next recorded trace
|
||
|
event.
|
||
|
.TP 7
|
||
|
POSIX_TRACE_FLUSH
|
||
|
.sp
|
||
|
If the Trace Log option is supported, this policy is identical to
|
||
|
the POSIX_TRACE_UNTIL_FULL trace stream full policy except that
|
||
|
the trace stream shall be flushed regularly as if \fIposix_trace_flush\fP()
|
||
|
had
|
||
|
been explicitly called. Defining this policy for an active trace stream
|
||
|
without log shall be invalid.
|
||
|
.sp
|
||
|
.LP
|
||
|
The default value for the \fIstream-full-policy\fP attribute shall
|
||
|
be POSIX_TRACE_LOOP for an active trace stream without
|
||
|
log.
|
||
|
.LP
|
||
|
If the Trace Log option is supported, the default value for the \fIstream-full-policy\fP
|
||
|
attribute shall be POSIX_TRACE_FLUSH for
|
||
|
an active trace stream with log.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, these functions shall return a value of
|
||
|
zero. Otherwise, they shall return the corresponding error
|
||
|
number.
|
||
|
.LP
|
||
|
If successful, the \fIposix_trace_attr_getinherited\fP() function
|
||
|
shall store the \fIinheritance\fP attribute value in the object
|
||
|
pointed to by \fIinheritancepolicy\fP. Otherwise, the content of this
|
||
|
object is undefined.
|
||
|
.LP
|
||
|
If successful, the \fIposix_trace_attr_getlogfullpolicy\fP() function
|
||
|
shall store the \fIlog-full-policy\fP attribute value in
|
||
|
the object pointed to by \fIlogpolicy\fP. Otherwise, the content of
|
||
|
this object is undefined.
|
||
|
.LP
|
||
|
If successful, the \fIposix_trace_attr_getstreamfullpolicy\fP() function
|
||
|
shall store the \fIstream-full-policy\fP attribute
|
||
|
value in the object pointed to by \fIstreampolicy\fP. Otherwise, the
|
||
|
content of this object is undefined.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
These functions may fail if:
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The value specified by at least one of the arguments is invalid.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIfork\fP() , \fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP()
|
||
|
, \fIposix_trace_flush\fP() , \fIposix_trace_get_attr\fP() , \fIposix_trace_getnext_event\fP()
|
||
|
, \fIposix_trace_start\fP() , \fIposix_trace_timedgetnext_event\fP()
|
||
|
, the Base Definitions volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<trace.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|