mdoc warning: Extraneous .Ed (#77)

os_trace(3)              BSD Library Functions Manual              os_trace(3)

NAME
     os_trace, os_trace_debug, os_trace_error, os_trace_fault -- trace message
     for the current activity

SYNOPSIS
     #include <os/trace.h>

     void
     os_trace(const char *format, ...);

     void
     os_trace_debug(const char *format, ...);

     void
     os_trace_error(const char *format, ...);

     void
     os_trace_fault(const char *format, ...);

DESCRIPTION
     This interface is deprecated and replaced by os_log(3).

     os_trace and its variants use a memory-only buffer to store the provided
     trace message.  Trace messages are correlated based on a new identifier
     assigned when an activity is created by the system, see
     os_activity_initiate(3).  The identifier is automatically carried across
     GCD and XPC boundaries.  This identifier provides a correlation point for
     intra and inter-process work based on that activity.

     Trace messages should never be done in tight loops as they may overrun
     the buffer pushing relevant trace messages out. Loss of those entries
     reduces the effectiveness of the trace mechanism.

     The API was designed to prevent strings from being recorded in the
     buffers for performance and privacy protection.  See os_log(3) for string
     and object support, among other features. The os_trace API set only sup-
     ports scalar types (float,double, etc.).  All unsupported types will emit
     UNSUP to the trace output.  The format string length does not factor into
     the trace buffer memory, although there is a maximum supported length of
     100 characters.

     Inappropriate use of strings in messages:

           os_trace("user %s logged in from hostname %s", username, host);

     Will output:

           user UNSUP logged in from hostname UNSUP

     There are four(4) types of trace messages: default, debug, error, and
     fault.

     os_trace is a "default" trace message.  The default category of messages
     are always recorded into the memory buffers regardless of the state of
     the process.  Limit use to messages that would help diagnose a failure,
     crash, etc.

           os_trace("issue query for record type: %d, timeout: %d", recType, timeout);

     os_trace_debug is a "debug" trace message.  The debug category of mes-
     sages are only recorded if the process is under a debugger or is specifi-
     cally requested to include debug messages.  Debug messages should be used
     for development use while debugging a problem.

     os_trace_error is an "error" trace message.  The error category of mes-
     sages should be used when a process encounters a soft-error (i.e., an
     unexpected error that was successfully avoided).

     os_trace_fault is a "fault" trace message.  The fault category of mes-
     sages should be used when a process is about to crash or would otherwise
     crash but recovered.  This call causes a collection of all buffers
     related to activity that triggered the fault.  The buffers are analyzed
     and may be provided in crash/spin reports.

EXAMPLES
     Example use of trace messages.

           #include <os/trace.h>
           #include <pwd.h>

           uid_t uid;

           os_trace("looking up user %d", uid);
           struct passwd *pwd = getpwuid(uid);
           if (pwd == NULL) {
               os_trace_error("failed to lookup user %d", uid);
               return ENOENT;
           }

           error = _openPref(pwd->pw_name, pwd->pw_dir);
           if (error) {
               os_trace_error("failed to open prefs %d", error);
               return error;
           }

CAVEATS
     Please note that os_trace is printf-like, but not printf-compatible. For-
     mat specifiers should be exactly matched to the types of the arguments
     being used to fill them.

SEE ALSO
     os_log(3), os_log_create(3), os_activity_initiate(3)

Darwin                           June 2, 2016                           Darwin