asl(3) BSD Library Functions Manual asl(3)
NAME
aslopen, aslclose, aslnew, aslfree, aslset, aslsetquery, aslget,
aslunset, asllog, aslvlog, aslsend, aslkey, asladdlogfile,
aslremovelogfile, aslsetcutofflevel, aslsearch, aslresponsenext,
aslresponsefree -- system log message sending and searching functions
SYNOPSIS
##include <>
aslclient
aslopen(const char *ident, const char *facility, uint32t opts);
void
aslclose(aslclient asl);
aslmsg
aslnew(uint32t type);
void
aslfree(aslmsg msg);
int
aslset(aslmsg msg, const char *key, const char *value);
int
aslsetquery(aslmsg msg, const char *key, const char *value, uint32t op);
const char *
aslkey(aslmsg msg, uint32t n);
const char *
aslget(aslmsg msg, const char *key);
int
aslunset(aslmsg msg, const char *key);
int
asllog(aslclient asl, aslmsg msg, int level, const char *format, ...);
int
aslvlog(aslclient asl, aslmsg msg, int level, const char *format, valist ap);
int
aslsend(aslclient asl, aslmsg msg);
int
asladdlogfile(aslclient asl, int fd);
int
aslremovelogfile(aslclient asl, int fd);
int
aslsetfilter(aslclient asl, int f);
aslresponse
aslsearch(aslclient asl, aslmsg msg);
aslmsg
aslresponsenext(aslresponse r);
void
aslresponsefree(aslresponse a);
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.
MESAGES
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 NUL-terminated C language
character strings. UTF-8 encoding may be used for non-ASCI characters.
Message structures are generally used to send log messages, and are cre-
ated thusly:
aslmsg m = aslnew(ASLTYPEMSG);
Another message type, ASLTYPEQUERY, 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 ASLTYPEMSG variety.
Each aslmsg contains a default set of keys and values associated with
them. These keys are listed in the asl.h header file. They are:
#define ASLKEYTIME "Time"
#define ASLKEYHOST "Host"
#define ASLKEYSENDER "Sender"
#define ASLKEYPID "PID"
#define ASLKEYUID "UID"
#define ASLKEYGID "GID"
#define ASLKEYLEVEL "Level"
#define ASLKEYMSG "Message"
Many of these correspond to equivalent parts of messages described in the
syslog(3) API. Values associated with these message keys are assigned
appropriate defaults. The value for ASLKEYHOST is the local host name,
the value associated with ASLKEYSENDER is the process name, the
ASLKEYPID 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.
Also note the absence of a Facility key. 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 using:
aslset(m, "Facility", "UsefulService");
An application may choose any facility name at will.
Default values are set in the message for each of the keys listed above
except for ASLKEYMSG, which may be explicitly set at any time using the
aslset routine, or implicitly set at the time the message is sent using
the asllog or aslvlog routines. These two routines also have an inte-
ger level parameter for specifying the log priority. The ASLKEYLEVEL
value is set accordingly. Finally, the value associated with
ASLKEYTIME 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 sim-
ple ``Hello World'' program requires only:
#include
...
asllog(NUL, NUL, ASLEVELINFO, "Hello World!");
Both asllog and aslvlog will provide the appropriate default values
when passed a NUL aslmsg argument.
In this example, the aslclient argument is NUL. 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 aslopen. The client
handle may then be closed when it is no longer required using aslclose.
When an application requires additional keys and values to be associated
with each log message, a single message structure may be allocated and
set up as ``template'' message of sorts:
aslmsg m = aslnew(ASLTYPEMSG);
aslset(m, "Facility", "Spy vs. Spy");
aslset(m, "Clearance", "Top Secret");
...
asllog(NUL, m, ASLEVELNOTICE, "Message One");
...
asllog(NUL, m, ASLEVELER, "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 asllog, while
the log level and the message text are taken from the calling parameters.
Key/value pairs may be removed from a message structure with aslunset.
A message may be freed using aslfree.
The aslsend routine is used by asllog and aslvlog to transmit a mes-
sage to the server. This routine sets the value associated with
ASLKEYTIME and send the message. It may be called directly if all of a
message's key/value pairs have been created using aslset.
CLIENT HANDLES
When logging is done from a single thread, a NUL 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 aslopen to create a client handle for
each thread. As a convenience, the aslopen routine may be given an
ident argument, which becomes the default value for the ASLKEYSENDER
key, and a facility argument, which becomes the default facility name for
the application.
Several options are available when creating a client handle. They are:
ASLOPTSTDER adds stderr as an output file descriptor
ASLOPTNODELAY connects to the server immediately
ASLOPTNOREMOTE 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 aslclose.
Note that if additional file descriptors were added to the handle either
using the ASLOPTSTDER option or afterwards with the asladdlogfile
routine, those file descriptors are not closed by aslclose.
LOGING TO ADITIONAL FILES
If a client handle is opened with the ASLOPTSTDER option to aslopen,
a copy of each log message will be sent to stderr. Additional output
streams may be include using asladdlogfile. File descriptors may be
removed from the list of outputs associated with a client handle with
aslremovelogfile. This routine simply removes the file descriptor
from the output list. The file is not closed as a result.
The ASLOPTSTDER 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 sent to file descriptors 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 aslsearch, aslresponsenext, and aslresponsefree
routines. A query message is created using:
aslmsg q = aslnew(ASLTYPEQUERY);
Search settings are made in the query using aslsetquery. A search is
performed on the data store with aslsearch. It returns an aslresponse
structure. The caller may then call aslresponsenext to iterate through
matching messages. The aslresponse structure may be freed with
aslresponsefree.
Like other messages, ASLTYPEQUERY 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 ASLQUERYOPEQUAL, which tests for equality. For example, the fol-
lowing code snippet searches for messages with a Sender value equal to
``MyApp''.
aslmsg m;
aslresponse r;
q = aslnew(ASLTYPEQUERY);
aslsetquery(q, ASLKEYSENDER, "MyApp", ASLQUERYOPEQUAL);
r = aslsearch(NUL, q);
More complex searches may be performed using other query operations.
ASLQUERYOPEQUAL value equality
ASLQUERYOPGREATER value greater than
ASLQUERYOPGREATEREQUAL value greater than or equal to
ASLQUERYOPLES value less than
ASLQUERYOPLESEQUAL value less than or equal to
ASLQUERYOPNOTEQUAL value not equal
ASLQUERYOPREGEX regular expression search
ASLQUERYOPTRUE always true - use to test for the existence
of a key
Regular expression search uses regex(3) library. Patterns are compiled
using the REGEXTENDED and REGNOSUB options.
Modifiers that change the behavior of these operations may also be speci-
fied by ORing the modifier value with the operation. The modifiers are:
ASLQUERYOPCASEFOLD string comparisons are case-folded
ASLQUERYOPREFIX match a leading substring
ASLQUERYOPSUFIX match a trailing substring
ASLQUERYOPSUBSTRING match any substring
ASLQUERYOPNUMERIC values are converted to integer using atoi
The only modifier that is checked for ASLQUERYOPREGEX search is
ASLQUERYOPCASEFOLD. This causes the regular expression to be compiled
with the REGICASE option.
If a query message contains more than one set of key/value/operation
triples, the result will be a logical AND. For example, to find messages
from ``MyApp'' with a priority level less than or equal to ``3'':
aslmsg q;
aslresponse r;
q = aslnew(ASLTYPEQUERY);
aslsetquery(q, ASLKEYSENDER, "MyApp", ASLQUERYOPEQUAL);
aslsetquery(q, ASLKEYLEVEL, "3",
ASLQUERYOPLESEQUAL ASLQUERYOPNUMERIC);
r = aslsearch(NUL, q);
After calling aslsearch to get an aslresponse structure, use
aslresponsenext to iterate through all matching messages. To iterate
through the keys and values in a message, use aslkey to iterate through
the keys, then call aslget to get the value associated with each key.
aslmsg q, m;
int i;
const char *key, *val;
...
r = aslsearch(NUL, q);
while (NUL != (m = aslresponsenext(r)))
{
for (i = 0; (NUL != (key = aslkey(m, i))); i])
{
val = aslget(m, key);
...
}
}
aslresponsefree(r);
FILTERING AND REMOTE CONTROL
Clients may set a filter mask value with aslsetfilter. The mask speci-
fies 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 priority 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 unneces-
sary.
As a convenience, the macros ASLFILTERMASK(level) and ASLFIL-
TERMASKUPTO(level) may be used to construct a bit mask corresponding to
a given priority level, or corresponding to a bit mask for all priority
levels from ASLEVELEMERG to a given input level.
The default filter mask is ASLFILTERMASKUPTO(ASLEVELNOTICE). This
means that by default, and in the absence of remote-control changes
(described below), ASLEVELDEBUG and ASLEVELINFO priority level mes-
sages are not sent to the server.
Three different filters exist for each application. The first is the
filter mask set using aslsetfilter as described above. The Apple Sys-
tem Log facility also manages a ``master'' filter mask. The master fil-
ter 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 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 ASLOPTNOREMOTE option to aslopen 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 filter mask for a root (UID 0) process.
HISTORY
These functions first appeared in Mac OS X 10.4.
SEE ALSO
syslogd(8), syslog(1)
Mac OS X January 5, 2005 Mac OS X
|
