man3p/posix_trace_attr_getinherited.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "POSIX_TRACE_ATTR_GETINHERITED" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" posix_trace_attr_getinherited
   4 .SH NAME
   5 posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy,
   6 posix_trace_attr_getstreamfullpolicy,
   7 posix_trace_attr_setinherited, posix_trace_attr_setlogfullpolicy,
   8 posix_trace_attr_setstreamfullpolicy \- retrieve and set the
   9 behavior of a trace stream (\fBTRACING\fP)
  10 .SH SYNOPSIS
  11 .LP
  12 \fB#include <trace.h>
  13 .br
  14 .sp
  15 \fP
  16 .LP
  17 \fBint posix_trace_attr_getinherited(const trace_attr_t *restrict\fP
  18 \fIattr\fP\fB,
  19 .br
  20 \ \ \ \ \ \  int *restrict\fP \fIinheritancepolicy\fP\fB);
  21 .br
  22 \fP
  23 .LP
  24 \fBint posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict\fP
  25 \fIattr\fP\fB,
  26 .br
  27 \ \ \ \ \ \  int *restrict\fP \fIlogpolicy\fP\fB);
  28 .br
  29 \fP
  30 .LP
  31 \fBint posix_trace_attr_getstreamfullpolicy(const trace_attr_t *\fP\fIattr\fP\fB,
  32 .br
  33 \ \ \ \ \ \  int *\fP\fIstreampolicy\fP\fB);
  34 .br
  35 \fP
  36 .LP
  37 \fBint posix_trace_attr_setinherited(trace_attr_t *\fP\fIattr\fP\fB,
  38 .br
  39 \ \ \ \ \ \  int\fP \fIinheritancepolicy\fP\fB);
  40 .br
  41 \fP
  42 .LP
  43 \fBint posix_trace_attr_setlogfullpolicy(trace_attr_t *\fP\fIattr\fP\fB,
  44 .br
  45 \ \ \ \ \ \  int\fP \fIlogpolicy\fP\fB);
  46 .br
  47 \fP
  48 .LP
  49 \fBint posix_trace_attr_setstreamfullpolicy(trace_attr_t *\fP\fIattr\fP\fB,
  50 .br
  51 \ \ \ \ \ \  int\fP \fIstreampolicy\fP\fB); \fP
  52 \fB
  53 .br
  54 \fP
  55 .SH DESCRIPTION
  56 .LP
  57 The \fIposix_trace_attr_getinherited\fP() and \fIposix_trace_attr_setinherited\fP()
  58 functions, respectively, shall get and set
  59 the inheritance policy stored in the \fIinheritance\fP attribute for
  60 traced processes across the \fIfork\fP() and \fIspawn\fP() operations.
  61 The \fIinheritance\fP attribute of the attributes object
  62 pointed to by the \fIattr\fP argument shall be set to one of the following
  63 values defined by manifest constants in the \fI<trace.h>\fP header:
  64 .TP 7
  65 POSIX_TRACE_CLOSE_FOR_CHILD
  66 .sp
  67 After a \fIfork\fP() or \fIspawn\fP() operation, the child shall not
  68 be traced, and tracing
  69 of the parent shall continue.
  70 .TP 7
  71 POSIX_TRACE_INHERITED
  72 .sp
  73 After a \fIfork\fP() or \fIspawn\fP() operation, if the parent is
  74 being traced, its child
  75 shall be concurrently traced using the same trace stream.
  76 .sp
  77 .LP
  78 The default value for the \fIinheritance\fP attribute is POSIX_TRACE_CLOSE_FOR_CHILD.
  79 .LP
  80 The \fIposix_trace_attr_getlogfullpolicy\fP() and \fIposix_trace_attr_setlogfullpolicy\fP()
  81 functions, respectively, shall get
  82 and set the trace log full policy stored in the \fIlog-full-policy\fP
  83 attribute of the attributes object pointed to by the
  84 \fIattr\fP argument.
  85 .LP
  86 The \fIlog-full-policy\fP attribute shall be set to one of the following
  87 values defined by manifest constants in the \fI<trace.h>\fP header:
  88 .TP 7
  89 POSIX_TRACE_LOOP
  90 .sp
  91 The trace log shall loop until the associated trace stream is stopped.
  92 This policy means that when the trace log gets full, the
  93 file system shall reuse the resources allocated to the oldest trace
  94 events that were recorded. In this way, the trace log will
  95 always contain the most recent trace events flushed.
  96 .TP 7
  97 POSIX_TRACE_UNTIL_FULL
  98 .sp
  99 The trace stream shall be flushed to the trace log until the trace
 100 log is full. This condition can be deduced from the
 101 \fIposix_log_full_status\fP member status (see the \fBposix_trace_status_info\fP
 102 structure defined in \fI<trace.h>\fP). The last recorded trace event
 103 shall be the POSIX_TRACE_STOP trace
 104 event.
 105 .TP 7
 106 POSIX_TRACE_APPEND
 107 .sp
 108 The associated trace stream shall be flushed to the trace log without
 109 log size limitation. If the application specifies
 110 POSIX_TRACE_APPEND, the implementation shall ignore the \fIlog-max-size\fP
 111 attribute.
 112 .sp
 113 .LP
 114 The default value for the \fIlog-full-policy\fP attribute is POSIX_TRACE_LOOP.
 115 .LP
 116 The \fIposix_trace_attr_getstreamfullpolicy\fP() and \fIposix_trace_attr_setstreamfullpolicy\fP()
 117 functions, respectively,
 118 shall get and set the trace stream full policy stored in the \fIstream-full-policy\fP
 119 attribute of the attributes object pointed
 120 to by the \fIattr\fP argument.
 121 .LP
 122 The \fIstream-full-policy\fP attribute shall be set to one of the
 123 following values defined by manifest constants in the \fI<trace.h>\fP
 124 header:
 125 .TP 7
 126 POSIX_TRACE_LOOP
 127 .sp
 128 The trace stream shall loop until explicitly stopped by the \fIposix_trace_stop\fP()
 129 function. This policy means that when the trace stream is full,
 130 the trace system shall reuse the resources allocated to the oldest
 131 trace events recorded. In this way, the trace stream will always
 132 contain the most recent trace events recorded.
 133 .TP 7
 134 POSIX_TRACE_UNTIL_FULL
 135 .sp
 136 The trace stream will run until the trace stream resources are exhausted.
 137 Then the trace stream will stop. This condition can be
 138 deduced from \fIposix_stream_status\fP and \fIposix_stream_full_status\fP
 139 (see the \fBposix_trace_status_info\fP structure
 140 defined in \fI<trace.h>\fP). When this trace stream is read, a POSIX_TRACE_STOP
 141 trace
 142 event shall be reported after reporting the last recorded trace event.
 143 The trace system shall reuse the resources allocated to any
 144 trace events already reported-see the \fIposix_trace_getnext_event\fP(),
 145 \fIposix_trace_trygetnext_event\fP(), and \fIposix_trace_timedgetnext_event\fP()
 146 functions-or already flushed for an
 147 active trace stream with log if the Trace Log option is supported;
 148 see the \fIposix_trace_flush\fP() function. The trace system shall
 149 restart the trace stream when
 150 it is empty and may restart it sooner. A POSIX_TRACE_START trace event
 151 shall be reported before reporting the next recorded trace
 152 event.
 153 .TP 7
 154 POSIX_TRACE_FLUSH
 155 .sp
 156 If the Trace Log option is supported, this policy is identical to
 157 the POSIX_TRACE_UNTIL_FULL trace stream full policy except that
 158 the trace stream shall be flushed regularly as if \fIposix_trace_flush\fP()
 159 had
 160 been explicitly called. Defining this policy for an active trace stream
 161 without log shall be invalid.
 162 .sp
 163 .LP
 164 The default value for the \fIstream-full-policy\fP attribute shall
 165 be POSIX_TRACE_LOOP for an active trace stream without
 166 log.
 167 .LP
 168 If the Trace Log option is supported, the default value for the \fIstream-full-policy\fP
 169 attribute shall be POSIX_TRACE_FLUSH for
 170 an active trace stream with log.
 171 .SH RETURN VALUE
 172 .LP
 173 Upon successful completion, these functions shall return a value of
 174 zero. Otherwise, they shall return the corresponding error
 175 number.
 176 .LP
 177 If successful, the \fIposix_trace_attr_getinherited\fP() function
 178 shall store the \fIinheritance\fP attribute value in the object
 179 pointed to by \fIinheritancepolicy\fP. Otherwise, the content of this
 180 object is undefined.
 181 .LP
 182 If successful, the \fIposix_trace_attr_getlogfullpolicy\fP() function
 183 shall store the \fIlog-full-policy\fP attribute value in
 184 the object pointed to by \fIlogpolicy\fP. Otherwise, the content of
 185 this object is undefined.
 186 .LP
 187 If successful, the \fIposix_trace_attr_getstreamfullpolicy\fP() function
 188 shall store the \fIstream-full-policy\fP attribute
 189 value in the object pointed to by \fIstreampolicy\fP. Otherwise, the
 190 content of this object is undefined.
 191 .SH ERRORS
 192 .LP
 193 These functions may fail if:
 194 .TP 7
 195 .B EINVAL
 196 The value specified by at least one of the arguments is invalid.
 197 .sp
 198 .LP
 199 \fIThe following sections are informative.\fP
 200 .SH EXAMPLES
 201 .LP
 202 None.
 203 .SH APPLICATION USAGE
 204 .LP
 205 None.
 206 .SH RATIONALE
 207 .LP
 208 None.
 209 .SH FUTURE DIRECTIONS
 210 .LP
 211 None.
 212 .SH SEE ALSO
 213 .LP
 214 \fIfork\fP() , \fIposix_trace_attr_init\fP() , \fIposix_trace_create\fP()
 215 , \fIposix_trace_flush\fP() , \fIposix_trace_get_attr\fP() , \fIposix_trace_getnext_event\fP()
 216 , \fIposix_trace_start\fP() , \fIposix_trace_timedgetnext_event\fP()
 217 , the Base Definitions volume of
 218 IEEE\ Std\ 1003.1-2001, \fI<trace.h>\fP
 219 .SH COPYRIGHT
 220 Portions of this text are reprinted and reproduced in electronic form
 221 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 222 -- Portable Operating System Interface (POSIX), The Open Group Base
 223 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 224 Electrical and Electronics Engineers, Inc and The Open Group. In the
 225 event of any discrepancy between this version and the original IEEE and
 226 The Open Group Standard, the original IEEE and The Open Group Standard
 227 is the referee document. The original Standard can be obtained online at
 228 http://www.opengroup.org/unix/online.html .