mirror of https://github.com/mkerrisk/man-pages
213 lines
8.0 KiB
Plaintext
213 lines
8.0 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "POSIX_TRACE_ATTR_GETLOGSIZE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" posix_trace_attr_getlogsize
|
|
.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
|
|
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 \- retrieve and set trace stream size
|
|
attributes (\fBTRACING\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <sys/types.h>
|
|
.br
|
|
#include <trace.h>
|
|
.br
|
|
.sp
|
|
\fP
|
|
.LP
|
|
\fBint posix_trace_attr_getlogsize(const trace_attr_t *restrict\fP
|
|
\fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t *restrict\fP \fIlogsize\fP\fB);
|
|
.br
|
|
\fP
|
|
.LP
|
|
\fBint posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict\fP
|
|
\fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t *restrict\fP \fImaxdatasize\fP\fB);
|
|
.br
|
|
int posix_trace_attr_getmaxsystemeventsize(
|
|
.br
|
|
\ \ \ \ \ \ const trace_attr_t *restrict\fP \fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t *restrict\fP \fIeventsize\fP\fB);
|
|
.br
|
|
int posix_trace_attr_getmaxusereventsize(
|
|
.br
|
|
\ \ \ \ \ \ const trace_attr_t *restrict\fP \fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t\fP \fIdata_len\fP\fB, size_t *restrict\fP \fIeventsize\fP\fB);
|
|
.br
|
|
int posix_trace_attr_getstreamsize(const trace_attr_t *restrict\fP
|
|
\fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t *restrict\fP \fIstreamsize\fP\fB);
|
|
.br
|
|
\fP
|
|
.LP
|
|
\fBint posix_trace_attr_setlogsize(trace_attr_t *\fP\fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t\fP \fIlogsize\fP\fB);
|
|
.br
|
|
\fP
|
|
.LP
|
|
\fBint posix_trace_attr_setmaxdatasize(trace_attr_t *\fP\fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t\fP \fImaxdatasize\fP\fB);
|
|
.br
|
|
int posix_trace_attr_setstreamsize(trace_attr_t *\fP\fIattr\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ size_t\fP \fIstreamsize\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIposix_trace_attr_getlogsize\fP() function shall copy the log
|
|
size, in bytes, from the \fIlog-max-size\fP attribute of the
|
|
attributes object pointed to by the \fIattr\fP argument into the variable
|
|
pointed to by the \fIlogsize\fP 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
|
|
\fIlog-max-size\fP attribute is implementation-defined.
|
|
.LP
|
|
The \fIposix_trace_attr_setlogsize\fP() function shall set the maximum
|
|
allowed size, in bytes, in the \fIlog-max-size\fP
|
|
attribute of the attributes object pointed to by the \fIattr\fP argument,
|
|
using the size value supplied by the \fIlogsize\fP
|
|
argument.
|
|
.LP
|
|
The trace log size shall be used if the \fIlog-full-policy\fP attribute
|
|
is set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL.
|
|
If the \fIlog-full-policy\fP attribute is set to POSIX_TRACE_APPEND,
|
|
the implementation shall ignore the \fIlog-max-size\fP
|
|
attribute.
|
|
.LP
|
|
The \fIposix_trace_attr_getmaxdatasize\fP() function shall copy the
|
|
maximum user trace event data size, in bytes, from the
|
|
\fImax-data-size\fP attribute of the attributes object pointed to
|
|
by the \fIattr\fP argument into the variable pointed to by the
|
|
\fImaxdatasize\fP argument. The default value for the \fImax-data-size\fP
|
|
attribute is implementation-defined.
|
|
.LP
|
|
The \fIposix_trace_attr_getmaxsystemeventsize\fP() 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 \fIattr\fP
|
|
argument and is returned in the variable pointed to by the \fIeventsize\fP
|
|
argument.
|
|
.LP
|
|
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
|
|
\fIstream-min-size\fP attribute of that trace stream, the system provides
|
|
the necessary resources for recording all those trace
|
|
events, without loss.
|
|
.LP
|
|
The \fIposix_trace_attr_getmaxusereventsize\fP() 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\fP()
|
|
with
|
|
a \fIdata_len\fP parameter equal to the \fIdata_len\fP value specified
|
|
in this call. This value is calculated for the trace
|
|
stream attributes object pointed to by the \fIattr\fP argument and
|
|
is returned in the variable pointed to by the \fIeventsize\fP
|
|
argument.
|
|
.LP
|
|
The \fIposix_trace_attr_getstreamsize\fP() function shall copy the
|
|
stream size, in bytes, from the \fIstream-min-size\fP
|
|
attribute of the attributes object pointed to by the \fIattr\fP argument
|
|
into the variable pointed to by the \fIstreamsize\fP
|
|
argument.
|
|
.LP
|
|
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 \fIstream-min-size\fP 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.
|
|
.LP
|
|
The \fIposix_trace_attr_setmaxdatasize\fP() function shall set the
|
|
maximum allowed size, in bytes, in the \fImax-data-size\fP
|
|
attribute of the attributes object pointed to by the \fIattr\fP argument,
|
|
using the size value supplied by the \fImaxdatasize\fP
|
|
argument. This maximum size is the maximum allowed size for the user
|
|
data argument which may be passed to \fIposix_trace_event\fP(). The
|
|
implementation shall be allowed to truncate data passed
|
|
to \fItrace_user_event\fP which is longer than \fImaxdatasize\fP.
|
|
.LP
|
|
The \fIposix_trace_attr_setstreamsize\fP() function shall set the
|
|
minimum allowed size, in bytes, in the \fIstream-min-size\fP
|
|
attribute of the attributes object pointed to by the \fIattr\fP argument,
|
|
using the size value supplied by the \fIstreamsize\fP
|
|
argument.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, these functions shall return a value of
|
|
zero. Otherwise, they shall return the corresponding error
|
|
number.
|
|
.LP
|
|
The \fIposix_trace_attr_getlogsize\fP() function stores the maximum
|
|
trace log allowed size in the object pointed to by
|
|
\fIlogsize\fP, if successful.
|
|
.LP
|
|
The \fIposix_trace_attr_getmaxdatasize\fP() function stores the maximum
|
|
trace event record memory size in the object pointed to
|
|
by \fImaxdatasize\fP, if successful.
|
|
.LP
|
|
The \fIposix_trace_attr_getmaxsystemeventsize\fP() function stores
|
|
the maximum memory size to store a single system trace event
|
|
in the object pointed to by \fIeventsize\fP, if successful.
|
|
.LP
|
|
The \fIposix_trace_attr_getmaxusereventsize\fP() function stores the
|
|
maximum memory size to store a single user trace event in
|
|
the object pointed to by \fIeventsize\fP, if successful.
|
|
.LP
|
|
The \fIposix_trace_attr_getstreamsize\fP() function stores the maximum
|
|
trace stream allowed size in the object pointed to by
|
|
\fIstreamsize\fP, if successful.
|
|
.SH ERRORS
|
|
.LP
|
|
These functions may fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The value specified by one of the arguments is invalid.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIposix_trace_attr_init\fP(), \fIposix_trace_create\fP(), \fIposix_trace_event\fP(),
|
|
\fIposix_trace_get_attr\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<sys/types.h>\fP, \fI<trace.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|