posix_trace_attr_getlogsize.3p (8401B)
- '\" et
- .TH POSIX_TRACE_ATTR_GETLOGSIZE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- .ad l
- posix_trace_attr_getlogsize,
- posix_trace_attr_getmaxdatasize,
- posix_trace_attr_getmaxsystemeventsize,
- posix_trace_attr_getmaxusereventsize,
- posix_trace_attr_getstreamsize,
- posix_trace_attr_setlogsize,
- posix_trace_attr_setmaxdatasize,
- posix_trace_attr_setstreamsize
- \(em retrieve and set trace stream size attributes
- (\fBTRACING\fP)
- .ad b
- .SH SYNOPSIS
- .LP
- .nf
- #include <sys/types.h>
- #include <trace.h>
- .P
- int posix_trace_attr_getlogsize(const trace_attr_t *restrict \fIattr\fP,
- size_t *restrict \fIlogsize\fP);
- int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict \fIattr\fP,
- size_t *restrict \fImaxdatasize\fP);
- int posix_trace_attr_getmaxsystemeventsize(
- const trace_attr_t *restrict \fIattr\fP,
- size_t *restrict \fIeventsize\fP);
- int posix_trace_attr_getmaxusereventsize(
- const trace_attr_t *restrict \fIattr\fP,
- size_t \fIdata_len\fP, size_t *restrict \fIeventsize\fP);
- int posix_trace_attr_getstreamsize(const trace_attr_t *restrict \fIattr\fP,
- size_t *restrict \fIstreamsize\fP);
- int posix_trace_attr_setlogsize(trace_attr_t *\fIattr\fP,
- size_t \fIlogsize\fP);
- int posix_trace_attr_setmaxdatasize(trace_attr_t *\fIattr\fP,
- size_t \fImaxdatasize\fP);
- int posix_trace_attr_setstreamsize(trace_attr_t *\fIattr\fP,
- size_t \fIstreamsize\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIposix_trace_attr_getlogsize\fR()
- function shall copy the log size, in bytes, from the
- .IR log-max-size
- attribute of the attributes object pointed to by the
- .IR attr
- argument into the variable pointed to by the
- .IR logsize
- argument. This log size is the maximum total of bytes that shall be
- allocated for system and user trace events in the trace log. The
- default value for the
- .IR log-max-size
- attribute is implementation-defined.
- .P
- The
- \fIposix_trace_attr_setlogsize\fR()
- function shall set the maximum allowed size, in bytes, in the
- .IR log-max-size
- attribute of the attributes object pointed to by the
- .IR attr
- argument, using the size value supplied by the
- .IR logsize
- argument.
- .P
- The trace log size shall be used if the
- .IR log-full-policy
- attribute is set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. If the
- .IR log-full-policy
- attribute is set to POSIX_TRACE_APPEND, the implementation shall ignore
- the
- .IR log-max-size
- attribute.
- .P
- The
- \fIposix_trace_attr_getmaxdatasize\fR()
- function shall copy the maximum user trace event data size, in bytes,
- from the
- .IR max-data-size
- attribute of the attributes object pointed to by the
- .IR attr
- argument into the variable pointed to by the
- .IR maxdatasize
- argument. The default value for the
- .IR max-data-size
- attribute is implementation-defined.
- .P
- The
- \fIposix_trace_attr_getmaxsystemeventsize\fR()
- function shall calculate the maximum memory size, in bytes, required to
- store a single system trace event. This value is calculated for the
- trace stream attributes object pointed to by the
- .IR attr
- argument and is returned in the variable pointed to by the
- .IR eventsize
- argument.
- .P
- The values returned as the maximum memory sizes of the user and system
- trace events shall be such that if the sum of the maximum memory sizes
- of a set of the trace events that may be recorded in a trace stream is
- less than or equal to the
- .IR stream-min-size
- attribute of that trace stream, the system provides the necessary
- resources for recording all those trace events, without loss.
- .P
- The
- \fIposix_trace_attr_getmaxusereventsize\fR()
- function shall calculate the maximum memory size, in bytes, required to
- store a single user trace event generated by a call to
- \fIposix_trace_event\fR()
- with a
- .IR data_len
- parameter equal to the
- .IR data_len
- value specified in this call. This value is calculated for the trace
- stream attributes object pointed to by the
- .IR attr
- argument and is returned in the variable pointed to by the
- .IR eventsize
- argument.
- .P
- The
- \fIposix_trace_attr_getstreamsize\fR()
- function shall copy the stream size, in bytes, from the
- .IR stream-min-size
- attribute of the attributes object pointed to by the
- .IR attr
- argument into the variable pointed to by the
- .IR streamsize
- argument.
- .P
- This stream size is the current total memory size reserved for system
- and user trace events in the trace stream. The default value for the
- .IR stream-min-size
- attribute is implementation-defined. The stream size refers to memory
- used to store trace event records. Other stream data (for example,
- trace attribute values) shall not be included in this size.
- .P
- The
- \fIposix_trace_attr_setmaxdatasize\fR()
- function shall set the maximum allowed size, in bytes, in the
- .IR max-data-size
- attribute of the attributes object pointed to by the
- .IR attr
- argument, using the size value supplied by the
- .IR maxdatasize
- argument. This maximum size is the maximum allowed size for the user
- data argument which may be passed to
- \fIposix_trace_event\fR().
- The implementation shall be allowed to truncate data passed to
- .IR trace_user_event
- which is longer than
- .IR maxdatasize .
- .P
- The
- \fIposix_trace_attr_setstreamsize\fR()
- function shall set the minimum allowed size, in bytes, in the
- .IR stream-min-size
- attribute of the attributes object pointed to by the
- .IR attr
- argument, using the size value supplied by the
- .IR streamsize
- argument.
- .SH "RETURN VALUE"
- Upon successful completion, these functions shall return a value of
- zero. Otherwise, they shall return the corresponding error number.
- .P
- The
- \fIposix_trace_attr_getlogsize\fR()
- function stores the maximum trace log allowed size in the object
- pointed to by
- .IR logsize ,
- if successful.
- .P
- The
- \fIposix_trace_attr_getmaxdatasize\fR()
- function stores the maximum trace event record memory size in the
- object pointed to by
- .IR maxdatasize ,
- if successful.
- .P
- The
- \fIposix_trace_attr_getmaxsystemeventsize\fR()
- function stores the maximum memory size to store a single system trace
- event in the object pointed to by
- .IR eventsize ,
- if successful.
- .P
- The
- \fIposix_trace_attr_getmaxusereventsize\fR()
- function stores the maximum memory size to store a single user trace
- event in the object pointed to by
- .IR eventsize ,
- if successful.
- .P
- The
- \fIposix_trace_attr_getstreamsize\fR()
- function stores the maximum trace stream allowed size in the object
- pointed to by
- .IR streamsize ,
- if successful.
- .SH ERRORS
- These functions may fail if:
- .TP
- .BR EINVAL
- The value specified by one of the arguments is invalid.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- The following functions:
- .sp
- .RS
- .nf
- \fIposix_trace_attr_getlogsize\fR()
- \fIposix_trace_attr_getmaxdatasize\fR()
- \fIposix_trace_attr_getmaxsystemeventsize\fR()
- \fIposix_trace_attr_getmaxusereventsize\fR()
- \fIposix_trace_attr_getstreamsize\fR()
- \fIposix_trace_attr_setlogsize\fR()
- \fIposix_trace_attr_setmaxdatasize\fR()
- \fIposix_trace_attr_setstreamsize\fR()
- .fi
- .RE
- .P
- may be removed in a future version.
- .SH "SEE ALSO"
- .ad l
- .IR "\fIposix_trace_attr_destroy\fR\^(\|)",
- .IR "\fIposix_trace_create\fR\^(\|)",
- .IR "\fIposix_trace_event\fR\^(\|)",
- .IR "\fIposix_trace_get_attr\fR\^(\|)"
- .ad b
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<sys_types.h>\fP",
- .IR "\fB<trace.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .