Libc-825.24.tar.gz

[apple/libc.git] / gen / asl.3

.\" Copyright (c) 2005-2011 Apple Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of Apple Computer nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"
.Dd October 1, 2011
.Dt asl 3
.Os "Mac OS X"
.Sh NAME
.Nm asl_add_log_file ,
.Nm asl_close ,
.Nm asl_close_auxiliary_file ,
.Nm asl_create_auxiliary_file ,
.Nm asl_free ,
.Nm asl_get ,
.Nm asl_key ,
.Nm asl_log ,
.Nm asl_log_auxiliary_location ,
.Nm asl_log_descriptor ,
.Nm asl_new ,
.Nm asl_open ,
.Nm asl_open_from_file ,
.Nm asl_remove_log_file ,
.Nm asl_search ,
.Nm asl_send ,
.Nm asl_set ,
.Nm asl_set_filter ,
.Nm asl_set_query ,
.Nm asl_unset ,
.Nm asl_vlog ,
.Nm aslresponse_free ,
.Nm aslresponse_next
.Nd system log message sending and searching functions
.Sh SYNOPSIS
.Fd #include <asl.h>
.\"
.Ft int
.Fo asl_add_log_file
.Fa "aslclient asl"
.Fa "int descriptor"
.Fc
.Ft void
.Fo asl_close
.Fa "aslclient asl"
.Fc
.Ft void
.Fo asl_close_auxiliary_file
.Fa "int descriptor"
.Fc
.Ft void
.Fo asl_create_auxiliary_file
.Fa "aslmsg msg"
.Fa "const char *title"
.Fa "const char *uti"
.Fa "int *out_descriptor"
.Fc
.Ft void
.Fo asl_free
.Fa "aslmsg msg"
.Fc
.Ft const char *
.Fo asl_get
.Fa "aslmsg msg"
.Fa "const char *key"
.Fc
.Ft const char *
.Fo asl_key
.Fa "aslmsg msg"
.Fa "uint32_t n"
.Fc
.Ft int
.Fo asl_log
.Fa "aslclient asl"
.Fa "aslmsg msg"
.Fa "int level"
.Fa "const char *format"
.Fa "..."
.Fc
.Ft void
.Fo asl_log_auxiliary_location
.Fa "aslmsg msg"
.Fa "const char *title"
.Fa "const char *uti"
.Fa "const char *url"
.Fc
.Ft int
.Fo asl_log_descriptor
.Fa "aslclient asl"
.Fa "aslmsg msg"
.Fa "int level"
.Fa "int descriptor"
.Fa "uint32_t fd_type"
.Fc
.Ft aslmsg
.Fo asl_new
.Fa "uint32_t type"
.Fc
.Ft aslclient
.Fo asl_open
.Fa "const char *ident"
.Fa "const char *facility"
.Fa "uint32_t opts"
.Fc
.Ft aslclient
.Fo asl_open_from_file
.Fa "int descriptor"
.Fa "const char *ident"
.Fa "const char *facility"
.Fc
.Ft int
.Fo asl_remove_log_file
.Fa "aslclient asl"
.Fa "int descriptor"
.Fc
.Ft aslresponse
.Fo asl_search
.Fa "aslclient asl"
.Fa "aslmsg msg"
.Fc
.Ft int
.Fo asl_send
.Fa "aslclient asl"
.Fa "aslmsg msg"
.Fc
.Ft int
.Fo asl_set
.Fa "aslmsg msg"
.Fa "const char *key"
.Fa "const char *value"
.Fc
.Ft int
.Fo asl_set_filter
.Fa "aslclient asl"
.Fa "int f"
.Fc
.Ft int
.Fo asl_set_query
.Fa "aslmsg msg"
.Fa "const char *key"
.Fa "const char *value"
.Fa "uint32_t op"
.Fc
.Ft int
.Fo asl_unset
.Fa "aslmsg msg"
.Fa "const char *key"
.Fc
.Ft int
.Fo asl_vlog
.Fa "aslclient asl"
.Fa "aslmsg msg"
.Fa "int level"
.Fa "const char *format"
.Fa "va_list ap"
.Fc
.Ft void
.Fo aslresponse_free
.Fa "aslresponse r"
.Fc
.Ft aslmsg
.Fo aslresponse_next
.Fa "aslresponse r"
.Fc
.Sh DESCRIPTION
These routines provide an interface to the Apple System Log facility.
They are intended to be a replacement for the 
.Xr 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 
.Nm 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.
.Pp
An introduction to the concepts underlying this interface follows the interface summary below.
.Ss INTERFACE SUMMARY
.Fo asl_open
.Fa ident
.Fa facility
.Fa opts
.Fc
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
.Ar ident
as the value associated with the ASL_KEY_SENDER key, and the value
.Ar facility
associated with the ASL_KEY_FACILITY key.
Several options are available, as described in the
.Sx CLIENT HANDLES
section.
.Pp
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 contend for a single internal lock when
sending log messages using a NULL handle.
.Pp
.Fo asl_close
.Fa asl
.Fc
closes the client handle
.Ar asl
and releases its associated resources.
.Pp
.Fo asl_add_log_file
.Fa asl
.Fa descriptor  
.Fc
adds the file descriptor
.Ar descriptor
to the a set of file descriptors associated with the client handle
.Ar asl .
Each log message sent by that client handle is also written to these file descriptors.
Returns 0 on success, non-zero on failure.
.Pp
.Fo asl_remove_log_file
.Fa asl
.Fa descriptor  
.Fc
removes a file descriptor from the set of file descriptors associated with a client handle.
Returns 0 on success, non-zero on failure.
.Pp
.Fo asl_new
.Fa type
.Fc
allocates and returns an aslmsg structure, or NULL in the case of a failure in the library.
The
.Ar type
argument must be ASL_TYPE_MSG or ASL_TYPE_QUERY.
.Pp
.Fo asl_free
.Fa msg
.Fc
frees an aslmsg and releases resources associated with the structure.
.Pp
.Fo asl_set
.Fa msg
.Fa key
.Fa value
.Fc
creates a new key and value in an aslmsg structure, or replaces the value of an existing key.
Returns 0 on success, non-zero on failure.
.Pp
.Fo asl_set_query
.Fa msg
.Fa key
.Fa op
.Fa value
.Fc
is used to construct searches.
It is similar to
.Fn asl_set ,
except that it takes an additional
.Ar 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
.Sx SEARCHING
section for more information.
Returns 0 on success, non-zero on failure.
.Pp
.Fo asl_unset
.Fa msg
.Fa key
.Fc
removes a key and its associated value from an aslmsg structure.
Returns 0 on success, non-zero on failure.
.Pp
.Fo asl_key
.Fa msg
.Fa n
.Fc
returns the nth key in an aslmsg (beginning at zero),
allowing an application to iterate through the keys.
Returns NULL if
.Ar n
indexes beyond the number of keys in
.Ar msg .
.Pp
.Fo asl_get
.Fa msg
.Fa key
.Fc
returns the value associated with
.Ar key
in the aslmsg
.Ar msg .
Returns NULL if
.Ar msg
does not contain
. Ar key .
.Pp
.Fo asl_set_filter
.Fa asl
.Fa f
.Fc
sets a filter for messages being sent to the server.
The filter is a bitmask representing priority levels.
Only messages having a priority level with a corresponding bit set in the filter mask are sent to the
.Nm syslogd
server.
The filter does not control writes to additional files associated with the client handle using
.Fn asl_add_log_file .
Returns the previous filter value.
.Pp
.Fo asl_log
.Fa asl
.Fa msg
.Fa level
.Fa format
.Fa args...
.Fc
sends a log to the server (subject to filtering, see 
.Fn asl_set_filter
above) and to any file descriptors associated with the client handle
.Ar asl .
The 
.Ar msg
argument may contain any keys and values, which will be formatted as part of the log message.
The value for ASL_KEY_LEVEL is supplied by the
.Ar level
argument. 
The value for ASL_KEY_MESSAGE is computed from 
.Ar format
and the associated arguments
.Ar args... .
Normal 
.Fn printf
style argument processing is applied to the format and the arguments.
The format may also contain
.Dq %m
which will be substituted with the string value corresponding to the current
.Em errno .
.Pp
The ASL_PREFILTER_LOG(asl, msg, level, format, ...) macro may be used in
place of
.Fn asl_log .
The macro avoids processing the variable argument list in those cases where
the message would be filtered out due to filter settings, would not be
written to a log file associated with the aslclient, or would not be
written to stderr.
The macro may provide a performance benefit for some applications.
Details on filter setting, additional log files, and aslclient options
are described below in this manual.
.Pp
.Fo asl_vlog
.Fa asl
.Fa msg
.Fa level
.Fa format
.Fa ap
.Fc
is similar to
.Fn asl_log
except that it takes a va_list argument.
.Pp
.Fo asl_send
.Fa asl
.Fa msg
.Fc
is similar to
.Fn asl_log ,
exceopt the value for ASL_KEY_MESSAGE is taken from
.Ar msg
rather than being constructed using a
.Fn printf
style syntax.
.Pp
.Fo asl_log_descriptor
.Fa asl
.Fa msg
.Fa level
.Fa descriptor
.Fa fd_type
.Fc
provides functionality to use file descriptors to send logging data to ASL.
.Ar asl
is retained by ASL and must still be closed by the caller by calling
.Fn asl_close
if the caller loses reference to it.
.Ar msg
is copied by ASL and similarly must still be freed by the caller by calling
.Fn asl_free
if the caller loses reference to it.  Any changes made to it after calling
.Fn asl_log_descriptor()
are not applicable to the message used.
.Ar descriptor is treated differentlty based on the value of
.Ar fd_type .
.Pp
If
.Ar fd_type
is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read access.  ASL
uses
.Xr dispatch 2
to read from the descriptor as data becomes available.  These data are line
buffered and passed to
.Fn asl_log .
When EOF is read, ASL will
.Xr close 2
.Ar descriptor ..
.Pp
If
.Ar fd_type
is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new writable
descriptor is created with the same fileno.  Any data written to this new
descriptor are line buffered and passed to
.Fn asl_log .
When EOF is sent, no further data are read.  The caller is responsible for
closing the new descriptor.  One common use for this API is to redirect writes
to stdout or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as
.Ar descriptor .
.Pp
.Fo asl_search
.Fa asl
.Fa msg
.Fc
searches for messages that match the keys and values in
.Ar msg ,
subject to matching operations associated with those keys and values.
The 
.Ar msg
argument should be constructed using
.Fn asl_set_query .
See the
.Sx 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.
.Pp
.Fo aslresponse_next
.Fa r
.Fc
iterates over an aslresponse structure returned by
.Fn asl_search .
Each call returns the next aslmsg in the response.
Returns NULL when there are no further messages.
.Pp
.Fo aslresponse_free
.Fa r
.Fc
frees the aslresponse structure
.Ar r
and all of its associated resources.
.Pp
.Fo asl_create_auxiliary_file
.Fa msg
.Fa title
.Fa uti
.Fa out_descriptor
.Fc
Creates an auxiliary file that may be used by the client to save arbitrary data.
When the file is closed using
.Fo asl_close_auxiliary_file
.Fc ,
.Nm syslogd
will log the specified
.Fa msg 
along with the
.Fa title
and the Uniform Type Identifier provided by
.Fa uti .
If a NULL value is supplied for 
.Fa uti
the type
.Dq public.data
will be used.
The
.Nm Console
application will display the message with a link to the file.
.Pp
Auxiliary files are saved in the ASL data store.
They are automatically deleted at the same time that the log message expires.
Messages expire in 7 days by default.
A value set for the ASLExpireTime key will override the default.
Read access for the auxiliary file will be the same as read access for
.Fa msg .
By default, messages (and auxiliary files) are world-readable.
Access may be limited by setting values for the ReadUID and ReadGID keys.
.Pp
.Fo asl_close_auxiliary_file
.Fa descriptor
.Fc
closes the file descriptor
.Ar descriptor 
previously returned by a call to
.Fn asl_create_auxiliary_file .
.Pp
.Fo asl_log_auxiliary_location
.Fa msg
.Fa title
.Fa uti
.Fa url
.Fc
will log the specified
.Fa msg 
along with the
.Fa title ,
the Uniform Type Identifier provided by
.Fa uti ,
and the Uniform Resource Locator provided by
.Fa url .
The
.Nm Console
application will display the message with a link to the file.
This allows a client to save data in an auxiliary file, but unlike
.Fo asl_create_auxiliary_file
.Fc ,
the life-cycle of this file must be managed by some external system.
The file will not be removed when the corresponding log message expired from the ASL data store.
.Pp
.Fo asl_open_from_file
.Fa descriptor
.Fa facility
.Fa opts
.Fc
creates a client handle for an open file descriptor
.Fa descriptor .
This routine may be used in conjunction with
.Fo asl_create_auxiliary_file
.Fc 
or
.Fo asl_log_auxiliary_location
.Fc 
to save ASL format log messages in an auxiliary file.
The UTI type
.Dq com.apple.asl-file
should be used for ASL format auxiliary files.
.Pp
Files with this format may be read from the command line using
.Nm syslog Fl f Ar file ,
or from the 
.Nm Console 
utility.
.Pp
The file must be open for read and write access.
The file will be truncated and its existing contents will be lost.
.Fo asl_close
.Fc
must be called to close the client handle when logging to this file is complete. 
The file should be closed using
.Fo asl_close_auxiliary_file
.Fc
if it was returned by
.Fo asl_create_auxiliary_file
.Fc ,
or
.Fo close
.Fc
otherwise.
.Pp
The client handle may be used safely by multiple threads.
The threads will contend for a single internal lock when saving log messages to a file.
.Pp
Note that messages with ReadUID or ReadGID values will simply be saved to the file,
and will not effect read access to either the message or the file itself.
Similarly, messages with ASLExpireTime values will be saved, but will not effect the 
life-cycle of either the individual messages or the file.
.Ss 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 NUL-character terminated C language strings.
UTF-8 encoding may be used for non-ASCII characters.
.Pp
Message structures are generally used to send log messages,
and are created thusly:
.Pp
    aslmsg m = asl_new(ASL_TYPE_MSG);
