~ubuntu-branches/ubuntu/precise/manpages-posix/precise

.\" 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 .