Provided by: manpages-posix-dev_2013a-2_all bug

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.

NAME

       posix_trace_attr_getinherited, posix_trace_attr_getlogfullpolicy,
       posix_trace_attr_getstreamfullpolicy, posix_trace_attr_setinherited,
       posix_trace_attr_setlogfullpolicy, posix_trace_attr_setstreamfullpolicy — retrieve and set
       the behavior of a trace stream (TRACING)

SYNOPSIS

       #include <trace.h>

       int posix_trace_attr_getinherited(const trace_attr_t *restrict attr,
           int *restrict inheritancepolicy);
       int posix_trace_attr_getlogfullpolicy(const trace_attr_t *restrict attr,
           int *restrict logpolicy);
       int posix_trace_attr_getstreamfullpolicy(const trace_attr_t *restrict
           attr, int *restrict streampolicy);
       int posix_trace_attr_setinherited(trace_attr_t *attr,
           int inheritancepolicy);
       int posix_trace_attr_setlogfullpolicy(trace_attr_t *attr,
           int logpolicy);
       int posix_trace_attr_setstreamfullpolicy(trace_attr_t *attr,
           int streampolicy);

DESCRIPTION

       The   posix_trace_attr_getinherited()   and   posix_trace_attr_setinherited()   functions,
       respectively, shall get and set the inheritance policy stored in the inheritance attribute
       for traced processes across the fork() and spawn() operations. The  inheritance  attribute
       of  the  attributes  object  pointed  to  by  the attr argument shall be set to one of the
       following values defined by manifest constants in the <trace.h> header:

       POSIX_TRACE_CLOSE_FOR_CHILD
             After a fork() or spawn() operation, the child shall not be traced, and  tracing  of
             the parent shall continue.

       POSIX_TRACE_INHERITED
             After  a fork() or spawn() operation, if the parent is being traced, its child shall
             be concurrently traced using the same trace stream.

       The default value for the inheritance attribute is POSIX_TRACE_CLOSE_FOR_CHILD.

       The posix_trace_attr_getlogfullpolicy() and posix_trace_attr_setlogfullpolicy() functions,
       respectively,  shall  get  and set the trace log full policy stored in the log-full-policy
       attribute of the attributes object pointed to by the attr argument.

       The log-full-policy attribute shall be set to one  of  the  following  values  defined  by
       manifest constants in the <trace.h> header:

       POSIX_TRACE_LOOP
             The  trace log shall loop until the associated trace stream is stopped.  This policy
             means that when the trace log gets full, the file system shall reuse  the  resources
             allocated  to the oldest trace events that were recorded. In this way, the trace log
             will always contain the most recent trace events flushed.

       POSIX_TRACE_UNTIL_FULL
             The trace stream shall be flushed to the trace log until the trace log is full. This
             condition  can  be  deduced  from  the  posix_log_full_status member status (see the
             posix_trace_status_info structure defined in <trace.h>).  The  last  recorded  trace
             event shall be the POSIX_TRACE_STOP trace event.

       POSIX_TRACE_APPEND
             The  associated  trace  stream  shall  be  flushed to the trace log without log size
             limitation. If the  application  specifies  POSIX_TRACE_APPEND,  the  implementation
             shall ignore the log-max-size attribute.

       The default value for the log-full-policy attribute is POSIX_TRACE_LOOP.

       The   posix_trace_attr_getstreamfullpolicy()   and  posix_trace_attr_setstreamfullpolicy()
       functions, respectively, shall get and set the trace stream  full  policy  stored  in  the
       stream-full-policy attribute of the attributes object pointed to by the attr argument.

       The  stream-full-policy  attribute  shall be set to one of the following values defined by
       manifest constants in the <trace.h> header:

       POSIX_TRACE_LOOP
             The trace stream shall loop  until  explicitly  stopped  by  the  posix_trace_stop()
             function.  This  policy  means  that when the trace stream is full, the trace system
             shall reuse the resources allocated to the oldest trace  events  recorded.  In  this
             way, the trace stream will always contain the most recent trace events recorded.

       POSIX_TRACE_UNTIL_FULL
             The  trace  stream will run until the trace stream resources are exhausted. Then the
             trace stream will stop. This condition can be deduced from  posix_stream_status  and
             posix_stream_full_status  (see  the  posix_trace_status_info  structure  defined  in
             <trace.h>).  When this trace stream is read, a POSIX_TRACE_STOP trace event shall be
             reported  after  reporting  the  last  recorded trace event.  The trace system shall
             reuse  the  resources  allocated  to  any  trace  events  already  reported—see  the
             posix_trace_getnext_event(),           posix_trace_trygetnext_event(),           and
             posix_trace_timedgetnext_event() functions—or already flushed for  an  active  trace
             stream  with  log  if the Trace Log option is supported; see the posix_trace_flush()
             function. The trace system shall restart the trace stream when it is empty  and  may
             restart  it  sooner.  A  POSIX_TRACE_START  trace  event  shall  be  reported before
             reporting the next recorded trace event.

       POSIX_TRACE_FLUSH
             If  the  Trace  Log  option  is  supported,  this  policy  is   identical   to   the
             POSIX_TRACE_UNTIL_FULL  trace  stream full policy except that the trace stream shall
             be flushed regularly as if posix_trace_flush() had been explicitly called.  Defining
             this policy for an active trace stream without log shall be invalid.

       The  default  value  for the stream-full-policy attribute shall be POSIX_TRACE_LOOP for an
       active trace stream without log.

       If the Trace Log option  is  supported,  the  default  value  for  the  stream-full-policy
       attribute shall be POSIX_TRACE_FLUSH for an active trace stream with log.

RETURN VALUE

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

       If successful, the posix_trace_attr_getinherited() function shall  store  the  inheritance
       attribute  value in the object pointed to by inheritancepolicy.  Otherwise, the content of
       this object is undefined.

       If successful, the posix_trace_attr_getlogfullpolicy() function shall store the  log-full-
       policy  attribute  value in the object pointed to by logpolicy.  Otherwise, the content of
       this object is undefined.

       If successful, the posix_trace_attr_getstreamfullpolicy() function shall store the stream-
       full-policy  attribute  value  in  the  object pointed to by streampolicy.  Otherwise, the
       content of this object is undefined.

ERRORS

       These functions may fail if:

       EINVAL The value specified by at least 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_getinherited()
              posix_trace_attr_getlogfullpolicy()
              posix_trace_attr_getstreamfullpolicy()
              posix_trace_attr_setinherited()
              posix_trace_attr_setlogfullpolicy()
              posix_trace_attr_setstreamfullpolicy()

       may be removed in a future version.

SEE ALSO

       fork(), posix_trace_attr_destroy(), posix_trace_create(), posix_trace_get_attr(),
       posix_trace_getnext_event(), posix_trace_start()

       The Base Definitions volume of POSIX.1‐2008, <trace.h>

COPYRIGHT

       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2013 Edition, Standard for Information Technology  --  Portable  Operating  System
       Interface  (POSIX),  The Open Group Base Specifications Issue 7, Copyright (C) 2013 by the
       Institute of Electrical and Electronics Engineers, Inc  and  The  Open  Group.   (This  is
       POSIX.1-2008  with  the  2013  Technical  Corrigendum  1  applied.)  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.unix.org/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 .