.Pp
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
.Sx SEARCHING
section.
For the remainder of this section,
the messages described will be of the ASL_TYPE_MSG variety.
.Pp
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:
.Pp
    #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"
.Pp
Many of these correspond to equivalent parts of messages described in the 
.Xr syslog 3
API.
Values associated 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.
.Pp
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.
.Pp
The 
.Xr asl 3
API does not require a process to choose a facility name.
The 
.Nm syslogd
server will use a default value of 
.Dq user
if a facility is not set.
However, a client may set a facility name as an argument in the
.Nm asl_open
call, or by setting a specific value for the ASL_KEY_FACILITY in a message:
.Pp
    asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");
.Pp
An application may choose any facility name at will.
Different facility names may be attached to different messages, perhaps to distinguish different subsystems in log messages.
Developers are encouraged to adopt a
.Dq Reverse ICANN
naming convention to avoid conflicting facility names.
.Pp
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
.Nm asl_set
routine, or implicitly set at the time the message is sent using the
.Nm asl_log
or
.Nm asl_vlog
routines.
These two routines also have an integer-level parameter
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.
.Pp
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 
.Dq Hello World
program requires only:
.Pp
    #include <asl.h>
    ...
    asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!");
.Pp
Both
.Nm asl_log
and
.Nm asl_vlog
will provide the appropriate default values
when passed a NULL aslmsg argument.
.Pp
.Pp
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
.Em should
open a separate client handle using
.Nm asl_open .
The client handle may then be closed when it is no longer required using
.Nm asl_close .
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.
.Pp
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 
.Dq template
message of sorts:
.Pp
    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");
