1POSIX_TRACE_ATTR_GETINHERITEPDO(S3IPX)Programmer'sPMOaSnIuXa_lTRACE_ATTR_GETINHERITED(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_attr_getinherited, posix_trace_attr_getlogfullpolicy,
14       posix_trace_attr_getstreamfullpolicy, posix_trace_attr_setinherited,
15       posix_trace_attr_setlogfullpolicy, posix_trace_attr_setstreamfullpolicy
16       — retrieve and set the behavior of a trace stream (TRACING)
17

SYNOPSIS

19       #include <trace.h>
20
21       int posix_trace_attr_getinherited(const trace_attr_t *restrict attr,
22           int *restrict inheritancepolicy);
23       int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict attr,
24           int *restrict logpolicy);
25       int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict
26           attr, int *restrict streampolicy);
27       int posix_trace_attr_setinherited(trace_attr_t *attr,
28           int inheritancepolicy);
29       int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr,
30           int logpolicy);
31       int posix_trace_attr_setstreamfullpolicy(trace_attr_t *attr,
32           int streampolicy);
33

DESCRIPTION

35       The posix_trace_attr_getinherited() and posix_trace_attr_setinherited()
36       functions, respectively, shall  get  and  set  the  inheritance  policy
37       stored  in  the  inheritance  attribute for traced processes across the
38       fork()  and  spawn()  operations.  The  inheritance  attribute  of  the
39       attributes  object  pointed to by the attr argument shall be set to one
40       of the following values defined by manifest constants in the  <trace.h>
41       header:
42
43       POSIX_TRACE_CLOSE_FOR_CHILD
44             After  a  fork()  or  spawn()  operation,  the child shall not be
45             traced, and tracing of the parent shall continue.
46
47       POSIX_TRACE_INHERITED
48             After a fork() or spawn()  operation,  if  the  parent  is  being
49             traced,  its  child  shall  be concurrently traced using the same
50             trace stream.
51
52       The    default    value    for    the    inheritance    attribute    is
53       POSIX_TRACE_CLOSE_FOR_CHILD.
54
55       The  posix_trace_attr_getlogfullpolicy()  and  posix_trace_attr_setlog‐
56       fullpolicy() functions, respectively, shall get and set the  trace  log
57       full  policy  stored in the log-full-policy attribute of the attributes
58       object pointed to by the attr argument.
59
60       The log-full-policy attribute shall be set to one of the following val‐
61       ues defined by manifest constants in the <trace.h> header:
62
63       POSIX_TRACE_LOOP
64             The  trace  log  shall  loop until the associated trace stream is
65             stopped.  This policy means that when the trace  log  gets  full,
66             the file system shall reuse the resources allocated to the oldest
67             trace events that were recorded. In this way, the trace log  will
68             always contain the most recent trace events flushed.
69
70       POSIX_TRACE_UNTIL_FULL
71             The  trace  stream  shall  be  flushed to the trace log until the
72             trace log is  full.  This  condition  can  be  deduced  from  the
73             posix_log_full_status  member  status  (see  the posix_trace_sta‐
74             tus_info structure defined  in  <trace.h>).   The  last  recorded
75             trace event shall be the POSIX_TRACE_STOP trace event.
76
77       POSIX_TRACE_APPEND
78             The  associated  trace  stream  shall be flushed to the trace log
79             without  log  size  limitation.  If  the  application   specifies
80             POSIX_TRACE_APPEND,  the implementation shall ignore the log-max-
81             size attribute.
82
83       The   default   value   for   the    log-full-policy    attribute    is
84       POSIX_TRACE_LOOP.
85
86       The  posix_trace_attr_getstreamfullpolicy()  and  posix_trace_attr_set‐
87       streamfullpolicy() functions, respectively, shall get and set the trace
88       stream  full  policy  stored in the stream-full-policy attribute of the
89       attributes object pointed to by the attr argument.
90
91       The stream-full-policy attribute shall be set to one of  the  following
92       values defined by manifest constants in the <trace.h> header:
93
94       POSIX_TRACE_LOOP
95             The  trace  stream  shall  loop  until  explicitly stopped by the
96             posix_trace_stop() function. This  policy  means  that  when  the
97             trace  stream is full, the trace system shall reuse the resources
98             allocated to the oldest trace events recorded. In this  way,  the
99             trace  stream  will  always  contain the most recent trace events
100             recorded.
101
102       POSIX_TRACE_UNTIL_FULL
103             The trace stream will run until the trace  stream  resources  are
104             exhausted. Then the trace stream will stop. This condition can be
105             deduced  from  posix_stream_status  and  posix_stream_full_status
106             (see the posix_trace_status_info structure defined in <trace.h>).
107             When this trace stream is read, a  POSIX_TRACE_STOP  trace  event
108             shall  be reported after reporting the last recorded trace event.
109             The trace system shall reuse the resources allocated to any trace
110             events   already  reported—see  the  posix_trace_getnext_event(),
111             posix_trace_trygetnext_event(),     and     posix_trace_timedget‐
112             next_event()  functions—or  already  flushed  for an active trace
113             stream with log if the Trace Log option  is  supported;  see  the
114             posix_trace_flush()  function. The trace system shall restart the
115             trace stream when it is  empty  and  may  restart  it  sooner.  A
116             POSIX_TRACE_START  trace event shall be reported before reporting
117             the next recorded trace event.
118
119       POSIX_TRACE_FLUSH
120             If the Trace Log option is supported, this policy is identical to
121             the  POSIX_TRACE_UNTIL_FULL  trace stream full policy except that
122             the   trace   stream   shall   be   flushed   regularly   as   if
123             posix_trace_flush()  had  been  explicitly  called. Defining this
124             policy for an active trace stream without log shall be invalid.
125
126       The  default  value  for  the  stream-full-policy  attribute  shall  be
127       POSIX_TRACE_LOOP for an active trace stream without log.
128
129       If the Trace Log option is supported, the default value for the stream-
130       full-policy attribute shall be POSIX_TRACE_FLUSH for  an  active  trace
131       stream with log.
132

