1POSIX_TRACE_ATTR_GETLOGSIZE(P3OPS)IX Programmer's MaPnOuSaIlX_TRACE_ATTR_GETLOGSIZE(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_getlogsize, posix_trace_attr_getmaxdatasize,
13       posix_trace_attr_getmaxsystemeventsize, posix_trace_attr_get‐
14       maxusereventsize, posix_trace_attr_getstreamsize, posix_trace_attr_set‐
15       logsize, posix_trace_attr_setmaxdatasize, posix_trace_attr_setstream‐
16       size — retrieve and set trace stream size attributes (TRACING)
17

SYNOPSIS

19       #include <sys/types.h>
20       #include <trace.h>
21
22       int posix_trace_attr_getlogsize(const trace_attr_t *restrict attr,
23           size_t *restrict logsize);
24       int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict attr,
25           size_t *restrict maxdatasize);
26       int posix_trace_attr_getmaxsystemeventsize(
27           const trace_attr_t *restrict attr,
28           size_t *restrict eventsize);
29       int posix_trace_attr_getmaxusereventsize(
30           const trace_attr_t *restrict attr,
31           size_t data_len, size_t *restrict eventsize);
32       int posix_trace_attr_getstreamsize(const trace_attr_t *restrict attr,
33           size_t *restrict streamsize);
34       int posix_trace_attr_setlogsize(trace_attr_t *attr,
35           size_t logsize);
36       int posix_trace_attr_setmaxdatasize(trace_attr_t *attr,
37           size_t maxdatasize);
38       int posix_trace_attr_setstreamsize(trace_attr_t *attr,
39           size_t streamsize);
40

DESCRIPTION

42       The posix_trace_attr_getlogsize() function shall copy the log size,  in
43       bytes, from the log-max-size attribute of the attributes object pointed
44       to by the attr argument into the variable pointed  to  by  the  logsize
45       argument.  This  log  size  is the maximum total of bytes that shall be
46       allocated for system and user  trace  events  in  the  trace  log.  The
47       default value for the log-max-size attribute is implementation-defined.
48
49       The   posix_trace_attr_setlogsize()  function  shall  set  the  maximum
50       allowed size, in bytes, in the log-max-size attribute of the attributes
51       object  pointed  to by the attr argument, using the size value supplied
52       by the logsize argument.
53
54       The trace log size shall be used if the  log-full-policy  attribute  is
55       set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. If the log-full-pol‐
56       icy attribute is set to POSIX_TRACE_APPEND,  the  implementation  shall
57       ignore the log-max-size attribute.
58
59       The  posix_trace_attr_getmaxdatasize()  function shall copy the maximum
60       user trace event data size, in bytes, from the max-data-size  attribute
61       of the attributes object pointed to by the attr argument into the vari‐
62       able pointed to by the maxdatasize argument. The default value for  the
63       max-data-size attribute is implementation-defined.
64
65       The  posix_trace_attr_getmaxsystemeventsize()  function shall calculate
66       the maximum memory size, in bytes, required to store  a  single  system
67       trace  event.  This value is calculated for the trace stream attributes
68       object pointed to by the attr argument and is returned in the  variable
69       pointed to by the eventsize argument.
70
71       The  values returned as the maximum memory sizes of the user and system
72       trace events shall be such that if the sum of the maximum memory  sizes
73       of  a set of the trace events that may be recorded in a trace stream is
74       less than or equal to  the  stream-min-size  attribute  of  that  trace
75       stream,  the  system provides the necessary resources for recording all
76       those trace events, without loss.
77
78       The posix_trace_attr_getmaxusereventsize() function shall calculate the
79       maximum  memory  size,  in bytes, required to store a single user trace
80       event generated by a call to posix_trace_event() with a data_len param‐
81       eter  equal to the data_len value specified in this call. This value is
82       calculated for the trace stream attributes object  pointed  to  by  the
83       attr  argument and is returned in the variable pointed to by the event‐
84       size argument.
85
86       The posix_trace_attr_getstreamsize() function  shall  copy  the  stream
87       size,  in  bytes,  from the stream-min-size attribute of the attributes
88       object pointed to by the attr argument into the variable pointed to  by
89       the streamsize argument.
90
91       This  stream  size is the current total memory size reserved for system
92       and user trace events in the trace stream. The default  value  for  the
93       stream-min-size  attribute  is  implementation-defined. The stream size
94       refers to memory used to store trace event records. Other  stream  data
95       (for  example,  trace  attribute  values) shall not be included in this
96       size.
97
98       The posix_trace_attr_setmaxdatasize() function shall  set  the  maximum
99       allowed   size,  in  bytes,  in  the  max-data-size  attribute  of  the
100       attributes object pointed to by the attr argument, using the size value
101       supplied  by the maxdatasize argument. This maximum size is the maximum
102       allowed size for  the  user  data  argument  which  may  be  passed  to
103       posix_trace_event().   The  implementation shall be allowed to truncate
104       data passed to trace_user_event which is longer than maxdatasize.
105
106       The posix_trace_attr_setstreamsize() function  shall  set  the  minimum
107       allowed  size,  in  bytes,  in  the  stream-min-size  attribute  of the
108       attributes object pointed to by the attr argument, using the size value
109       supplied by the streamsize argument.
110

