+++ /dev/null
-.\" 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
projects / apple / libc.git / blobdiff