1POSIX_TRACE_ATTR_GETINHERITEPDO(S3IPX)Programmer'sPMOaSnIuXa_lTRACE_ATTR_GETINHERITED(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy,
13 posix_trace_attr_getstreamfullpolicy, posix_trace_attr_setinherited,
14 posix_trace_attr_setlogfullpolicy, posix_trace_attr_setstreamfullpolicy
15 - retrieve and set the behavior of a trace stream (TRACING)
16
18 #include <trace.h>
19 int posix_trace_attr_getinherited(const trace_attr_t *restrict attr,
23 int *restrict inheritancepolicy);
24 int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict
27 attr,
28 int *restrict logpolicy);
29 int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *attr,
32 int *streampolicy);
33 int posix_trace_attr_setinherited(trace_attr_t *attr,
36 int inheritancepolicy);
37 int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr,
40 int logpolicy);
41 int posix_trace_attr_setstreamfullpolicy(trace_attr_t *attr,
44 int streampolicy);
45
48 The posix_trace_attr_getinherited() and posix_trace_attr_setinherited()
49 functions, respectively, shall get and set the inheritance policy
50 stored in the inheritance attribute for traced processes across the
51 fork() and spawn() operations. The inheritance attribute of the
52 attributes object pointed to by the attr argument shall be set to one
53 of the following values defined by manifest constants in the <trace.h>
54 header:
55 POSIX_TRACE_CLOSE_FOR_CHILD
57 After a fork() or spawn() operation, the child shall not be
59 traced, and tracing of the parent shall continue.
60 POSIX_TRACE_INHERITED
62 After a fork() or spawn() operation, if the parent is being
64 traced, its child shall be concurrently traced using the same
65 trace stream.
66 The default value for the inheritance attribute is
69 POSIX_TRACE_CLOSE_FOR_CHILD.
70 The posix_trace_attr_getlogfullpolicy() and posix_trace_attr_setlog‐
72 fullpolicy() functions, respectively, shall get and set the trace log
73 full policy stored in the log-full-policy attribute of the attributes
74 object pointed to by the attr argument.
75 The log-full-policy attribute shall be set to one of the following val‐
77 ues defined by manifest constants in the <trace.h> header:
78 POSIX_TRACE_LOOP
80 The trace log shall loop until the associated trace stream is
82 stopped. This policy means that when the trace log gets full,
83 the file system shall reuse the resources allocated to the old‐
84 est trace events that were recorded. In this way, the trace log
85 will always contain the most recent trace events flushed.
86 POSIX_TRACE_UNTIL_FULL
88 The trace stream shall be flushed to the trace log until the
90 trace log is full. This condition can be deduced from the
91 posix_log_full_status member status (see the posix_trace_sta‐
92 tus_info structure defined in <trace.h>). The last recorded
93 trace event shall be the POSIX_TRACE_STOP trace event.
94 POSIX_TRACE_APPEND
96 The associated trace stream shall be flushed to the trace log
98 without log size limitation. If the application specifies
99 POSIX_TRACE_APPEND, the implementation shall ignore the log-max-
100 size attribute.
101 The default value for the log-full-policy attribute is
104 POSIX_TRACE_LOOP.
105 The posix_trace_attr_getstreamfullpolicy() and posix_trace_attr_set‐
107 streamfullpolicy() functions, respectively, shall get and set the trace
108 stream full policy stored in the stream-full-policy attribute of the
109 attributes object pointed to by the attr argument.
110 The stream-full-policy attribute shall be set to one of the following
112 values defined by manifest constants in the <trace.h> header:
113 POSIX_TRACE_LOOP
115 The trace stream shall loop until explicitly stopped by the
117 posix_trace_stop() function. This policy means that when the
118 trace stream is full, the trace system shall reuse the resources
119 allocated to the oldest trace events recorded. In this way, the
120 trace stream will always contain the most recent trace events
121 recorded.
122 POSIX_TRACE_UNTIL_FULL
124 The trace stream will run until the trace stream resources are
126 exhausted. Then the trace stream will stop. This condition can
127 be deduced from posix_stream_status and posix_stream_full_status
128 (see the posix_trace_status_info structure defined in
129 <trace.h>). When this trace stream is read, a POSIX_TRACE_STOP
130 trace event shall be reported after reporting the last recorded
131 trace event. The trace system shall reuse the resources allo‐
132 cated to any trace events already reported-see the
133 posix_trace_getnext_event(), posix_trace_trygetnext_event(), and
134 posix_trace_timedgetnext_event() functions-or already flushed
135 for an active trace stream with log if the Trace Log option is
136 supported; see the posix_trace_flush() function. The trace sys‐
137 tem shall restart the trace stream when it is empty and may
138 restart it sooner. A POSIX_TRACE_START trace event shall be
139 reported before reporting the next recorded trace event.
140 POSIX_TRACE_FLUSH
142 If the Trace Log option is supported, this policy is identical
144 to the POSIX_TRACE_UNTIL_FULL trace stream full policy except
145 that the trace stream shall be flushed regularly as if
146 posix_trace_flush() had been explicitly called. Defining this
147 policy for an active trace stream without log shall be invalid.
148 The default value for the stream-full-policy attribute shall be
151 POSIX_TRACE_LOOP for an active trace stream without log.
152 If the Trace Log option is supported, the default value for the stream-
154 full-policy attribute shall be POSIX_TRACE_FLUSH for an active trace
155 stream with log.
156
158 Upon successful completion, these functions shall return a value of
159 zero. Otherwise, they shall return the corresponding error number.
160 If successful, the posix_trace_attr_getinherited() function shall store
162 the inheritance attribute value in the object pointed to by inheritan‐
163 cepolicy. Otherwise, the content of this object is undefined.
164 If successful, the posix_trace_attr_getlogfullpolicy() function shall
166 store the log-full-policy attribute value in the object pointed to by
167 logpolicy. Otherwise, the content of this object is undefined.
168 If successful, the posix_trace_attr_getstreamfullpolicy() function
170 shall store the stream-full-policy attribute value in the object
171 pointed to by streampolicy. Otherwise, the content of this object is
172 undefined.
173
175 These functions may fail if:
176 EINVAL The value specified by at least one of the arguments is invalid.
178 The following sections are informative.
181
183 None.
184
186 None.
187
189 None.
190
192 None.
193
195 fork(), posix_trace_attr_init(), posix_trace_create(),
196 posix_trace_flush(), posix_trace_get_attr(), posix_trace_get‐
197 next_event(), posix_trace_start(), posix_trace_timedgetnext_event(),
198 the Base Definitions volume of IEEE Std 1003.1-2001, <trace.h>
199
201 Portions of this text are reprinted and reproduced in electronic form
202 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
203 -- Portable Operating System Interface (POSIX), The Open Group Base
204 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
205 Electrical and Electronics Engineers, Inc and The Open Group. In the
206 event of any discrepancy between this version and the original IEEE and
207 The Open Group Standard, the original IEEE and The Open Group Standard
208 is the referee document. The original Standard can be obtained online
209 at http://www.opengroup.org/unix/online.html .
210IEEE/The Open Group 2003 POSIX_TRACE_ATTR_GETINHERITED(3P)