Manual Pages for UNIX Darwin command on man asl_set

Manual Pages for UNIX Darwin command on man asl_set_filter

asl(3) BSD Library Functions Manual asl(3)

NAME

aassllaaddddllooggffiillee, aassllcclloossee, aassllffrreeee, aassllggeett, aassllkkeeyy, aasslllloogg, aassllnneeww, aassllooppeenn, aassllrreemmoovveellooggffiillee, aassllsseeaarrcchh, aassllsseenndd, aassllsseett, aassllsseettffiilltteerr, aassllsseettqquueerryy, aasslluunnsseett, aassllvvlloogg, aassllrreessppoonnsseeffrreeee,

aassllrreessppoonnsseenneexxtt - system log message sending and searching functions

SYNOPSIS

##iinncclluuddee <>

int aassllaaddddllooggffiillee(aslclient asl, int fd); void aassllcclloossee(aslclient asl); void aassllffrreeee(aslmsg msg); const char * aassllggeett(aslmsg msg, const char *key); const char * aassllkkeeyy(aslmsg msg, uint32t n); int aasslllloogg(aslclient asl, aslmsg msg, int level, const char *format, ...); aslmsg aassllnneeww(uint32t type); aslclient aassllooppeenn(const char *ident, const char *facility, uint32t opts); int aassllrreemmoovveellooggffiillee(aslclient asl, int fd); aslresponse aassllsseeaarrcchh(aslclient asl, aslmsg msg); int aassllsseenndd(aslclient asl, aslmsg msg); int aassllsseett(aslmsg msg, const char *key, const char *value); int aassllsseettffiilltteerr(aslclient asl, int f); int aassllsseettqquueerryy(aslmsg msg, const char *key, const char *value, uint32t op); int aasslluunnsseett(aslmsg msg, const char *key); int aassllvvlloogg(aslclient asl, aslmsg msg, int level, const char *format, valist ap); void aassllrreessppoonnsseeffrreeee(aslresponse r); aslmsg aassllrreessppoonnsseenneexxtt(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 ssyyssllooggdd 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. An introduction to the concepts underlying this interface follows the interface summary below. IINNTTEERRFFAACCEE SSUUMMMMAARRYY aassllooppeenn(ident, facility, opts) creates and returns a client handle, or NULL if an error occurs in the library. Messages sent using this handle will default to having the string ident as the value assocated with the ASLKEYSENDER key, and the value facility assocated with the ASLKEYFACILITY key. Several options are available, as described in the CLIENT HANDLES section.

Multi-threaded applications should create one client handle for each

thread that logs messages. A client may use NULL as a client handle, in which case a default handle managed by the library will be used. A NULL

handle may be used safely by multiple threads, but the threads will con-

tend for a single internal lock when sending log messages using a NULL handle. aassllcclloossee(asl) closes the client handle asl and releases its associated resources. aassllaaddddllooggffiillee(asl, fd) adds the file descriptor fd to the a set of file descriptors associated with the client handle asl. Each log message sent by that client handle is also written to these file descriptors.

Returns 0 on success, non-zero on failure.

aassllrreemmoovveellooggffiillee(asl, fd) removes a file descriptor from the set of file descriptors associated with a client handle. Returns 0 on success,

non-zero on failure.

aassllnneeww(type) allocates and returns an aslmsg structure, or NULL in the case of a failure in the library. The type argument must be ASLTYPEMSG or ASLTYPEQUERY. aassllffrreeee(msg) frees an aslmsg and releases resources associated with the structure.

aassllsseett(msg, key, value) creates a new key and value in an aslmsg struc-

ture, or replaces the value of an existing key. Returns 0 on success,

non-zero on failure.

aassllsseettqquueerryy(msg, key, op, value) is used to construct searches. It is similar to aassllsseett(), except that it takes an additional op (operation) argument. Creates a new (key, op, value) triple in an aslmsg structure, or replaces the value and operation for an existing key. See the

SEARCHING section for more information. Returns 0 on success, non-zero

on failure. aasslluunnsseett(msg, key) removes a key and its associated value from an aslmsg

structure. Returns 0 on success, non-zero on failure.

aassllkkeeyy(msg, n) returns the nth key in an aslmsg (beginning at zero), allowing an application to iterate through the keys. Returns NULL if n indexes beyond the number of keys in msg. aassllggeett(msg, key) returns the value associated with key in the aslmsg msg. Returns NULL if msg does not contain key. aassllsseettffiilltteerr(asl, f) sets a filter for messages being sent to the

server. The filter is a bitmask representing priority levels. Only mes-

sages having a priority level with a corresponding bit set in the filter mask are sent to the ssyyssllooggdd server. The filter does not control writes to additional files associated with the client handle using aassllaaddddllooggffiillee(). Returns the previous filter value.

aasslllloogg(asl, msg, level, format, args...) sends a log to the server (sub-

ject to filtering, see aassllsseettffiilltteerr() above) and to any file descrip-

tors associated with the client handle asl. The msg argument may contain any keys and values, which will be formatted as part of the log message. The value for ASLKEYLEVEL is supplied by the level argument. The value for ASLKEYMESSAGE is computed from format and the associated arguments args.... Normal pprriinnttff() style argument processing is applied to the

format and the arguments. The format may also contain ``%m'' which will

be substituted with the string value corresponding to the current errno. aassllvvlloogg(asl, msg, level, format, ap) is similar to aasslllloogg() except that it takes a valist argument. aassllsseenndd(asl, msg) is similar to aasslllloogg(), exceopt the value for ASLKEYMESSAGE is taken from msg rather than being constructed using a pprriinnttff() style syntax. aassllsseeaarrcchh(asl, msg) searches for messages that match the keys and values in msg, subject to matching operations associated with those keys and values. The msg argument should be constructed using aassllsseettqquueerryy(). See the SEARCHING section for details on constructing queries. Returns an aslresponse structure that contains matching log messages. NULL is returned in case of error or if there are no matching messages in the ASL database. aassllrreessppoonnsseenneexxtt(r) iterates over an aslresponse structure returned by aassllsseeaarrcchh(). Each call returns the next aslmsg in the response. Returns NULL when there are no further messages. aassllrreessppoonnsseeffrreeee(r) frees the aslresponse structure r and all of its associated resources. MMEESSSSAAGGEESS 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-character terminated C lan-

guage strings. UTF-8 encoding may be used for non-ASCII 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. 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 that are 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 ASLKEYFACILITY "Facility"

#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. The asl(3) API does not require a process to choose a facility name. The ssyyssllooggdd 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 aassllooppeenn call, or by setting a specific value for the ASLKEYFACILITY in a message: aslset(m, ASLKEYFACILITY, "com.somename.greatservice"); An application may choose any facility name at will. Different facility

names may be attached to different messages, perhaps to distinguish dif-

ferent subsystems in log messages. Developers are encouraged 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 ASLKEYMSG, which may be explicitly set at any time using the aassllsseett routine, or implicitly set at the time the message is sent using

the aasslllloogg or aassllvvlloogg 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(NULL, NULL, ASLLEVELINFO, "Hello World!"); Both aasslllloogg and aassllvvlloogg will provide the appropriate default values when passed a NULL aslmsg argument. 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 should open a separate client handle using aassllooppeenn. The client handle may then be closed when it is no longer required using aassllcclloossee. Multiple threads may log messages safely using a NULL aslclient argument, but the library will use an internal lock, so that in fact only one thread will log at a time. 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, ASLKEYFACILITY, "com.secrets.r.us"); aslset(m, "Clearance", "Top Secret"); ... asllog(NULL, m, ASLLEVELNOTICE, "Message One"); ... asllog(NULL, m, ASLLEVELERR, "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 aasslllloogg, while the log level and the message text are taken from the calling parameters. The format argument to aasslllloogg and aassllvvlloogg 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 aasslluunnsseett. A message may be freed using aassllffrreeee.

The aassllsseenndd routine is used by aasslllloogg and aassllvvlloogg to transmit a mes-

sage to the server. This routine sets the value associated with ASLKEYTIME and sends the message. It may be called directly if all of a message's key/value pairs have been created using aassllsseett. SSEECCUURRIITTYY Messages that are sent to the ssyyssllooggdd server may be saved in a message store. The store may be searched using aassllsseeaarrcchh, as described below.

By default, all messages are readable by any user. However, some appli-

cations may wish to restrict read access for some messages. To accomo-

date this, a client may set a value for the "ReadUID" and "ReadGID" keys.

These keys may be associated with a value containing an ASCII representa-

tion 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 ssyysslloogg 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 generally allows any string to be used as a facility value, with one exception. The value "com.apple.system", 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 ssyyssllooggdd server. CCLLIIEENNTT HHAANNDDLLEESS 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 applica-

tion. If multiple threads must do logging, or if client options are desired, then the application should call aassllooppeenn to create a client handle for each thread. As a convenience, the aassllooppeenn routine may be given an ident argument, which becomes the default value for the ASLKEYSENDER key, and a facility argument, which becomes the value associated with the ASLKEYFACILITY key. Several options are available when creating a client handle. They are: ASLOPTSTDERR adds stderr as an output file descriptor ASLOPTNODELAY connects to the server immediately

ASLOPTNOREMOTE disables remote-control filter adjustment

ASLOPTNODELAY makes the client library connect to the ssyyssllooggdd server at the time that aassllooppeenn is called, rather than waiting for the first message to be sent. Opening the connection is quite fast, but some applications may want to avoid any unnecessary delays when calling aasslllloogg, aassllvvlloogg, or aassllsseenndd. 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 aassllcclloossee. Note that if additional file descriptors were added to the handle, either using the ASLOPTSTDERR option or afterwards with the aassllaaddddllooggffiillee routine, those file descriptors are not closed by aassllcclloossee. LOGGING TO ADDITIONAL FILES If a client handle is opened with the ASLOPTSTDERR option to aassllooppeenn, a copy of each log message will be sent to stderr. Additional output streams may be include using aassllaaddddllooggffiillee.

Messages sent to stderr or other files are printed in the "standard" mes-

sage format also used as a default format by the syslog(1) command line

utility. Non-ASCII characters in a message are encoded using the

``safe'' encoding style used by syslog(1) with the -EE safe option.

Backspace characters are printed as ^H. Carriage returns are mapped to newlines. A tab character is appended after newlines so that message text is indented. File descriptors may be removed from the list of outputs associated with a client handle with aassllrreemmoovveellooggffiillee. This routine simply removes the file descriptor from the output list. The file is not closed as a result. The ASLOPTSTDERR option may not be unset after a client handle has been opened. SSEEAARRCCHHIINNGG The ssyyssllooggdd server archives received messages in a data store that may be searched using the aassllsseeaarrcchh, aassllrreessppoonnsseenneexxtt, and aassllrreessppoonnsseeffrreeee routines. A query message is created using: aslmsg q = aslnew(ASLTYPEQUERY); Search settings are made in the query using aassllsseettqquueerryy. A search is performed on the data store with aassllsseeaarrcchh. It returns an aslresponse structure. The caller may then call aassllrreessppoonnsseenneexxtt to iterate through matching messages. The aslresponse structure may be freed with aassllrreessppoonnsseeffrreeee. 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(NULL, 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 ASLQUERYOPLESS value less than ASLQUERYOPLESSEQUAL 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

ASLQUERYOPPREFIX match a leading substring ASLQUERYOPSUFFIX match a trailing substring ASLQUERYOPSUBSTRING match any substring ASLQUERYOPNUMERIC values are converted to integer using aattooii 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", ASLQUERYOPLESSEQUAL | ASLQUERYOPNUMERIC); r = aslsearch(NULL, q); After calling aassllsseeaarrcchh to get an aslresponse structure, use aassllrreessppoonnsseenneexxtt to iterate through all matching messages. To iterate through the keys and values in a message, use aassllkkeeyy to iterate through the keys, then call aassllggeett to get the value associated with each key. aslmsg q, m; int i; const char *key, *val; ... r = aslsearch(NULL, q); while (NULL != (m = aslresponsenext(r))) { for (i = 0; (NULL != (key = aslkey(m, i))); i++) { val = aslget(m, key); ... } } aslresponsefree(r); FFIILLTTEERRIINNGG AANNDD RREEMMOOTTEE CCOONNTTRROOLL

Clients may set a filter mask value with aassllsseettffiilltteerr. The mask speci-

fies which messages should be sent to the ssyyssllooggdd 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. aassllsseettffiilltteerr rreettuurrnnss tthhee pprreevviioouuss vvaalluuee ooff tthhee ffiilltteerr,, ii..ee.. tthhee vvaalluuee ooff tthhee ffiilltteerr bbeeffoorree tthhee rroouuttiinnee wwaass ccaalllleedd..

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 ASLLEVELEMERG to a given input level. The default filter mask is ASLFILTERMASKUPTO(ASLLEVELNOTICE). This

means that by default, and in the absence of remote-control changes

(described below), ASLLEVELDEBUG and ASLLEVELINFO 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 aassllsseettffiilltteerr 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 ssyysslloogg command, using the -cc 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 ssyysslloogg command,

using the -cc 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 aassllooppeenn 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.