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

NAME

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

SYNOPSIS

18       #include <trace.h>
19
20
21
22       int posix_trace_attr_getinherited(const trace_attr_t *restrict attr,
23              int *restrict inheritancepolicy);
24
25
26       int   posix_trace_attr_getlogfullpolicy(const   trace_attr_t  *restrict
27       attr,
28              int *restrict logpolicy);
29
30
31       int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *attr,
32              int *streampolicy);
33
34
35       int posix_trace_attr_setinherited(trace_attr_t *attr,
36              int inheritancepolicy);
37
38
39       int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr,
40              int logpolicy);
41
42
43       int posix_trace_attr_setstreamfullpolicy(trace_attr_t *attr,
44              int streampolicy);
45
46

DESCRIPTION

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
56       POSIX_TRACE_CLOSE_FOR_CHILD
57
58              After a fork() or spawn() operation,  the  child  shall  not  be
59              traced, and tracing of the parent shall continue.
60
61       POSIX_TRACE_INHERITED
62
63              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
67
68       The    default    value    for    the    inheritance    attribute    is
69       POSIX_TRACE_CLOSE_FOR_CHILD.
70
71       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
76       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
79       POSIX_TRACE_LOOP
80
81              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
87       POSIX_TRACE_UNTIL_FULL
88
89              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
95       POSIX_TRACE_APPEND
96
97              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
102
103       The    default    value    for   the   log-full-policy   attribute   is
104       POSIX_TRACE_LOOP.
105
106       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
111       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
114       POSIX_TRACE_LOOP
115
116              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
123       POSIX_TRACE_UNTIL_FULL
124
125              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
141       POSIX_TRACE_FLUSH
142
143              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
149
150       The  default  value  for  the  stream-full-policy  attribute  shall  be
151       POSIX_TRACE_LOOP for an active trace stream without log.
152
153       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

RETURN VALUE

158       Upon successful completion, these functions shall  return  a  value  of
159       zero. Otherwise, they shall return the corresponding error number.
160
161       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
165       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
169       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

ERRORS

175       These functions may fail if:
176
177       EINVAL The value specified by at least one of the arguments is invalid.
178
179
180       The following sections are informative.
181

EXAMPLES

183       None.
184

APPLICATION USAGE

186       None.
187

RATIONALE

189       None.
190

FUTURE DIRECTIONS

192       None.
193

SEE ALSO

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 .
210
211
212
213IEEE/The Open Group                  2003    POSIX_TRACE_ATTR_GETINHERITED(3P)
Impressum