.Pp
The message structure will carry the values set for the 
.Dq Facility
and
.Dq Clearance
keys so that they are used in each call to
.Nm asl_log ,
while the log level and the message text
are taken from the calling parameters.
.Pp
The
.Ar format
argument to
.Nm asl_log
and
.Nm asl_vlog
is identical to
.Xr printf 3 ,
and may include
.Ql %m ,
which is replaced by the current error message
(as denoted by the global variable 
.Va errno ;
see
.Xr strerror 3 . )
.Pp
Key/value pairs may be removed from a message structure with
.Nm asl_unset .
A message may be freed using
.Nm asl_free .
.Pp
The 
.Nm asl_send
routine is used by 
.Nm asl_log
and
.Nm 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
.Nm asl_set .
.Ss SECURITY
Messages that are sent to the 
.Nm syslogd
server may be saved in a message store.
The store may be searched using
.Nm 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.
.Pp
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
.Nm syslog
API, although developers are encouraged to adopt facility names that make sense for their application.
A
.Dq 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
.Nm syslogd
server.
.Ss 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.
.Pp
If multiple threads must do logging,
or if client options are desired,
then the application should call
.Nm asl_open
to create a client handle for each thread.
As a convenience,
the
.Nm 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.
.Pp
Several options are available when creating a client handle.
They are:
.Pp
.Bl -tag -width "ASL_OPT_NO_REMOTE" -compact
.It ASL_OPT_STDERR
adds stderr as an output file descriptor
.It ASL_OPT_NO_DELAY
connects to the server immediately
.It ASL_OPT_NO_REMOTE
disables remote-control filter adjustment
.El
.Pp
ASL_OPT_NO_DELAY makes the client library connect to the
.Nm syslogd
server at the time that
.Nm asl_open
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 
.Nm asl_log ,
.Nm asl_vlog ,
or 
.Nm asl_send .
.Pp
See the FILTERING section below, and the
.Xr syslog 1
for additional details on filter controls.
.Pp
A client handle is closed and it's resources released using 
.Nm asl_close .
Note that if additional file descriptors were added to the handle,
either using the ASL_OPT_STDERR option
or afterwards with the
.Nm asl_add_log_file
routine, those file descriptors are not closed by 
.Nm asl_close .
.Ss LOGGING TO ADDITIONAL FILES
If a client handle is opened with the ASL_OPT_STDERR option to
.Nm asl_open ,
a copy of each log message will be sent to stderr. 
Additional output streams may be include using
.Nm asl_add_log_file .
.Pp
Messages sent to stderr or other files are printed in the "standard" message format
also used as a default format by the
.Xr syslog 1
command line utility.
Non-ASCII characters in a message are encoded using the
.Dq safe
encoding style used by
.Xr syslog 1
with the 
.Fl E Ar 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.
.Pp
File descriptors may be removed from the list of outputs associated
with a client handle with
.Nm asl_remove_log_file .
This routine simply removes the file descriptor from the output list.
The file is not closed as a result.
.Pp
The ASL_OPT_STDERR option may not be unset
after a client handle has been opened.
.Ss SEARCHING
The 
.Nm syslogd
server archives received messages in a data store
that may be searched using the
.Nm asl_search ,
.Nm aslresponse_next ,
and
.Nm aslresponse_free
routines.
A query message is created using:
.Pp
    aslmsg q = asl_new(ASL_TYPE_QUERY);
