asl(3) BSD Library Functions Manual asl(3)
NAME
asl_add_log_file, asl_close, asl_free, asl_get, asl_key, asl_log, asl_new, asl_open,
asl_remove_log_file, asl_search, asl_send, asl_set, asl_set_filter, asl_set_query, asl_unset, asl_vlog,
aslresponse_free, aslresponse_next -- system log message sending and searching functions
SYNOPSIS
#include <asl.h>
int
asl_add_log_file(aslclient asl, int fd);
void
asl_close(aslclient asl);
void
asl_free(aslmsg msg);
const char *
asl_get(aslmsg msg, const char *key);
const char *
asl_key(aslmsg msg, uint32_t n);
int
asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...);
aslmsg
asl_new(uint32_t type);
aslclient
asl_open(const char *ident, const char *facility, uint32_t opts);
int
asl_remove_log_file(aslclient asl, int fd);
aslresponse
asl_search(aslclient asl, aslmsg msg);
int
asl_send(aslclient asl, aslmsg msg);
int
asl_set(aslmsg msg, const char *key, const char *value);
int
asl_set_filter(aslclient asl, int f);
int
asl_set_query(aslmsg msg, const char *key, const char *value, uint32_t op);
int
asl_unset(aslmsg msg, const char *key);
int
asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap);
void
aslresponse_free(aslresponse a);
aslmsg
aslresponse_next(aslresponse r);
DESCRIPTION
These routines provide an interface to the Apple System Log facility. They are intended to be a
replacement for the syslog(3) API, which will continue to be supported for backwards compatibility.
The new API allows client applications to create flexible, structured messages and send them to the
syslogd server, where they may undergo additional processing. Messages received by the server are
saved in a data store (subject to input filtering constraints). This API permits clients to create
queries and search the message data store for matching messages.
MESSAGES
At the core of this API is the aslmsg structure. Although the structure is opaque and may not be
directly manipulated, it contains a list of key/value pairs. All keys and values are NULL-terminated C
language character strings. UTF-8 encoding may be used for non-ASCII characters.
Message structures are generally used to send log messages, and are created thusly:
aslmsg m = asl_new(ASL_TYPE_MSG);
Another message type, ASL_TYPE_QUERY, is used to create queries when searching the data store. Query
type messages and searching are described in detail in the SEARCHING section below. For the remainder
of this section, the messages described will be of the ASL_TYPE_MSG variety.
Each aslmsg contains a default set of keys and values that are associated with them. These keys are
listed in the asl.h header file. They are:
#define ASL_KEY_TIME "Time"
#define ASL_KEY_HOST "Host"
#define ASL_KEY_SENDER "Sender"
#define ASL_KEY_FACILITY "Facility"
#define ASL_KEY_PID "PID"
#define ASL_KEY_UID "UID"
#define ASL_KEY_GID "GID"
#define ASL_KEY_LEVEL "Level"
#define ASL_KEY_MSG "Message"
Many of these correspond to equivalent parts of messages described in the syslog(3) API. Values asso-ciated associated
ciated with these message keys are assigned appropriate defaults. The value for ASL_KEY_HOST is the
local host name, the value associated with ASL_KEY_SENDER is the process name, the ASL_KEY_PID is the
client's process ID number, and so on.
Note the addition of the UID and GID keys. The values for UID and GID are set in library code by the
message sender. The server will attempt to confirm the values, but no claim is made that these values
cannot be maliciously overridden in an attempt to deceive a log message reader as to the identity of
the sender of a message. The contents of log messages must be regarded as insecure.
The asl(3) API does not require a process to choose a facility name. The syslogd server will use a
default value of ``user'' if a facility is not set. However, a client may set a facility name as an
argument in the asl_open call, or by setting a specific value for the ASL_KEY_FACILITY in a message:
asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");
An application may choose any facility name at will. Different facility names may be attached to dif-ferent different
ferent messages, perhaps to distinguish different subsystems in log messages. Developers are encour-aged encouraged
aged to adopt a ``Reverse ICANN'' naming convention to avoid conflicting facility names.
Default values are set in the message for each of the keys listed above, except for ASL_KEY_MSG, which
may be explicitly set at any time using the asl_set routine, or implicitly set at the time the message
is sent using the asl_log or asl_vlog routines. These two routines also have an integer-level parame-ter parameter
ter for specifying the log priority. The ASL_KEY_LEVEL value is set accordingly. Finally, the value
associated with ASL_KEY_TIME is set in the sending routine.
Although it may appear that there is significant overhead required to send a log message using this
API, the opposite is actually true. A simple ``Hello World'' program requires only:
#include <asl.h>
...
asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!");
Both asl_log and asl_vlog will provide the appropriate default values when passed a NULL aslmsg argu-ment. argument.
ment.
In this example, the aslclient argument is NULL. This is sufficient for a single-threaded application,
or for an application which only sends log messages from a single thread. When logging from multiple
threads, each thread must open a separate client handle using asl_open. The client handle may then be
closed when it is no longer required using asl_close.
When an application requires additional keys and values to be associated with each log message, a sin-gle single
gle message structure may be allocated and set up as ``template'' message of sorts:
aslmsg m = asl_new(ASL_TYPE_MSG);
asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us");
asl_set(m, "Clearance", "Top Secret");
...
asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One");
...
asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two");
The message structure will carry the values set for the ``Facility'' and ``Clearance'' keys so that
they are used in each call to asl_log, while the log level and the message text are taken from the
calling parameters.
The format argument to asl_log and asl_vlog is identical to printf(3), and may include `%m', which is
replaced by the current error message (as denoted by the global variable errno; see strerror(3).)
Key/value pairs may be removed from a message structure with asl_unset. A message may be freed using
asl_free.
The asl_send routine is used by asl_log and asl_vlog to transmit a message to the server. This routine
sets the value associated with ASL_KEY_TIME and sends the message. It may be called directly if all of
a message's key/value pairs have been created using asl_set.
SECURITY
Messages that are sent to the syslogd server may be saved in a message store. The store may be
searched using asl_search, as described below. By default, all messages are readable by any user.
However, some applications may wish to restrict read access for some messages. To accomodate this, a
client may set a value for the "ReadUID" and "ReadGID" keys. These keys may be associated with a value
containing an ASCII representation of a numeric UID or GID. Only the root user (UID 0), the user with
the given UID, or a member of the group with the given GID may fetch access-controlled messages from
the database.
Although the ASL system does not require a "Facility" key in a message, many processes specify a
"Facility" value similar to the common usage of the BSD syslog API, although developers are encouraged
to adopt facility names that make sense for their application. A ``Reverse ICANN'' naming convention
(e.g. "com.apple.system.syslog") should be adopted to avoid conflicting names. The ASL system gener-ally generally
ally allows any string to be used as a facility value, with one exception. The value "com.apple.sys-tem", "com.apple.system",
tem", or any string that has "com.apple.system" as a prefix, may only be used by processes running with
the UID 0. This allows system processes to log messages that can not be "spoofed" by user processes.
Non-UID 0 client processes that specify "com.apple.system" as a facility, will be assigned the value
"user" by the syslogd server.
CLIENT HANDLES
When logging is done from a single thread, a NULL value may be used in any of the routines that require
an aslclient argument. In this case, the library will open an internal client handle on behalf of the
application.
If multiple threads must do logging, or if client options are desired, then the application should call
asl_open to create a client handle for each thread. As a convenience, the asl_open routine may be
given an ident argument, which becomes the default value for the ASL_KEY_SENDER key, and a facility
argument, which becomes the value associated with the ASL_KEY_FACILITY key.
Several options are available when creating a client handle. They are:
ASL_OPT_STDERR adds stderr as an output file descriptor
ASL_OPT_NO_DELAY connects to the server immediately
ASL_OPT_NO_REMOTE disables remote-control filter adjustment
See the FILTERING section below, and the syslog(1) for additional details on filter controls.
A client handle is closed and it's resources released using asl_close. Note that if additional file
descriptors were added to the handle, either using the ASL_OPT_STDERR option or afterwards with the
asl_add_log_file routine, those file descriptors are not closed by asl_close.
LOGGING TO ADDITIONAL FILES
If a client handle is opened with the ASL_OPT_STDERR option to asl_open, a copy of each log message
will be sent to stderr. Additional output streams may be include using asl_add_log_file.
Messages sent to stderr or other files are printed in the "standard" message format also used as a
default format by the syslog(1) command line utility. The strvis(3) encoding with the VIS_CSTYLE,
VIS_TAB, and VIS_NL options is used to print the message.
File descriptors may be removed from the list of outputs associated with a client handle with
asl_remove_log_file. This routine simply removes the file descriptor from the output list. The file
is not closed as a result.
The ASL_OPT_STDERR option may not be unset after a client handle has been opened.
In the present release of Mac OS X, a ``raw'' format is used to format messages that are sent to file
descriptors that have been added to a client handle. Each message is preceded by a 10-character field
containing a message length. The message length is padded with leading white space. The length gives
the string length of the remainder of the output string. Following the length is a space character,
and then the message. The message is encoded as a set of key/value pairs enclosed in square brackets,
which are themselves separated by a space character. The key is separated from the value by space
character. Embedded closing square brackets are escaped by a backslash. Embedded space characters in
keys are escaped by a backslash; Embedded newlines are summarily turned into semicolons. The output is
terminated by a trailing newline and a NUL character.
SEARCHING
The syslogd server archives received messages in a data store that may be searched using the
asl_search, aslresponse_next, and aslresponse_free routines. A query message is created using:
aslmsg q = asl_new(ASL_TYPE_QUERY);
Search settings are made in the query using asl_set_query. A search is performed on the data store
with asl_search. It returns an aslresponse structure. The caller may then call aslresponse_next to
iterate through matching messages. The aslresponse structure may be freed with aslresponse_free.
Like other messages, ASL_TYPE_QUERY messages contain keys and values. They also associate an operation
with each key and value. The operation is used to decide if a message matches the query. The simplest
operation is ASL_QUERY_OP_EQUAL, which tests for equality. For example, the following code snippet
searches for messages with a Sender value equal to ``MyApp''.
aslmsg m;
aslresponse r;
q = asl_new(ASL_TYPE_QUERY);
asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
r = asl_search(NULL, q);
More complex searches may be performed using other query operations.
ASL_QUERY_OP_EQUAL value equality
ASL_QUERY_OP_GREATER value greater than
ASL_QUERY_OP_GREATER_EQUAL value greater than or equal to
ASL_QUERY_OP_LESS value less than
ASL_QUERY_OP_LESS_EQUAL value less than or equal to
ASL_QUERY_OP_NOT_EQUAL value not equal
ASL_QUERY_OP_REGEX regular expression search
ASL_QUERY_OP_TRUE always true - use to test for the existence of a key
Regular expression search uses regex(3) library. Patterns are compiled using the REG_EXTENDED and
REG_NOSUB options.
Modifiers that change the behavior of these operations may also be specified by ORing the modifier
value with the operation. The modifiers are:
ASL_QUERY_OP_CASEFOLD string comparisons are case-folded
ASL_QUERY_OP_PREFIX match a leading substring
ASL_QUERY_OP_SUFFIX match a trailing substring
ASL_QUERY_OP_SUBSTRING match any substring
ASL_QUERY_OP_NUMERIC values are converted to integer using atoi
The only modifier that is checked for ASL_QUERY_OP_REGEX search is ASL_QUERY_OP_CASEFOLD. This causes
the regular expression to be compiled with the REG_ICASE option.
If a query message contains more than one set of key/value/operation triples, the result will be a log-ical logical
ical AND. For example, to find messages from ``MyApp'' with a priority level less than or equal to
``3'':
aslmsg q;
aslresponse r;
q = asl_new(ASL_TYPE_QUERY);
asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
asl_set_query(q, ASL_KEY_LEVEL, "3",
ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC);
r = asl_search(NULL, q);
After calling asl_search to get an aslresponse structure, use aslresponse_next to iterate through all
matching messages. To iterate through the keys and values in a message, use asl_key to iterate through
the keys, then call asl_get to get the value associated with each key.
aslmsg q, m;
int i;
const char *key, *val;
...
r = asl_search(NULL, q);
while (NULL != (m = aslresponse_next(r)))
{
for (i = 0; (NULL != (key = asl_key(m, i))); i++)
{
val = asl_get(m, key);
...
}
}
aslresponse_free(r);
FILTERING AND REMOTE CONTROL
Clients may set a filter mask value with asl_set_filter. The mask specifies which messages should be
sent to the syslogd daemon by specifying a yes/no setting for each priority level. Clients typically
set a filter mask to avoid sending relatively unimportant messages. For example, Debug or Info prior-ity priority
ity level messages are generally only useful for debugging operations. By setting a filter mask, a
process can improve performance by avoiding sending messages that are in most cases unnecessary.
asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the
routine was called.
As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(level) may be used to con-struct construct
struct a bit mask corresponding to a given priority level, or corresponding to a bit mask for all pri-ority priority
ority levels from ASL_LEVEL_EMERG to a given input level.
The default filter mask is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE). This means that by default, and in
the absence of remote-control changes (described below), ASL_LEVEL_DEBUG and ASL_LEVEL_INFO priority
level messages are not sent to the server.
Three different filters exist for each application. The first is the filter mask set using
asl_set_filter as described above. The Apple System Log facility also manages a ``master'' filter
mask. The master filter mask usually has a value that indicates to the library that it is ``off'', and
thus it has no effect. However, the mask filter mask may be enabled by giving it a value using the
syslog command, using the -c 0 option. When the master filter mask has been set, it takes precedence
over the client's filter mask. The client's mask is unmodified, and will become active again if
remote-control filtering is disabled.
In addition to the master filter mask, The Apple System Log facility also manages a per-client remote-control remotecontrol
control filter mask. Like the master filter mask, the per-client mask is usually ``off'', having no
effect on a client. If a per-client filter mask is set using the syslog command, using the -c process
option, then it takes precedence over both the client's filter mask and the master filter mask. As is
the case with the master filter mask, a per-client mask ceases having any effect when if is disabled.
The ASL_OPT_NO_REMOTE option to asl_open causes both the master and per-client remote-control masks to
be ignored in the library. In that case, only the client's own filter mask is used to determine which
messages are sent to the server. This may be useful for Applications that produce log messages that
should never be filtered, due to security considerations. Note that root (administrator) access is
required to set or change the master filter mask, and that only root may change a per-client remote-control remotecontrol
control filter mask for a root (UID 0) process.
HISTORY
These functions first appeared in Mac OS X 10.4.
SEE ALSO
syslog(1), strvis(3), syslogd(8)
Mac OS X January 11, 2007 Mac OS X
|