diff options
Diffstat (limited to 'man3p/posix_trace_attr_getinherited.3p')
| -rw-r--r-- | man3p/posix_trace_attr_getinherited.3p | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/man3p/posix_trace_attr_getinherited.3p b/man3p/posix_trace_attr_getinherited.3p new file mode 100644 index 000000000..d2d17f056 --- /dev/null +++ b/man3p/posix_trace_attr_getinherited.3p @@ -0,0 +1,228 @@ +.\" 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 . |