.Pp
Search settings are made in the query using 
.Nm asl_set_query .
A search is performed on the data store with
.Nm asl_search .
It returns an
.Ft aslresponse 
structure.
The caller may then call 
.Nm aslresponse_next
to iterate through matching messages.
The
.Ft aslresponse 
structure may be freed with
.Nm aslresponse_free .
.Pp
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
.Dq MyApp .
.Pp
    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);
.Pp
More complex searches may be performed using other query operations.
.Pp
.Bl -tag -width "ASL_QUERY_OP_GREATER_EQUAL" -compact
.It ASL_QUERY_OP_EQUAL
value equality
.It ASL_QUERY_OP_GREATER
value greater than
.It ASL_QUERY_OP_GREATER_EQUAL
value greater than or equal to
.It ASL_QUERY_OP_LESS
value less than
.It ASL_QUERY_OP_LESS_EQUAL
value less than or equal to
.It ASL_QUERY_OP_NOT_EQUAL
value not equal
.It ASL_QUERY_OP_REGEX
regular expression search
.It ASL_QUERY_OP_TRUE
always true - use to test for the existence of a key
.El
.Pp
Regular expression search uses 
.Xr regex 3
library.
Patterns are compiled using the REG_EXTENDED and REG_NOSUB options.
.Pp
Modifiers that change the behavior of these operations
may also be specified by ORing the modifier value with the operation.
The modifiers are:
.Pp
.Bl -tag -width "ASL_QUERY_OP_SUBSTRING" -compact
.It ASL_QUERY_OP_CASEFOLD
string comparisons are case-folded
.It ASL_QUERY_OP_PREFIX
match a leading substring
.It ASL_QUERY_OP_SUFFIX
match a trailing substring
.It ASL_QUERY_OP_SUBSTRING
match any substring
.It ASL_QUERY_OP_NUMERIC
values are converted to integer using 
.Nm atoi
.El
.Pp
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.
.Pp
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
.Dq MyApp 
with a priority level less than or equal to 
.Dq 3 :
.Pp
    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);