RETURN VALUE

112       Upon  successful  completion,  these  functions shall return a value of
113       zero. Otherwise, they shall return the corresponding error number.
114
115       The posix_trace_attr_getlogsize() function stores the maximum trace log
116       allowed size in the object pointed to by logsize, if successful.
117
118       The posix_trace_attr_getmaxdatasize() function stores the maximum trace
119       event record memory size in the object pointed to  by  maxdatasize,  if
120       successful.
121
122       The  posix_trace_attr_getmaxsystemeventsize() function stores the maxi‐
123       mum memory size to store a single system  trace  event  in  the  object
124       pointed to by eventsize, if successful.
125
126       The  posix_trace_attr_getmaxusereventsize() function stores the maximum
127       memory size to store a single user trace event in the object pointed to
128       by eventsize, if successful.
129
130       The  posix_trace_attr_getstreamsize() function stores the maximum trace
131       stream allowed size in the object pointed to by streamsize, if success‐
132       ful.
133

ERRORS

135       These functions may fail if:
136
137       EINVAL The value specified by one of the arguments is invalid.
138
139       The following sections are informative.
140

EXAMPLES

142       None.
143

APPLICATION USAGE

145       None.
146

RATIONALE

148       None.
149

FUTURE DIRECTIONS

151       The following functions:
152
153              posix_trace_attr_getlogsize()
154              posix_trace_attr_getmaxdatasize()
155              posix_trace_attr_getmaxsystemeventsize()
156              posix_trace_attr_getmaxusereventsize()
157              posix_trace_attr_getstreamsize()
158              posix_trace_attr_setlogsize()
159              posix_trace_attr_setmaxdatasize()
160              posix_trace_attr_setstreamsize()
161
162       may be removed in a future version.
163

SEE ALSO

165       posix_trace_attr_destroy(), posix_trace_create(), posix_trace_event(),
166       posix_trace_get_attr()
167
168       The Base Definitions volume of POSIX.1‐2017, <sys_types.h>, <trace.h>
169
171       Portions of this text are reprinted and reproduced in  electronic  form
172       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
173       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
174       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
175       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
176       event of any discrepancy between this version and the original IEEE and
177       The Open Group Standard, the original IEEE and The Open Group  Standard
178       is  the  referee document. The original Standard can be obtained online
179       at http://www.opengroup.org/unix/online.html .
180
181       Any typographical or formatting errors that appear  in  this  page  are
182       most likely to have been introduced during the conversion of the source
183       files to man page format. To report such errors,  see  https://www.ker
184       nel.org/doc/man-pages/reporting_bugs.html .
185
186
187
188IEEE/The Open Group                  2017      POSIX_TRACE_ATTR_GETLOGSIZE(3P)
Impressum