NAME

os_log_create — create an object that tracks the state of logging for a given system.

SYNOPSIS

#include <os/log.h>

os_log_t
os_log_create(const char *subsystem, const char *category);

DESCRIPTION

Use os_log_create to create an object that can be passed to os_log(3) calls. Log messages to this object will be marked with the object's subsystem and category name. The behavior of log messages to this object can be configured using the log(1) command or with a logging configuration profile (see os_log(5)).

The subsystem argument should be the identifier of the subsystem in reverse DNS form. The category argument should be the category within the subsystem, for differentiating by topic and settings. Neither argument may be NULL.

The logging runtime maintains a global collection of all os_log_t objects, one per subsystem/category pair. The os_log_t for a given subsystem/category is created upon the first call to os_log_create and any subsequent calls return the same object. These objects are never deallocated, so dynamic creation (e.g. on a per-operation basis) is generally inappropriate.

RETURN VALUES

The os_log_t object for the subsystem and category. A valid, non-NULL object is always returned.

EXAMPLES

Create a new os_log_t object and log a message:

#include <os/log.h>

/* create a log object for the subsystem, specifically the "connections" category" */
os_log_t log = os_log_create("com.example.widget", "connections");

/* log a connection related message */
os_log(log, "connection state changed: %d interface: %s", if, interface);

SEE ALSO

log(1), os_log(3), os_log(5)