1POSIX_TRACE_CREATE(P) POSIX Programmer's Manual POSIX_TRACE_CREATE(P)
2
6 posix_trace_create, posix_trace_create_withlog, posix_trace_flush,
7 posix_trace_shutdown - trace stream initialization, flush, and shutdown
8 from a process (TRACING)
9
11 #include <sys/types.h>
12 #include <trace.h>
13 int posix_trace_create(pid_t pid,
15 const trace_attr_t *restrict attr,
16 trace_id_t *restrict trid);
17 int posix_trace_create_withlog(pid_t pid,
20 const trace_attr_t *restrict attr, int file_desc,
21 trace_id_t *restrict trid);
22 int posix_trace_flush(trace_id_t trid);
23 int posix_trace_shutdown(trace_id_t trid);
26
29 The posix_trace_create() function shall create an active trace stream.
30 It allocates all the resources needed by the trace stream being created
31 for tracing the process specified by pid in accordance with the attr
32 argument. The attr argument represents the initial attributes of the
33 trace stream and shall have been initialized by the function
34 posix_trace_attr_init() prior to the posix_trace_create() call. If the
35 argument attr is NULL, the default attributes shall be used. The attr
36 attributes object shall be manipulated through a set of functions
37 described in the posix_trace_attr family of functions. If the
38 attributes of the object pointed to by attr are modified later, the
39 attributes of the trace stream shall not be affected. The creation-time
40 attribute of the newly created trace stream shall be set to the value
41 of the system clock, if the Timers option is not supported, or to the
42 value of the CLOCK_REALTIME clock, if the Timers option is supported.
43 The pid argument represents the target process to be traced. If the
45 process executing this function does not have appropriate privileges to
46 trace the process identified by pid, an error shall be returned. If the
47 pid argument is zero, the calling process shall be traced.
48 The posix_trace_create() function shall store the trace stream identi‐
50 fier of the new trace stream in the object pointed to by the trid argu‐
51 ment. This trace stream identifier shall be used in subsequent calls to
52 control tracing. The trid argument may only be used by the following
53 functions:
54 posix_trace_clear() posix_trace_getnext_event()
56 posix_trace_eventid_equal() posix_trace_shutdown()
57 posix_trace_eventid_get_name() posix_trace_start()
58 posix_trace_eventtypelist_getnext_id() posix_trace_stop()
59 posix_trace_eventtypelist_rewind() posix_trace_timedgetnext_event()
60 posix_trace_get_attr() posix_trace_trid_eventid_open()
61 posix_trace_get_status() posix_trace_trygetnext_event()
62 If the Trace Event Filter option is supported, the following additional
65 functions may use the trid argument:
66 posix_trace_get_filter() posix_trace_set_filter()
68 In particular, notice that the operations normally used by a trace ana‐
70 lyzer process, such as posix_trace_rewind() or posix_trace_close(),
71 cannot be invoked using the trace stream identifier returned by the
72 posix_trace_create() function.
73 A trace stream shall be created in a suspended state. If the Trace
75 Event Filter option is supported, its trace event type filter shall be
76 empty.
77 The posix_trace_create() function may be called multiple times from the
79 same or different processes, with the system-wide limit indicated by
80 the runtime invariant value {TRACE_SYS_MAX}, which has the minimum
81 value {_POSIX_TRACE_SYS_MAX}.
82 The trace stream identifier returned by the posix_trace_create() func‐
84 tion in the argument pointed to by trid is valid only in the process
85 that made the function call. If it is used from another process, that
86 is a child process, in functions defined in IEEE Std 1003.1-2001, these
87 functions shall return with the error [EINVAL].
88 The posix_trace_create_withlog() function shall be equivalent to
90 posix_trace_create(), except that it associates a trace log with this
91 stream. The file_desc argument shall be the file descriptor designating
92 the trace log destination. The function shall fail if this file
93 descriptor refers to a file with a file type that is not compatible
94 with the log policy associated with the trace log. The list of the
95 appropriate file types that are compatible with each log policy is
96 implementation-defined.
97 The posix_trace_create_withlog() function shall return in the parameter
99 pointed to by trid the trace stream identifier, which uniquely identi‐
100 fies the newly created trace stream, and shall be used in subsequent
101 calls to control tracing. The trid argument may only be used by the
102 following functions:
103 posix_trace_clear() posix_trace_getnext_event()
105 posix_trace_eventid_equal() posix_trace_shutdown()
106 posix_trace_eventid_get_name() posix_trace_start()
107 posix_trace_eventtypelist_getnext_id() posix_trace_stop()
108 posix_trace_eventtypelist_rewind() posix_trace_timedgetnext_event()
109 posix_trace_flush() posix_trace_trid_eventid_open()
110 posix_trace_get_attr() posix_trace_trygetnext_event()
111 posix_trace_get_status()
112 If the Trace Event Filter option is supported, the following additional
115 functions may use the trid argument:
116 posix_trace_get_filter() posix_trace_set_filter()
118 In particular, notice that the operations normally used by a trace ana‐
120 lyzer process, such as posix_trace_rewind() or posix_trace_close(),
121 cannot be invoked using the trace stream identifier returned by the
122 posix_trace_create_withlog() function.
123 The posix_trace_flush() function shall initiate a flush operation which
125 copies the contents of the trace stream identified by the argument trid
126 into the trace log associated with the trace stream at the creation
127 time. If no trace log has been associated with the trace stream pointed
128 to by trid, this function shall return an error. The termination of the
129 flush operation can be polled by the posix_trace_get_status() function.
130 During the flush operation, it shall be possible to trace new trace
131 events up to the point when the trace stream becomes full. After flush‐
132 ing is completed, the space used by the flushed trace events shall be
133 available for tracing new trace events.
134 If flushing the trace stream causes the resulting trace log to become
136 full, the trace log full policy shall be applied. If the trace log-
137 full-policy attribute is set, the following occurs:
138 POSIX_TRACE_UNTIL_FULL
140 The trace events that have not yet been flushed shall be dis‐
142 carded.
143 POSIX_TRACE_LOOP
145 The trace events that have not yet been flushed shall be written
147 to the beginning of the trace log, overwriting previous trace
148 events stored there.
149 POSIX_TRACE_APPEND
151 The trace events that have not yet been flushed shall be
153 appended to the trace log.
154 The posix_trace_shutdown() function shall stop the tracing of trace
157 events in the trace stream identified by trid, as if posix_trace_stop()
158 had been invoked. The posix_trace_shutdown() function shall free all
159 the resources associated with the trace stream.
160 The posix_trace_shutdown() function shall not return until all the
162 resources associated with the trace stream have been freed. When the
163 posix_trace_shutdown() function returns, the trid argument becomes an
164 invalid trace stream identifier. A call to this function shall uncondi‐
165 tionally deallocate the resources regardless of whether all trace
166 events have been retrieved by the analyzer process. Any thread blocked
167 on one of the trace_getnext_event() functions (which specified this
168 trid) before this call is unblocked with the error [EINVAL].
169 If the process exits, invokes a member of the exec family of functions,
171 or is terminated, the trace streams that the process had created and
172 that have not yet been shut down, shall be automatically shut down as
173 if an explicit call were made to the posix_trace_shutdown() function.
174 For an active trace stream with log, when the posix_trace_shutdown()
176 function is called, all trace events that have not yet been flushed to
177 the trace log shall be flushed, as in the posix_trace_flush() function,
178 and the trace log shall be closed.
179 When a trace log is closed, all the information that may be retrieved
181 later from the trace log through the trace interface shall have been
182 written to the trace log. This information includes the trace
183 attributes, the list of trace event types (with the mapping between
184 trace event names and trace event type identifiers), and the trace sta‐
185 tus.
186 In addition, unspecified information shall be written to the trace log
188 to allow detection of a valid trace log during the posix_trace_open()
189 operation.
190 The posix_trace_shutdown() function shall not return until all trace
192 events have been flushed.
193
195 Upon successful completion, these functions shall return a value of
196 zero. Otherwise, they shall return the corresponding error number.
197 The posix_trace_create() and posix_trace_create_withlog() functions
199 store the trace stream identifier value in the object pointed to by
200 trid, if successful.
201
203 The posix_trace_create() and posix_trace_create_withlog() functions
204 shall fail if:
205 EAGAIN No more trace streams can be started now. {TRACE_SYS_MAX} has
207 been exceeded.
208 EINTR The operation was interrupted by a signal. No trace stream was
210 created.
211 EINVAL One or more of the trace parameters specified by the attr param‐
213 eter is invalid.
214 ENOMEM The implementation does not currently have sufficient memory to
216 create the trace stream with the specified parameters.
217 EPERM The caller does not have appropriate privilege to trace the
219 process specified by pid.
220 ESRCH The pid argument does not refer to an existing process.
222 The posix_trace_create_withlog() function shall fail if:
225 EBADF The file_desc argument is not a valid file descriptor open for
227 writing.
228 EINVAL The file_desc argument refers to a file with a file type that
230 does not support the log policy associated with the trace log.
231 ENOSPC No space left on device. The device corresponding to the argu‐
233 ment file_desc does not contain the space required to create
234 this trace log.
235 The posix_trace_flush() and posix_trace_shutdown() functions shall
238 fail if:
239 EINVAL The value of the trid argument does not correspond to an active
241 trace stream with log.
242 EFBIG The trace log file has attempted to exceed an implementation-
244 defined maximum file size.
245 ENOSPC No space left on device.
247 The following sections are informative.
250
252 None.
253
255 None.
256
258 None.
259
261 None.
262
264 clock_getres() , exec() , posix_trace_attr_init() , posix_trace_clear()
265 , posix_trace_close() , posix_trace_eventid_equal() ,
266 posix_trace_eventtypelist_getnext_id() , posix_trace_flush() ,
267 posix_trace_get_attr() , posix_trace_get_filter() ,
268 posix_trace_get_status() , posix_trace_getnext_event() ,
269 posix_trace_open() , posix_trace_set_filter() , posix_trace_shutdown()
270 , posix_trace_start() , posix_trace_timedgetnext_event() ,
271 posix_trace_trid_eventid_open() , posix_trace_start() , time() , the
272 Base Definitions volume of IEEE Std 1003.1-2001, <sys/types.h>,
273 <trace.h>
274
276 Portions of this text are reprinted and reproduced in electronic form
277 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
278 -- Portable Operating System Interface (POSIX), The Open Group Base
279 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
280 Electrical and Electronics Engineers, Inc and The Open Group. In the
281 event of any discrepancy between this version and the original IEEE and
282 The Open Group Standard, the original IEEE and The Open Group Standard
283 is the referee document. The original Standard can be obtained online
284 at http://www.opengroup.org/unix/online.html .
285IEEE/The Open Group 2003 POSIX_TRACE_CREATE(P)