path: root/man-pages-posix-2017/man3p/posix_trace_attr_getinherited.3p

'\" et
.TH POSIX_TRACE_ATTR_GETINHERITED "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
.ad l
posix_trace_attr_getinherited,
posix_trace_attr_getlogfullpolicy,
posix_trace_attr_getstreamfullpolicy,
posix_trace_attr_setinherited,
posix_trace_attr_setlogfullpolicy,
posix_trace_attr_setstreamfullpolicy
\(em retrieve and set the behavior of a trace stream
(\fBTRACING\fP)
.ad b
.SH SYNOPSIS
.LP
.nf
#include <trace.h>
.P
int posix_trace_attr_getinherited(const trace_attr_t *restrict \fIattr\fP,
    int *restrict \fIinheritancepolicy\fP);
int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict \fIattr\fP,
    int *restrict \fIlogpolicy\fP);
int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict
    \fIattr\fP, int *restrict \fIstreampolicy\fP);
int posix_trace_attr_setinherited(trace_attr_t *\fIattr\fP,
    int \fIinheritancepolicy\fP);
int posix_trace_attr_setlogfullpolicy(trace_attr_t *\fIattr\fP,
    int \fIlogpolicy\fP);
int posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fIattr\fP,
    int \fIstreampolicy\fP);
.fi
.SH DESCRIPTION
The
\fIposix_trace_attr_getinherited\fR()
and
\fIposix_trace_attr_setinherited\fR()
functions, respectively, shall get and set the inheritance policy
stored in the
.IR inheritance
attribute for traced processes across the
\fIfork\fR()
and
\fIspawn\fR()
operations. The
.IR inheritance
attribute of the attributes object pointed to by the
.IR attr
argument shall be set to one of the following values defined by
manifest constants in the
.IR <trace.h> 
header:
.IP POSIX_TRACE_CLOSE_FOR_CHILD 6
.br
After a
\fIfork\fR()
or
\fIspawn\fR()
operation, the child shall not be traced, and tracing of the parent
shall continue.
.IP POSIX_TRACE_INHERITED 6
.br
After a
\fIfork\fR()
or
\fIspawn\fR()
operation, if the parent is being traced, its child shall be
concurrently traced using the same trace stream.
.P
The default value for the
.IR inheritance
attribute is POSIX_TRACE_CLOSE_FOR_CHILD.
.P
The
\fIposix_trace_attr_getlogfullpolicy\fR()
and
\fIposix_trace_attr_setlogfullpolicy\fR()
functions, respectively, shall get and set the trace log full policy
stored in the
.IR log-full-policy
attribute of the attributes object pointed to by the
.IR attr
argument.
.P
The
.IR log-full-policy
attribute shall be set to one of the following values defined by
manifest constants in the
.IR <trace.h> 
header:
.IP POSIX_TRACE_LOOP 6
.br
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.
.IP POSIX_TRACE_UNTIL_FULL 6
.br
The trace stream shall be flushed to the trace log until the trace log
is full. This condition can be deduced from the
.IR posix_log_full_status
member status (see the
.BR posix_trace_status_info
structure defined in
.IR <trace.h> ).
The last recorded trace event shall be the POSIX_TRACE_STOP trace event.
.IP POSIX_TRACE_APPEND 6
.br
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
.IR log-max-size
attribute.
.P
The default value for the
.IR log-full-policy
attribute is POSIX_TRACE_LOOP.
.P
The
\fIposix_trace_attr_getstreamfullpolicy\fR()
and
\fIposix_trace_attr_setstreamfullpolicy\fR()
functions, respectively, shall get and set the trace stream full policy
stored in the
.IR stream-full-policy
attribute of the attributes object pointed to by the
.IR attr
argument.
.P
The
.IR stream-full-policy
attribute shall be set to one of the following values defined by
manifest constants in the
.IR <trace.h> 
header:
.IP POSIX_TRACE_LOOP 6
.br
The trace stream shall loop until explicitly stopped by the
\fIposix_trace_stop\fR()
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.
.IP POSIX_TRACE_UNTIL_FULL 6
.br
The trace stream will run until the trace stream resources are
exhausted. Then the trace stream will stop. This condition can be
deduced from
.IR posix_stream_status
and
.IR posix_stream_full_status
(see the
.BR posix_trace_status_info
structure defined in
.IR <trace.h> ).
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\(emsee the
\fIposix_trace_getnext_event\fR(),
\fIposix_trace_trygetnext_event\fR(),
and
\fIposix_trace_timedgetnext_event\fR()
functions\(emor already flushed for an active trace stream with log if
the Trace Log option is supported; see the
\fIposix_trace_flush\fR()
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.
.IP POSIX_TRACE_FLUSH 6
.br
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\fR()
had been explicitly called. Defining this policy for an active trace
stream without log shall be invalid.
.P
The default value for the
.IR stream-full-policy
attribute shall be POSIX_TRACE_LOOP for an active trace stream without
log.
.P
If the Trace Log option is supported, the default value for the
.IR stream-full-policy
attribute shall be POSIX_TRACE_FLUSH for an active trace stream with
log.
.SH "RETURN VALUE"
Upon successful completion, these functions shall return a value of
zero. Otherwise, they shall return the corresponding error number.
.P
If successful, the
\fIposix_trace_attr_getinherited\fR()
function shall store the
.IR inheritance
attribute value in the object pointed to by
.IR inheritancepolicy .
Otherwise, the content of this object is undefined.
.P
If successful, the
\fIposix_trace_attr_getlogfullpolicy\fR()
function shall store the
.IR log-full-policy
attribute value in the object pointed to by
.IR logpolicy .
Otherwise, the content of this object is undefined.
.P
If successful, the
\fIposix_trace_attr_getstreamfullpolicy\fR()
function shall store the
.IR stream-full-policy
attribute value in the object pointed to by
.IR streampolicy .
Otherwise, the content of this object is undefined.
.SH ERRORS
These functions may fail if:
.TP
.BR EINVAL
The value specified by at least one of the arguments is invalid.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
None.
.SH "FUTURE DIRECTIONS"
The following functions:
.sp
.RS
.nf
\fIposix_trace_attr_getinherited\fR()
\fIposix_trace_attr_getlogfullpolicy\fR()
\fIposix_trace_attr_getstreamfullpolicy\fR()
\fIposix_trace_attr_setinherited\fR()
\fIposix_trace_attr_setlogfullpolicy\fR()
\fIposix_trace_attr_setstreamfullpolicy\fR()
.fi
.RE
.P
may be removed in a future version.
.SH "SEE ALSO"
.ad l
.IR "\fIfork\fR\^(\|)",
.IR "\fIposix_trace_attr_destroy\fR\^(\|)",
.IR "\fIposix_trace_create\fR\^(\|)",
.IR "\fIposix_trace_get_attr\fR\^(\|)",
.IR "\fIposix_trace_getnext_event\fR\^(\|)",
.IR "\fIposix_trace_start\fR\^(\|)"
.ad b
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<trace.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .