1POSIX_TRACE_CREATE(3P)     POSIX Programmer's Manual    POSIX_TRACE_CREATE(3P)
2
3
4

PROLOG

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
11

NAME

13       posix_trace_create,   posix_trace_create_withlog,    posix_trace_flush,
14       posix_trace_shutdown — trace stream initialization, flush, and shutdown
15       from a process (TRACING)
16

SYNOPSIS

18       #include <sys/types.h>
19       #include <trace.h>
20
21       int posix_trace_create(pid_t pid,
22           const trace_attr_t *restrict attr,
23           trace_id_t *restrict trid);
24       int posix_trace_create_withlog(pid_t pid,
25           const trace_attr_t *restrict attr, int file_desc,
26           trace_id_t *restrict trid);
27       int posix_trace_flush(trace_id_t trid);
28       int posix_trace_shutdown(trace_id_t trid);
29

DESCRIPTION

31       The posix_trace_create() function shall create an active trace  stream.
32       It allocates all the resources needed by the trace stream being created
33       for tracing the process specified by pid in accordance  with  the  attr
34       argument.  The  attr  argument represents the initial attributes of the
35       trace  stream  and  shall  have  been  initialized  by   the   function
36       posix_trace_attr_init()  prior to the posix_trace_create() call. If the
37       argument attr is NULL, the default attributes shall be used.  The  attr
38       attributes  object  shall  be  manipulated  through  a set of functions
39       described  in  the  posix_trace_attr  family  of  functions.   If   the
40       attributes  of  the  object  pointed to by attr are modified later, the
41       attributes of the trace stream shall not be affected. The creation-time
42       attribute  of  the newly created trace stream shall be set to the value
43       of the system clock, if the Timers option is not supported, or  to  the
44       value of the CLOCK_REALTIME clock, if the Timers option is supported.
45
46       The  pid  argument  represents  the target process to be traced. If the
47       process executing this function does not have appropriate privileges to
48       trace the process identified by pid, an error shall be returned. If the
49       pid argument is zero, the calling process shall be traced.
50
51       The posix_trace_create() function shall store the trace stream  identi‐
52       fier of the new trace stream in the object pointed to by the trid argu‐
53       ment. This trace stream identifier shall be used in subsequent calls to
54       control  tracing.  The  trid argument may only be used by the following
55       functions:
56
57       posix_trace_clear()                      posix_trace_getnext_event()
58       posix_trace_eventid_equal()              posix_trace_shutdown()
59       posix_trace_eventid_get_name()           posix_trace_start()
60       posix_trace_eventtypelist_getnext_id()   posix_trace_stop()
61       posix_trace_eventtypelist_rewind()       posix_trace_timedgetnext_event()
62       posix_trace_get_attr()                   posix_trace_trid_eventid_open()
63       posix_trace_get_status()                 posix_trace_trygetnext_event()
64
65       If the Trace Event Filter option is supported, the following additional
66       functions may use the trid argument:
67
68       posix_trace_get_filter()   posix_trace_set_filter()
69
70       In particular, notice that the operations normally used by a trace ana‐
71       lyzer process, such  as  posix_trace_rewind()  or  posix_trace_close(),
72       cannot  be  invoked  using  the trace stream identifier returned by the
73       posix_trace_create() function.
74
75       A trace stream shall be created in a suspended  state.   If  the  Trace
76       Event  Filter option is supported, its trace event type filter shall be
77       empty.
78
79       The posix_trace_create() function may be called multiple times from the
80       same  or  different  processes, with the system-wide limit indicated by
81       the runtime invariant value  {TRACE_SYS_MAX},  which  has  the  minimum
82       value {_POSIX_TRACE_SYS_MAX}.
83
84       The  trace stream identifier returned by the posix_trace_create() func‐
85       tion in the argument pointed to by trid is valid only  in  the  process
86       that  made  the function call. If it is used from another process, that
87       is a child process, in functions defined in POSIX.1‐2008,  these  func‐
88       tions shall return with the error [EINVAL].
89
90       The   posix_trace_create_withlog()  function  shall  be  equivalent  to
91       posix_trace_create(), except that it associates a trace log  with  this
92       stream. The file_desc argument shall be the file descriptor designating
93       the trace log  destination.  The  function  shall  fail  if  this  file
94       descriptor  refers  to  a  file with a file type that is not compatible
95       with the log policy associated with the trace  log.  The  list  of  the
96       appropriate  file  types  that  are  compatible with each log policy is
97       implementation-defined.
98
99       The posix_trace_create_withlog() function shall return in the parameter
100       pointed  to by trid the trace stream identifier, which uniquely identi‐
101       fies the newly created trace stream, and shall be  used  in  subsequent
102       calls  to  control  tracing.  The trid argument may only be used by the
103       following functions:
104
105       posix_trace_clear()                      posix_trace_get_status()
106       posix_trace_eventid_equal()              posix_trace_getnext_event()
107       posix_trace_eventid_get_name()           posix_trace_shutdown()
108       posix_trace_eventtypelist_getnext_id()   posix_trace_start()
109       posix_trace_eventtypelist_rewind()       posix_trace_stop()
110       posix_trace_flush()                      posix_trace_timedgetnext_event()
111       posix_trace_get_attr()                   posix_trace_trid_eventid_open()
112
113       If the Trace Event Filter option is supported, the following additional
114       functions may use the trid argument:
115
116       posix_trace_get_filter()   posix_trace_set_filter()
117
118       In particular, notice that the operations normally used by a trace ana‐
119       lyzer process, such  as  posix_trace_rewind()  or  posix_trace_close(),
120       cannot  be  invoked  using  the trace stream identifier returned by the
121       posix_trace_create_withlog() function.
122
123       The posix_trace_flush() function shall initiate a flush operation which
124       copies the contents of the trace stream identified by the argument trid
125       into the trace log associated with the trace  stream  at  the  creation
126       time. If no trace log has been associated with the trace stream pointed
127       to by trid, this function shall return an error. The termination of the
128       flush operation can be polled by the posix_trace_get_status() function.
129       During the flush operation, it shall be possible  to  trace  new  trace
130       events  up  to  the  point  when  the trace stream becomes full.  After
131       flushing is completed, the space used by the flushed trace events shall
132       be available for tracing new trace events.
133
134       If  flushing  the trace stream causes the resulting trace log to become
135       full, the trace log full policy shall be applied.  If  the  trace  log-
136       full-policy attribute is set, the following occurs:
137
138       POSIX_TRACE_UNTIL_FULL
139             The  trace  events  that  have not yet been flushed shall be dis‐
140             carded.
141
142       POSIX_TRACE_LOOP
143             The trace events that have not yet been flushed shall be  written
144             to  the  beginning  of  the trace log, overwriting previous trace
145             events stored there.
146
147       POSIX_TRACE_APPEND
148             The trace events that have not yet been flushed shall be appended
149             to the trace log.
150
151       The  posix_trace_shutdown()  function  shall  stop the tracing of trace
152       events in the trace stream identified by trid, as if posix_trace_stop()
153       had  been  invoked.  The posix_trace_shutdown() function shall free all
154       the resources associated with the trace stream.
155
156       The posix_trace_shutdown() function shall  not  return  until  all  the
157       resources  associated  with  the trace stream have been freed. When the
158       posix_trace_shutdown() function returns, the trid argument  becomes  an
159       invalid trace stream identifier. A call to this function shall uncondi‐
160       tionally deallocate the  resources  regardless  of  whether  all  trace
161       events have been retrieved by the analyzer process.  Any thread blocked
162       on one of the trace_getnext_event()  functions  (which  specified  this
163       trid) before this call is unblocked with the error [EINVAL].
164
165       If the process exits, invokes a member of the exec family of functions,
166       or is terminated, the trace streams that the process  had  created  and
167       that  have  not yet been shut down, shall be automatically shut down as
168       if an explicit call were made to the posix_trace_shutdown() function.
169
170       For an active trace stream with log,  when  the  posix_trace_shutdown()
171       function  is called, all trace events that have not yet been flushed to
172       the trace log shall be flushed, as in the posix_trace_flush() function,
173       and the trace log shall be closed.
174
175       When  a  trace log is closed, all the information that may be retrieved
176       later from the trace log through the trace interface  shall  have  been
177       written   to  the  trace  log.  This  information  includes  the  trace
178       attributes, the list of trace event types  (with  the  mapping  between
179       trace event names and trace event type identifiers), and the trace sta‐
180       tus.
181
182       In addition, unspecified information shall be written to the trace  log
183       to  allow  detection of a valid trace log during the posix_trace_open()
184       operation.
185
186       The posix_trace_shutdown() function shall not return  until  all  trace
187       events have been flushed.
188