.Pp
After calling 
.Nm asl_search
to get an
.Ft aslresponse
structure, use
.Nm aslresponse_next
to iterate through all matching messages.
To iterate through the keys and values in a message, use
.Nm asl_key
to iterate through the keys, then call
.Nm asl_get
to get the value associated with each key.
.Pp
    aslmsg q, m;
    int i;
    const char *key, *val;
.Pp
    ...
    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);
.Pp
.Ss FILTERING AND REMOTE CONTROL
Clients may set a filter mask value with
.Nm asl_set_filter .
The mask specifies which messages should be sent to the
.Nm 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 unnecessary.
.Pp
.Nm asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the routine was called.
.Pp
As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(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 ASL_LEVEL_EMERG to a given input level.
.Pp
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
.Mn syslogd
server.
.Pp
Three different filters exist for each application.
The first is the filter mask set using
.Nm asl_set_filter
as described above.
The Apple System Log facility also manages a 
.Dq master
filter mask.
The master filter mask usually has a value
that indicates to the library that it is
.Dq off , 
and thus it has no effect.
However, the mask filter mask may be enabled
by giving it a value using the
.Nm syslog
command, using the 
.Fl 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.
.Pp
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 
.Dq off ,
having no effect on a client.
If a per-client filter mask is set using the
.Nm syslog
command, using the 
.Fl c Ar 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.
.Pp
The ASL_OPT_NO_REMOTE option to
.Nm 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 filter mask
for a root (UID 0) process.
.Pp
The per-process remote control filter value is kept as a state value
associated with a key managed by
.Nm notifyd .
The key is protected by an access control mechanism that only permits the
filter value to be accessed and modified by the same effective UID as the
ASL client at the time that the first ASL connection was created.
Remote filter control using 
.Nm syslog Fl c 
will fail for processes that change effective UID after starting an ASL connection.
Those processes should close all ASL client handles and then re-open ASL connections
if remote filter control support is desired.
.Sh HISTORY
These functions first appeared in
Mac OS X 10.4.
.Sh SEE ALSO
.Xr syslog 1 ,
.Xr strvis 3 ,
.Xr syslogd 8