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 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 specifically 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;
}
SEE ALSO
CAVEATS
Please note that os_trace is printf-like, but not printf-compatible. Format specifiers should be exactly matched to the types of the arguments being used to fill them.