Movatterモバイル変換

posix_trace_create(3p) — Linux manual page

PROLOG \|NAME \|SYNOPSIS \|DESCRIPTION \|RETURN VALUE \|ERRORS \|EXAMPLES \|APPLICATION USAGE \|RATIONALE \|FUTURE DIRECTIONS \|SEE ALSO \|COPYRIGHT

POSIX_TRACE_CREATE(3P)  POSIX Programmer's ManualPOSIX_TRACE_CREATE(3P)

PROLOG top

       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 top

       posix_trace_create, posix_trace_create_withlog, posix_trace_flush,       posix_trace_shutdown — trace stream initialization, flush, and       shutdown from a process (TRACING)

SYNOPSIS top

       #include <sys/types.h>       #include <trace.h>       int posix_trace_create(pid_tpid,           const trace_attr_t *restrictattr,           trace_id_t *restricttrid);       int posix_trace_create_withlog(pid_tpid,           const trace_attr_t *restrictattr, intfile_desc,           trace_id_t *restricttrid);       int posix_trace_flush(trace_id_ttrid);       int posix_trace_shutdown(trace_id_ttrid);

DESCRIPTION top

       Theposix_trace_create() function shall create an active trace       stream. It allocates all the resources needed by the trace stream       being created for tracing the process specified bypid in       accordance with theattr argument. Theattr argument represents       the initial attributes of the trace stream and shall have been       initialized by the functionposix_trace_attr_init() prior to theposix_trace_create() call. If the argumentattr is NULL, the       default attributes shall be used. Theattr attributes object shall       be manipulated through a set of functions described in theposix_trace_attr family of functions. If the attributes of the       object pointed to byattr are modified later, the attributes of       the trace stream shall not be affected. Thecreation-time       attribute of the newly created trace stream shall be set to the       value of the system clock, if the Timers option is not supported,       or to the value of the CLOCK_REALTIME clock, if the Timers option       is supported.       Thepid argument represents the target process to be traced. If       the process executing this function does not have appropriate       privileges to trace the process identified bypid, an error shall       be returned. If thepid argument is zero, the calling process       shall be traced.       Theposix_trace_create() function shall store the trace stream       identifier of the new trace stream in the object pointed to by thetrid argument. This trace stream identifier shall be used in       subsequent calls to control tracing. Thetrid argument may only be       used by the following functions:posix_trace_clear()posix_trace_getnext_event()posix_trace_eventid_equal()posix_trace_shutdown()posix_trace_eventid_get_name()posix_trace_start()posix_trace_eventtypelist_getnext_id()posix_trace_stop()posix_trace_eventtypelist_rewind()posix_trace_timedgetnext_event()posix_trace_get_attr()posix_trace_trid_eventid_open()posix_trace_get_status()posix_trace_trygetnext_event()       If the Trace Event Filter option is supported, the following       additional functions may use thetrid argument:posix_trace_get_filter()posix_trace_set_filter()       In particular, notice that the operations normally used by a trace       analyzer process, such asposix_trace_rewind() orposix_trace_close(), cannot be invoked using the trace stream       identifier returned by theposix_trace_create() function.       A trace stream shall be created in a suspended state.  If the       Trace Event Filter option is supported, its trace event type       filter shall be empty.       Theposix_trace_create() function may be called multiple times       from the same or different processes, with the system-wide limit       indicated by the runtime invariant value {TRACE_SYS_MAX}, which       has the minimum value {_POSIX_TRACE_SYS_MAX}.       The trace stream identifier returned by theposix_trace_create()       function in the argument pointed to bytrid is valid only in the       process that made the function call. If it is used from another       process, that is a child process, in functions defined in       POSIX.1‐2008, these functions shall return with the error[EINVAL].       Theposix_trace_create_withlog() function shall be equivalent toposix_trace_create(), except that it associates a trace log with       this stream. Thefile_desc argument shall be the file descriptor       designating the trace log destination. The function shall fail if       this file descriptor refers to a file with a file type that is not       compatible with the log policy associated with the trace log. The       list of the appropriate file types that are compatible with each       log policy is implementation-defined.       Theposix_trace_create_withlog() function shall return in the       parameter pointed to bytrid the trace stream identifier, which       uniquely identifies the newly created trace stream, and shall be       used in subsequent calls to control tracing. Thetrid argument may       only be used by the following functions:posix_trace_clear()posix_trace_get_status()posix_trace_eventid_equal()posix_trace_getnext_event()posix_trace_eventid_get_name()posix_trace_shutdown()posix_trace_eventtypelist_getnext_id()posix_trace_start()posix_trace_eventtypelist_rewind()posix_trace_stop()posix_trace_flush()posix_trace_timedgetnext_event()posix_trace_get_attr()posix_trace_trid_eventid_open()       If the Trace Event Filter option is supported, the following       additional functions may use thetrid argument:posix_trace_get_filter()posix_trace_set_filter()       In particular, notice that the operations normally used by a trace       analyzer process, such asposix_trace_rewind() orposix_trace_close(), cannot be invoked using the trace stream       identifier returned by theposix_trace_create_withlog() function.       Theposix_trace_flush() function shall initiate a flush operation       which copies the contents of the trace stream identified by the       argumenttrid into the trace log associated with the trace stream       at the creation time. If no trace log has been associated with the       trace stream pointed to bytrid, this function shall return an       error. The termination of the flush operation can be polled by theposix_trace_get_status() function. During the flush operation, it       shall be possible to trace new trace events up to the point when       the trace stream becomes full.  After flushing is completed, the       space used by the flushed trace events shall be available for       tracing new trace events.       If flushing the trace stream causes the resulting trace log to       become full, the trace log full policy shall be applied. If the       tracelog-full-policy attribute is set, the following occurs:       POSIX_TRACE_UNTIL_FULL             The trace events that have not yet been flushed shall be             discarded.       POSIX_TRACE_LOOP             The trace events that have not yet been flushed shall be             written to the beginning of the trace log, overwriting             previous trace events stored there.       POSIX_TRACE_APPEND             The trace events that have not yet been flushed shall be             appended to the trace log.       Theposix_trace_shutdown() function shall stop the tracing of       trace events in the trace stream identified bytrid, as ifposix_trace_stop() had been invoked. Theposix_trace_shutdown()       function shall free all the resources associated with the trace       stream.       Theposix_trace_shutdown() function shall not return until all the       resources associated with the trace stream have been freed. When       theposix_trace_shutdown() function returns, thetrid argument       becomes an invalid trace stream identifier. A call to this       function shall unconditionally deallocate the resources regardless       of whether all trace events have been retrieved by the analyzer       process.  Any thread blocked on one of thetrace_getnext_event()       functions (which specified thistrid) before this call is       unblocked with the error[EINVAL].       If the process exits, invokes a member of theexec family of       functions, or is terminated, the trace streams that the process       had created and that have not yet been shut down, shall be       automatically shut down as if an explicit call were made to theposix_trace_shutdown() function.       For an active trace stream with log, when theposix_trace_shutdown() function is called, all trace events that       have not yet been flushed to the trace log shall be flushed, as in       theposix_trace_flush() function, and the trace log shall be       closed.       When a trace log is closed, all the information that may be       retrieved later from the trace log through the trace interface       shall have been written to the trace log. This information       includes the trace attributes, the list of trace event types (with       the mapping between trace event names and trace event type       identifiers), and the trace status.       In addition, unspecified information shall be written to the trace       log to allow detection of a valid trace log during theposix_trace_open() operation.       Theposix_trace_shutdown() function shall not return until all       trace events have been flushed.

