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
Mac OS X 10.13.1 - Generated Wed Nov 8 15:35:37 CST 2017