RETURN VALUE

190       Upon  successful  completion,  these  functions shall return a value of
191       zero. Otherwise, they shall return the corresponding error number.
192
193       The  posix_trace_create()  and  posix_trace_create_withlog()  functions
194       store  the  trace  stream  identifier value in the object pointed to by
195       trid, if successful.
196

ERRORS

198       The  posix_trace_create()  and  posix_trace_create_withlog()  functions
199       shall fail if:
200
201       EAGAIN No  more  trace streams can be started now.  {TRACE_SYS_MAX} has
202              been exceeded.
203
204       EINTR  The operation was interrupted by a signal. No trace  stream  was
205              created.
206
207       EINVAL One or more of the trace parameters specified by the attr param‐
208              eter is invalid.
209
210       ENOMEM The implementation does not currently have sufficient memory  to
211              create the trace stream with the specified parameters.
212
213       EPERM  The  caller  does  not  have appropriate privileges to trace the
214              process specified by pid.
215
216       ESRCH  The pid argument does not refer to an existing process.
217
218       The posix_trace_create_withlog() function shall fail if:
219
220       EBADF  The file_desc argument is not a valid file descriptor  open  for
221              writing.
222
223       EINVAL The  file_desc  argument  refers to a file with a file type that
224              does not support the log policy associated with the trace log.
225
226       ENOSPC No space left on device. The device corresponding to  the  argu‐
227              ment  file_desc  does  not  contain the space required to create
228              this trace log.
229
230       The posix_trace_flush() and posix_trace_shutdown() functions shall fail
231       if:
232
233       EINVAL The  value of the trid argument does not correspond to an active
234              trace stream with log.
235
236       EFBIG  The trace log file has attempted to  exceed  an  implementation-
237              defined maximum file size.
238
239       ENOSPC No space left on device.
240
241       The following sections are informative.
242