RETURN VALUE top

       Upon successful completion, these functions shall return a value       of zero. Otherwise, they shall return the corresponding error       number.       Theposix_trace_create() andposix_trace_create_withlog()       functions store the trace stream identifier value in the object       pointed to bytrid, if successful.

ERRORS top

       Theposix_trace_create() andposix_trace_create_withlog()       functions shall fail if:EAGAINNo more trace streams can be started now.  {TRACE_SYS_MAX}              has been exceeded.EINTRThe operation was interrupted by a signal. No trace stream              was created.EINVALOne or more of the trace parameters specified by theattr              parameter is invalid.ENOMEMThe implementation does not currently have sufficient              memory to create the trace stream with the specified              parameters.EPERMThe caller does not have appropriate privileges to trace              the process specified bypid.ESRCHThepid argument does not refer to an existing process.       Theposix_trace_create_withlog() function shall fail if:EBADFThefile_desc argument is not a valid file descriptor open              for writing.EINVALThefile_desc argument refers to a file with a file type              that does not support the log policy associated with the              trace log.ENOSPCNo space left on device. The device corresponding to the              argumentfile_desc does not contain the space required to              create this trace log.       Theposix_trace_flush() andposix_trace_shutdown() functions shall       fail if:EINVALThe value of thetrid argument does not correspond to an              active trace stream with log.EFBIGThe trace log file has attempted to exceed an              implementation-defined maximum file size.ENOSPCNo space left on device.The following sections are informative.

EXAMPLES top

       None.

APPLICATION USAGE top

       None.

RATIONALE top

       None.

FUTURE DIRECTIONS top

       Theposix_trace_create(),posix_trace_create_withlog(),posix_trace_flush(), andposix_trace_shutdown() functions may be       removed in a future version.

COPYRIGHT top

       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  athttp://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,  seehttps://www.kernel.org/doc/man-pages/reporting_bugs.html .IEEE/The Open Group                2017POSIX_TRACE_CREATE(3P)

Pages that refer to this page:trace.h(0p), exec(3p), _Exit(3p), posix_trace_attr_destroy(3p), posix_trace_attr_getclockres(3p), posix_trace_attr_getinherited(3p), posix_trace_attr_getlogsize(3p), posix_trace_clear(3p), posix_trace_flush(3p), posix_trace_get_attr(3p), posix_trace_getnext_event(3p), posix_trace_shutdown(3p), posix_trace_start(3p)