os_trace_error(3) [mojave man page]

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 identi-
     fier 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 supports 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 messages are only recorded if the process is under a debugger or is specif-
     ically 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 messages 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 messages 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. Format specifiers should be exactly matched to the types of the argu-
     ments being used to fill them.

SEE ALSO

     os_log(3), os_log_create(3), os_activity_initiate(3)

Darwin								   June 2, 2016 							    Darwin