POSIX_TRACE_ATTR_GETLOGSIZE(P3O)SIX Programmer's ManPuOaSlIX_TRACE_ATTR_GETLOGSIZE(3)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

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 (TRACING)

SYNOPSIS
       #include <sys/types.h>
       #include <trace.h>

       int posix_trace_attr_getlogsize(const trace_attr_t *restrict attr,
           size_t *restrict logsize);
       int posix_trace_attr_getmaxdatasize(const trace_attr_t *restrict attr,
           size_t *restrict maxdatasize);
       int posix_trace_attr_getmaxsystemeventsize(
           const trace_attr_t *restrict attr,
           size_t *restrict eventsize);
       int posix_trace_attr_getmaxusereventsize(
           const trace_attr_t *restrict attr,
           size_t data__len, size_t *restrict eventsize);
       int posix_trace_attr_getstreamsize(const trace_attr_t *restrict attr,
           size_t *restrict streamsize);
       int posix_trace_attr_setlogsize(trace_attr_t *attr,
           size_t logsize);
       int posix_trace_attr_setmaxdatasize(trace_attr_t *attr,
           size_t maxdatasize);
       int posix_trace_attr_setstreamsize(trace_attr_t *attr,
           size_t streamsize);

DESCRIPTION
       The posix__trace__attr__getlogsize() function shall copy the log size, in
       bytes, from the log-max-size attribute of the attributes object pointed
       to by the attr argument into the variable pointed to by the 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 log-max-size attribute is implementation-defined.

       The posix__trace__attr__setlogsize() function shall set the maximum
       allowed size, in bytes, in the log-max-size attribute of the attributes
       object pointed to by the attr argument, using the size value supplied
       by the logsize argument.

       The trace log size shall be used if the log-full-policy attribute is
       set to POSIX_TRACE_LOOP or POSIX_TRACE_UNTIL_FULL. If the log-full-
       policy attribute is set to POSIX_TRACE_APPEND, the implementation shall
       ignore the log-max-size attribute.

       The posix__trace__attr__getmaxdatasize() function shall copy the maximum
       user trace event data size, in bytes, from the max-data-size attribute
       of the attributes object pointed to by the attr argument into the
       variable pointed to by the maxdatasize argument. The default value for
       the max-data-size attribute is implementation-defined.

       The posix__trace__attr__getmaxsystemeventsize() 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 attr argument and is returned in the variable
       pointed to by the eventsize argument.

       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 stream-min-size attribute of that trace
       stream, the system provides the necessary resources for recording all
       those trace events, without loss.

       The posix__trace__attr__getmaxusereventsize() function shall calculate the
       maximum memory size, in bytes, required to store a single user trace
       event generated by a call to posix__trace__event() with a data__len
       parameter equal to the data__len value specified in this call. This
       value is calculated for the trace stream attributes object pointed to
       by the attr argument and is returned in the variable pointed to by the
       eventsize argument.

       The posix__trace__attr__getstreamsize() function shall copy the stream
       size, in bytes, from the stream-min-size attribute of the attributes
       object pointed to by the attr argument into the variable pointed to by
       the streamsize argument.

       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
       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.

       The posix__trace__attr__setmaxdatasize() function shall set the maximum
       allowed size, in bytes, in the max-data-size attribute of the
       attributes object pointed to by the attr argument, using the size value
       supplied by the maxdatasize argument. This maximum size is the maximum
       allowed size for the user data argument which may be passed to
       posix__trace__event().  The implementation shall be allowed to truncate
       data passed to trace__user__event which is longer than maxdatasize.

       The posix__trace__attr__setstreamsize() function shall set the minimum
       allowed size, in bytes, in the stream-min-size attribute of the
       attributes object pointed to by the attr argument, using the size value
       supplied by the streamsize argument.

RETURN VALUE
       Upon successful completion, these functions shall return a value of
       zero. Otherwise, they shall return the corresponding error number.

       The posix__trace__attr__getlogsize() function stores the maximum trace log
       allowed size in the object pointed to by logsize, if successful.

       The posix__trace__attr__getmaxdatasize() function stores the maximum trace
       event record memory size in the object pointed to by maxdatasize, if
       successful.

       The posix__trace__attr__getmaxsystemeventsize() function stores the
       maximum memory size to store a single system trace event in the object
       pointed to by eventsize, if successful.

       The posix__trace__attr__getmaxusereventsize() function stores the maximum
       memory size to store a single user trace event in the object pointed to
       by eventsize, if successful.

       The posix__trace__attr__getstreamsize() function stores the maximum trace
       stream allowed size in the object pointed to by streamsize, if
       successful.

ERRORS
       These functions may fail if:

       EINVAL The value specified by one of the arguments is invalid.

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       None.

RATIONALE
       None.

FUTURE DIRECTIONS
       The following functions:

              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()

       may be removed in a future version.

SEE ALSO
       posix__trace__attr__destroy(), posix__trace__create(), posix__trace__event(),
       posix__trace__get__attr()

       The Base Definitions volume of POSIX.1-2017, <sys_types.h>, <trace.h>

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 .

       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 .



IEEE/The Open Group                  2017       POSIX_TRACE_ATTR_GETLOGSIZE(3)