RETURN VALUE

134       Upon  successful  completion,  these  functions shall return a value of
135       zero. Otherwise, they shall return the corresponding error number.
136
137       If successful, the posix_trace_attr_getinherited() function shall store
138       the  inheritance attribute value in the object pointed to by inheritan‐
139       cepolicy.  Otherwise, the content of this object is undefined.
140
141       If successful, the posix_trace_attr_getlogfullpolicy()  function  shall
142       store  the  log-full-policy attribute value in the object pointed to by
143       logpolicy.  Otherwise, the content of this object is undefined.
144
145       If  successful,  the  posix_trace_attr_getstreamfullpolicy()   function
146       shall  store  the  stream-full-policy  attribute  value  in  the object
147       pointed to by streampolicy.  Otherwise, the content of this  object  is
148       undefined.
149

ERRORS

151       These functions may fail if:
152
153       EINVAL The value specified by at least one of the arguments is invalid.
154
155       The following sections are informative.
156

EXAMPLES

158       None.
159

APPLICATION USAGE

161       None.
162

RATIONALE

164       None.
165

FUTURE DIRECTIONS

167       The following functions:
168
169              posix_trace_attr_getinherited()
170              posix_trace_attr_getlogfullpolicy()
171              posix_trace_attr_getstreamfullpolicy()
172              posix_trace_attr_setinherited()
173              posix_trace_attr_setlogfullpolicy()
174              posix_trace_attr_setstreamfullpolicy()
175
176       may be removed in a future version.
177

SEE ALSO

179       fork(), posix_trace_attr_destroy(), posix_trace_create(),
180       posix_trace_get_attr(), posix_trace_getnext_event(),
181       posix_trace_start()
182
183       The Base Definitions volume of POSIX.1‐2008, <trace.h>
184
186       Portions  of  this text are reprinted and reproduced in electronic form
187       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
188       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
189       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
190       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
191       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
192       event of any discrepancy between this version and the original IEEE and
193       The Open Group Standard, the original IEEE and The Open Group  Standard
194       is  the  referee document. The original Standard can be obtained online
195       at http://www.unix.org/online.html .
196
197       Any typographical or formatting errors that appear  in  this  page  are
198       most likely to have been introduced during the conversion of the source
199       files to man page format. To report such errors,  see  https://www.ker
200       nel.org/doc/man-pages/reporting_bugs.html .
201
202
203
204IEEE/The Open Group                  2013    POSIX_TRACE_ATTR_GETINHERITED(3P)
Impressum