EXAMPLES

244       None.
245

APPLICATION USAGE

247       None.
248

RATIONALE

250       None.
251

FUTURE DIRECTIONS

253       The         posix_trace_create(),         posix_trace_create_withlog(),
254       posix_trace_flush(),  and  posix_trace_shutdown()  functions   may   be
255       removed in a future version.
256

SEE ALSO

258       clock_getres(), exec, posix_trace_attr_destroy(), posix_trace_clear(),
259       posix_trace_close(), posix_trace_eventid_equal(), posix_trace_event‐
260       typelist_getnext_id(), posix_trace_get_attr(), posix_trace_get_fil‐
261       ter(), posix_trace_getnext_event(), posix_trace_start(),
262       posix_trace_start(), time()
263
264       The Base Definitions volume of POSIX.1‐2008, <sys_types.h>, <trace.h>
265
267       Portions  of  this text are reprinted and reproduced in electronic form
268       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
269       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
270       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
271       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
272       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
273       event of any discrepancy between this version and the original IEEE and
274       The Open Group Standard, the original IEEE and The Open Group  Standard
275       is  the  referee document. The original Standard can be obtained online
276       at http://www.unix.org/online.html .
277
278       Any typographical or formatting errors that appear  in  this  page  are
279       most likely to have been introduced during the conversion of the source
280       files to man page format. To report such errors,  see  https://www.ker
281       nel.org/doc/man-pages/reporting_bugs.html .
282
283
284
285IEEE/The Open Group                  2013               POSIX_TRACE_CREATE(3P)
Impressum