manpagez: man pages & more
man aslresponse_free(3)
Home | html | info | man
asl(3)                   BSD Library Functions Manual                   asl(3)


NAME

     asl_add_log_file, asl_add_outout_file, asl_close,
     asl_close_auxiliary_file, asl_create_auxiliary_file, asl_free, asl_get,
     asl_key, asl_log, asl_log_auxiliary_location, asl_log_descriptor,
     asl_new, asl_open, asl_open_from_file, asl_remove_log_file, asl_search,
     asl_send, asl_set, asl_set_filter, asl_set_output_file_filter,
     asl_set_query, asl_unset, asl_vlog, aslresponse_free, aslresponse_next --
     system log message sending and searching functions


SYNOPSIS

     #include <asl.h>

     int
     asl_add_log_file(aslclient asl, int descriptor);

     int
     asl_add_output_file(aslclient asl, int descriptor, const char *msg_fmt,
         const char *time_fmt, int filter, int text_encoding);

     void
     asl_close(aslclient asl);

     void
     asl_close_auxiliary_file(int descriptor);

     void
     asl_create_auxiliary_file(aslmsg msg, const char *title, const char *uti,
         int *out_descriptor);

     void
     asl_free(aslmsg msg);

     const char *
     asl_get(aslmsg msg, const char *key);

     const char *
     asl_key(aslmsg msg, uint32_t n);

     int
     asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...);

     void
     asl_log_auxiliary_location(aslmsg msg, const char *title,
         const char *uti, const char *url);

     int
     asl_log_descriptor(aslclient asl, aslmsg msg, int level, int descriptor,
         uint32_t fd_type);

     aslmsg
     asl_new(uint32_t type);

     aslclient
     asl_open(const char *ident, const char *facility, uint32_t opts);

     aslclient
     asl_open_from_file(int descriptor, const char *ident,
         const char *facility);

     int
     asl_remove_log_file(aslclient asl, int descriptor);

     aslresponse
     asl_search(aslclient asl, aslmsg msg);

     int
     asl_send(aslclient asl, aslmsg msg);

     int
     asl_set(aslmsg msg, const char *key, const char *value);

     int
     asl_set_filter(aslclient asl, int filter);

     int
     asl_set_output_file_filter(aslclient asl, int descriptor, int filter);

     int
     asl_set_query(aslmsg msg, const char *key, const char *value,
         uint32_t op);

     int
     asl_unset(aslmsg msg, const char *key);

     int
     asl_vlog(aslclient asl, aslmsg msg, int level, const char *format,
         va_list ap);

     void
     aslresponse_free(aslresponse r);

     aslmsg
     aslresponse_next(aslresponse r);


DESCRIPTION

     These routines provide an interface to the Apple System Log facility.
     They are intended to be a replacement for the syslog(3) API, which will
     continue to be supported for backwards compatibility.  The new API allows
     client applications to create flexible, structured messages and send them
     to the syslogd server, where they may undergo additional processing.
     Messages received by the server are saved in a data store (subject to
     input filtering constraints).  This API permits clients to create queries
     and search the message data store for matching messages.

     An introduction to the concepts underlying this interface follows the
     interface summary below.

   INTERFACE SUMMARY
     asl_open(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 associated with the
     ASL_KEY_SENDER key, and the value facility associated with the
     ASL_KEY_FACILITY key.  Several options are available, as described in the
     CLIENT HANDLES section.

     Each client handle holds state information that is used when a message is
     logged using that handle.  This information includes the ident and
     facility strings and the options from the opts parameter.  Client handles
     also contain various filter, file descriptor, and control data.

     The state information in a client handle is not protected by any locking
     or thread synchronization mechanism.  It is not safe for two or more
     threads to use a single client handle simultaneously.  Multi-threaded
     applications should generally create one client handle for each thread
     that logs messages.  A client handle may only be safely shared amongst
     multiple threads if the application uses locks or some synchronization
     strategy to ensure single-threaded access.

     As a special case, the ASL library allows the use of NULL in place of a
     client handle.  In this case, the library uses an internal structure
     which contains its own lock.  Multiple threads may safely use NULL,
     although there may be contention for the lock.

     Applications that use libdispatch may use NULL in place of a client han-
     dle, although this may cause undesirable synchronization behavior and
     degraded performance because of lock contention.  A better design is
     often to use one or more serial dispatch queues specifically for logging.
     Each such serial queue should use a separate client handle.

     asl_close(asl) closes the client handle asl and releases its associated
     resources.

     asl_add_output_file(asl, descriptor, msg_fmt, time_fmt, filter,
     text_encoding) adds the file descriptor descriptor 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 (depend-
     ing on the setting of the filter argument).  The message format is speci-
     fied by the msg_fmt argument.  The format for timestamps is specified by
     the time_fmt argument, although custom format strings may specify more
     advanced formats for timestamps.  Details on custom format strings are
     below.

     Each output file has an associated filter value.  The filter determines
     which messages are formatted and written to the file based on the message
     priority level.

     Special handling for certain characters is specified by the text_encoding
     argument.  The supported values and their effect are described below.

     The msg_format argument is a character string that tells the library how
     to format each message written to the output file.  There are several
     pre-defined message formats, described below.  Custom formats are also
     supported, giving complete control over which ASL message keys should be
     written and the overall format of each output line.  The pre-defined for-
     mats are identified by constants in the asl.h header file.

     ASL_MSG_FMT_RAW  The contents of the ASL message dictionaries are format-
                      ted as a list, with each key-value pair formatted as
                      ``[Key Value]''.

     ASL_MSG_FMT_STD  Messages are formatted using the standard ASL message
                      format of the form

                            Time Host Sender[PID] <Level>: Message

                      Time formats are described below.

     ASL_MSG_FMT_BSD  The legacy format used for plain-text log files.  Simi-
                      lar to the ASL_MSG_FMT_STD format, but the message pri-
                      ority level is excluded.

     ASL_MSG_FMT_MSG  The output line contains only the value of the Message
                      key in each ASL message dictionary.

     ASL_MSG_FMT_XML  Produces multiple lines of output for each ASL message.
                      The message is formatted as an XML dictionary:

                            <dict>
                                 <key>ASLMessageKey1</key>
                                 <string>Key 1 Value</string>
                                 <key>ASLMessageKey2</key>
                                 <string>Key 2 Value</string>
                                      ...
                            </dict>

     A NULL value for msg_fmt causes the library to use the ``std'' format.

     Custom format strings may contain a mix of characters that are directly
     copied to the output line and variables, which are a dollar sign `$' fol-
     lowed by specific ASL message dictionary keys, whose values will be
     interpolated into the output.  For example, the format string:

           This message from $Sender PID=$PID at $Time *** $Message

     would result in lines in the output file like, e.g.:

           This message from login PID=982 at Jul 27 08:41:27 ***
           USER_PROCESS: 330 ttys000
           This message from Mail PID=987 at Jul 27 08:42:16 *** Using V2
           Layout

     Normally, a space character terminates a variable name.  However, the
     name may be wrapped in parentheses if a space character is not desired in
     the output.  For example:

           $(Sender)[$(PID)]: $Message

     A third form for specifying variables may be used for the ASL ``Level''
     and ``Time'' message keys.  Note that a ``Time'' specification using one
     of the forms below will override the time_fmt argument to the function.

     The following forms are recognized:

     $((Level)(str))          Formats a Level value as a string, for example
                              ``Error'', ``Alert'', ``Warning'', and so on.
                              Note that $(Level) or $Level formats the value
                              as an integer 0 through 7.

     $((Time)(sec))           Formats a Time value as the number of seconds
                              since the Epoch.

     $((Time)(raw))           Alias for $((Time)(sec)).

     $((Time)(local))         Formats a Time value as a string of the form
                              ``Mmm dd hh:mm:ss'', where Mmm is the abbrevia-
                              tion for the month, dd is the date (1 - 31) and
                              hh:mm:ss is the time.  The local timezone is
                              used.

     $((Time)(lcl))           Alias for $((Time)(local)).

     $((Time)(utc))           Formats a Time value as a string of the form
                              ``yyyy-mm-dd hh:mm:ssZ'', using Coordinated Uni-
                              versal Time, or the ``Zulu'' time zone.

     $((Time)(zulu))          Alias for $((Time)(utc)).

     $((Time)(X))             Where X may be any letter in the range A - Z or
                              a - z.  Formats the Time using the format
                              ``yyyy-mm-dd hh:mm:ssX'', using the specified
                              nautical timezone.  Z is the same as UTC/Zulu
                              time.  Timezones A - M (except J) decrease by
                              one hour to the east of the Zulu time zone.
                              Timezones N - Y increase by one hour to the west
                              of Z.  M and Y have the same clock time, but
                              differ by one day.  J is used to indicate the
                              local timezone.  When printing using
                              $((Time)(J)), the output format is ``yyyy-mm-dd
                              hh:mm:ss'', without a trailing timezone letter.

     $((Time)(JZ))            Specifies the local timezone.  The timezone off-
                              set from UTC follows the date and time.  The
                              time is formatted as ``yyyy-mm-dd
                              hh:mm:ss[+|-]HH[:MM]''.  Minutes in the timezone
                              offset are only printed if they are non-zero.

     $((Time)(ISO8601))       Specifies the local timezone, formatted as spec-
                              ified by ISO 8601.  The timezone offset from UTC
                              follows the date and time.  The time is format-
                              ted as ``yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]''.
                              Minutes in the timezone offset are only printed
                              if they are non-zero.  Note that this differs
                              from ``JZ'' format only in that a ``T'' charac-
                              ter separates the date and time.

     $((Time)([+|-]HH[:MM]))  Specifies an offset (+ or -) of the indicated
                              number of hours (HH) and optionally minutes (MM)
                              to UTC.  The value is formatted as a string of
                              the form ``yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]''.
                              Minutes in the timezone offset are only printed
                              if they are non-zero.

     Unless a custom message format uses one of the specialized forms for
     ``Time'' described above, then any timestamps in an output message will
     be formatted according the the time_fmt argument.  The known formats are
     identified by constants in the asl.h header file.

     ASL_TIME_FMT_SEC  Formats timestamps as the number of seconds since the
                       Epoch.

     ASL_TIME_FMT_UTC  Formats a Time value as a string of the form
                       ``yyyy-mm-dd hh:mm:ssZ'', using Coordinated Universal
                       Time, or the ``Zulu'' time zone.

     ASL_TIME_FMT_LCL  Formats a Time value as a string of the form ``Mmm dd
                       hh:mm:ss'', where Mmm is the abbreviation for the
                       month, dd is the date (1 - 31) and hh:mm:ss is the
                       time.  The local timezone is used.

     A value of NULL for the time_fmt argument will cause the default format
     ASL_TIME_FMT_LCL to be used.

     The encoding parameter specifies how certain characters are to be treated
     when preparing a message for output.  The known encodings are:

     ASL_ENCODE_NONE  No special character encode is done.

     ASL_ENCODE_ASL   Newlines and tabs are also encoded as "\n" and "\t"
                      respectively.  In ``ASL_MSG_FMT_RAW'' format, space
                      characters embedded in log message keys are encoded as
                      "\s" and embedded brackets are escaped to print as "\["
                      and "\]".

     ASL_ENCODE_SAFE  Encodes backspace characters as ^H.  Carriage returns
                      are mapped to newlines.  A tab character is appended
                      after newlines so that message text is indented.

     ASL_ENCODE_XML   This encoding should be used when formatting messages
                      using ASL_MSG_FMT_XML.  XML format output requires that
                      keys are valid UTF8 strings.  Keys which are not valid
                      UTF8 are ignored, and the associated value is not
                      printed.

                      Values that contain legal UTF8 are printed as strings.
                      Ampersand, less than, greater than, quotation mark, and
                      apostrophe characters are encoded according to XML con-
                      ventions.  Embedded control characters are encoded as
                      ``&#xNN;'' where NN is the character's hexadecimal
                      value.

                      Values that do not contain legal UTF8 are encoded in
                      base-64 and printed as data objects.

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

     asl_add_log_file(asl, descriptor) Is equivalent to

           asl_add_output_file(asl, descriptor, ASL_MSG_FMT_STD,
           ASL_TIME_FMT_LCL, ASL_FILTER_MASK_UPTO(ASL_LEVEL_DEBUG),
           ASL_ENCODE_SAFE);

     Returns 0 on success, non-zero on failure.

     asl_set_output_file_filter(asl, descriptor, filter) replaces the current
     filter value associated with a file descriptor that has been added to a
     client handle.  Returns the previous filter value.

     asl_remove_log_file(asl, descriptor) removes a file descriptor from the
     set of file descriptors associated with a client handle.  Returns 0 on
     success, non-zero on failure.

     asl_new(type) allocates and returns an aslmsg structure, or NULL in the
     case of a failure in the library.  The type argument must be ASL_TYPE_MSG
     or ASL_TYPE_QUERY.

     asl_free(msg) frees an aslmsg and releases resources associated with the
     structure.

     asl_set(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.

     asl_set_query(msg, key, op, value) is used to construct searches.  It is
     similar to asl_set(), 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.

     asl_unset(msg, key) removes a key and its associated value from an aslmsg
     structure.  Returns 0 on success, non-zero on failure.

     asl_key(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.

     asl_get(msg, key) returns the value associated with key in the aslmsg
     msg.  Returns NULL if msg does not contain key.

     asl_set_filter(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 syslogd server.  The filter does not control writes
     to additional files associated with the client handle using
     asl_add_log_file().  Returns the previous filter value.

     asl_log(asl, msg, level, format, args...) sends a log to the server (sub-
     ject to filtering, see asl_set_filter() 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 ASL_KEY_LEVEL is supplied by the level argument.  The value
     for ASL_KEY_MESSAGE is computed from format and the associated arguments
     args....  Normal printf() 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.

     The ASL_PREFILTER_LOG(asl, msg, level, format, ...) macro may be used in
     place of 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.

     asl_vlog(asl, msg, level, format, ap) is similar to asl_log() except that
     it takes a va_list argument.

     asl_send(asl, msg) is similar to asl_log(), except the value for
     ASL_KEY_MESSAGE is taken from msg rather than being constructed using a
     printf() style syntax.

     asl_log_descriptor(asl, msg, level, descriptor, fd_type) provides func-
     tionality to use file descriptors to send logging data to ASL.  asl is
     retained by ASL and must still be closed by the caller by calling
     asl_close() if the caller loses reference to it.  msg is copied by ASL
     and similarly must still be freed by the caller by calling asl_free() if
     the caller loses reference to it.  Any changes made to it after calling
     asl_log_descriptor()() are not applicable to the message used.
     descriptor is treated differently based on the value of fd_type.

     If fd_type is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for
     read access.  ASL uses dispatch(2) to read from the descriptor as data
     becomes available.  These data are line buffered and passed to asl_log().
     When EOF is read, ASL will close(2) descriptor ..

     If fd_type is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a
     new writable descriptor is created with the same fileno.  Any data writ-
     ten to this new descriptor are line buffered and passed to 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 redi-
     rect writes to stdout or stderr to ASL by passing STDOUT_FILENO or
     STDERR_FILENO as descriptor.

     asl_search(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 asl_set_query().
     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.

     aslresponse_next(r) iterates over an aslresponse structure returned by
     asl_search().  Each call returns the next aslmsg in the response.
     Returns NULL when there are no further messages.

     aslresponse_free(r) frees the aslresponse structure r and all of its
     associated resources.

     asl_create_auxiliary_file(msg, title, uti, out_descriptor) Creates an
     auxiliary file that may be used by the client to save arbitrary data.
     When the file is closed using asl_close_auxiliary_file(), syslogd will
     log the specified msg along with the title and the Uniform Type Identi-
     fier provided by uti.  If a NULL value is supplied for uti the type
     ``public.data'' will be used.  The Console application will display the
     message with a link to the file.

     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 over-
     ride the default.  Read access for the auxiliary file will be the same as
     read access for msg.  By default, messages (and auxiliary files) are
     world-readable.  Access may be limited by setting values for the ReadUID
     and ReadGID keys.

     asl_close_auxiliary_file(descriptor) closes the file descriptor
     descriptor previously returned by a call to asl_create_auxiliary_file().

     asl_log_auxiliary_location(msg, title, uti, url) will log the specified
     msg along with the title, the Uniform Type Identifier provided by uti,
     and the Uniform Resource Locator provided by url.  The Console applica-
     tion will display the message with a link to the file.  This allows a
     client to save data in an auxiliary file, but unlike
     asl_create_auxiliary_file(), the life-cycle of this file must be managed
     by some external system.  The file will not be removed when the corre-
     sponding log message expired from the ASL data store.

     asl_open_from_file(descriptor, facility, opts) creates a client handle
     for an open file descriptor descriptor.  This routine may be used in con-
     junction with asl_create_auxiliary_file() or asl_log_auxiliary_location()
     to save ASL format log messages in an auxiliary file.  The UTI type
     ``com.apple.asl-file'' should be used for ASL format auxiliary files.

     Files with this format may be read from the command line using syslog -f
     file, or from the Console utility.

     The file must be open for read and write access.  The file will be trun-
     cated and its existing contents will be lost.  asl_close() must be called
     to close the client handle when logging to this file is complete.  The
     file should be closed using asl_close_auxiliary_file() if it was returned
     by asl_create_auxiliary_file(), or close() otherwise.

     The client handle returned by asl_open_from_file() contains an internal
     lock, and may be used safely by multiple threads or from independent dis-
     patch queues.  Note that callers will contend for the internal lock when
     saving log messages to a file.

     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 mes-
     sages or the file.

   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 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 = asl_new(ASL_TYPE_MSG);

     Another message type, ASL_TYPE_QUERY, is used to create queries when
     searching the data store.  Query type messages and searching are
     described in detail in the SEARCHING section.  For the remainder of this
     section, the messages described will be of the ASL_TYPE_MSG variety.

     Each aslmsg contains a default set of keys and values that are associated
     with them.  These keys are listed in the asl.h header file.  They are:

         #define ASL_KEY_TIME      "Time"
         #define ASL_KEY_HOST      "Host"
         #define ASL_KEY_SENDER    "Sender"
         #define ASL_KEY_FACILITY  "Facility"
         #define ASL_KEY_PID       "PID"
         #define ASL_KEY_UID       "UID"
         #define ASL_KEY_GID       "GID"
         #define ASL_KEY_LEVEL     "Level"
         #define ASL_KEY_MSG       "Message"

     Many of these correspond to equivalent parts of messages described in the
     syslog(3) API.  Values 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.

     Note the addition of the UID and GID keys.  The values for UID and GID
     are set in library code by the message sender.  The server will attempt
     to confirm the values, but no claim is made that these values cannot be
     maliciously overridden in an attempt to deceive a log message reader as
     to the identity of the sender of a message.  The contents of log messages
     must be regarded as insecure.

     The asl(3) API does not require a process to choose a facility name.  The
     syslogd server will use a default value of ``user'' if a facility is not
     set.  However, a client may set a facility name as an argument in the
     asl_open call, or by setting a specific value for the ASL_KEY_FACILITY in
     a message:

         asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");

     An application may choose any facility name at will.  Different facility
     names may be attached to 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 ASL_KEY_MSG, which may be explicitly set at any time using the
     asl_set routine, or implicitly set at the time the message is sent using
     the asl_log or asl_vlog routines.  These two routines also have an inte-
     ger-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.

     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 <asl.h>
         ...
         asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!");

     Both asl_log and asl_vlog will provide the appropriate default values
     when passed a NULL aslmsg 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 asl_open.  The client
     handle may then be closed when it is no longer required using 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.

     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 = asl_new(ASL_TYPE_MSG);
         asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us");
         asl_set(m, "Clearance", "Top Secret");
         ...
         asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One");
         ...
         asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two");

     The message structure will carry the values set for the ``Facility'' and
     ``Clearance'' keys so that they are used in each call to asl_log, while
     the log level and the message text are taken from the calling parameters.

     The format argument to asl_log and asl_vlog is identical to printf(3),
     and may include `%m', which is replaced by the current error message (as
     denoted by the global variable errno; see strerror(3).)

     Key/value pairs may be removed from a message structure with asl_unset.
     A message may be freed using asl_free.

     The asl_send routine is used by asl_log and asl_vlog to transmit a mes-
     sage to the server.  This routine sets the value associated with
     ASL_KEY_TIME and sends the message.  It may be called directly if all of
     a message's key/value pairs have been created using asl_set.

   SECURITY
     Messages that are sent to the syslogd server may be saved in a message
     store.  The store may be searched using asl_search, as described below.
     By default, all messages are readable by any user.  However, some appli-
     cations may wish to restrict read access for some messages.  To accommo-
     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 syslog API, although developers are encouraged to adopt facility
     names that make sense for their application.  A ``Reverse ICANN'' naming
     convention (e.g. "com.apple.system.syslog") should be adopted to avoid
     conflicting names.  The ASL system 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 syslogd server.

   CLIENT HANDLES
     A client handle contains various parameters and control settings that are
     used when a message is logged.  This includes an identification string, a
     facility name, filtering controls, additional file descriptors, and other
     data.  Client handles are not thread-safe.  Applications that log from
     multiple threads should create a client handle for each thread.

     Applications that use libdispatch must also avoid using a single client
     handle from multiple dispatch queues if those queues may run concur-
     rently.  A good approach is to create one or more serial dispatch queues
     specifically for logging.  Each such queue should use its own ASL client
     handle.

     If a single handle must be accessed by multiple dispatch queues, then the
     application must use locks, semaphores, or some other mechanism to pre-
     vent concurrent access to a client handle.

     A NULL value may be used in any of the routines that require an aslclient
     argument.  In this case, the library will use an internal client handle.
     This internal handle contains its own lock, allowing multiple threads to
     safely use the NULL client handle.  Note, however, that contention for
     the lock may cause undesirable synchronization behavior or reduced per-
     formance.

     The asl_open routine may be given an ident argument, which becomes the
     default value for the ASL_KEY_SENDER key, and a facility argument, which
     becomes the value associated with the ASL_KEY_FACILITY key.  If NULL is
     passed as the value for ident, the name of the currently running program
     will be used.  If NULL is passed as the value for facility, the value
     ``user'' will be used for non UID 0 processes, and ``'' daemon will be
     used for UID 0 processes.

     Several options are available when creating a client handle.  They are:

     ASL_OPT_STDERR     adds stderr as an output file descriptor
     ASL_OPT_NO_DELAY   connects to the server immediately
     ASL_OPT_NO_REMOTE  disables remote-control filter adjustment

     ASL_OPT_NO_DELAY makes the client library connect to the syslogd server
     at the time that 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
     asl_log, asl_vlog, or asl_send.

     See the FILTERING section below, and the syslog(1) for additional details
     on filter controls.

     A client handle is closed and its resources released using asl_close.
     Note that if additional file descriptors were added to the handle, either
     using the ASL_OPT_STDERR option or afterwards with the asl_add_log_file
     routine, those file descriptors are not closed by asl_close.

   LOGGING TO ADDITIONAL FILES
     If a client handle is opened with the ASL_OPT_STDERR option to asl_open,
     a copy of each log message will be sent to stderr.  Additional output
     streams may be include using asl_add_log_file.

     Messages sent to stderr or other files are printed in the "standard" 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 -E 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 asl_remove_log_file.  This routine simply removes
     the file descriptor from the output list.  The file is not closed as a
     result.

     The ASL_OPT_STDERR option may not be unset after a client handle has been
     opened.

   SEARCHING
     The syslogd server archives received messages in a data store that may be
     searched using the asl_search, aslresponse_next, and aslresponse_free
     routines.  A query message is created using:

         aslmsg q = asl_new(ASL_TYPE_QUERY);

     Search settings are made in the query using asl_set_query.  A search is
     performed on the data store with asl_search.  It returns an aslresponse
     structure.  The caller may then call aslresponse_next to iterate through
     matching messages.  The aslresponse structure may be freed with
     aslresponse_free.

     Like other messages, ASL_TYPE_QUERY messages contain keys and values.
     They also associate an operation with each key and value.  The operation
     is used to decide if a message matches the query.  The simplest operation
     is ASL_QUERY_OP_EQUAL, which tests for equality.  For example, the fol-
     lowing code snippet searches for messages with a Sender value equal to
     ``MyApp''.

         aslmsg m;
         aslresponse r;
         q = asl_new(ASL_TYPE_QUERY);
         asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
         r = asl_search(NULL, q);

     More complex searches may be performed using other query operations.

     ASL_QUERY_OP_EQUAL          value equality
     ASL_QUERY_OP_GREATER        value greater than
     ASL_QUERY_OP_GREATER_EQUAL  value greater than or equal to
     ASL_QUERY_OP_LESS           value less than
     ASL_QUERY_OP_LESS_EQUAL     value less than or equal to
     ASL_QUERY_OP_NOT_EQUAL      value not equal
     ASL_QUERY_OP_REGEX          regular expression search
     ASL_QUERY_OP_TRUE           always true - use to test for the existence
                                 of a key

     Regular expression search uses regex(3) library.  Patterns are compiled
     using the REG_EXTENDED and REG_NOSUB options.

     Modifiers that change the behavior of these operations may also be speci-
     fied by ORing the modifier value with the operation.  The modifiers are:

     ASL_QUERY_OP_CASEFOLD   string comparisons are case-folded
     ASL_QUERY_OP_PREFIX     match a leading substring
     ASL_QUERY_OP_SUFFIX     match a trailing substring
     ASL_QUERY_OP_SUBSTRING  match any substring
     ASL_QUERY_OP_NUMERIC    values are converted to integer using atoi

     The only modifier that is checked for ASL_QUERY_OP_REGEX search is
     ASL_QUERY_OP_CASEFOLD.  This causes the regular expression to be compiled
     with the REG_ICASE option.

     If a query message contains more than one set of key/value/operation
     triples, the result will be a logical AND.  For example, to find messages
     from ``MyApp'' with a priority level less than or equal to ``3'':

         aslmsg q;
         aslresponse r;
         q = asl_new(ASL_TYPE_QUERY);
         asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
         asl_set_query(q, ASL_KEY_LEVEL, "3",
                 ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC);
         r = asl_search(NULL, q);

     After calling asl_search to get an aslresponse structure, use
     aslresponse_next to iterate through all matching messages.  To iterate
     through the keys and values in a message, use asl_key to iterate through
     the keys, then call asl_get to get the value associated with each key.

         aslmsg q, m;
         int i;
         const char *key, *val;

         ...
         r = asl_search(NULL, q);
         while (NULL != (m = aslresponse_next(r)))
         {
             for (i = 0; (NULL != (key = asl_key(m, i))); i++)
             {
                 val = asl_get(m, key);
                 ...
             }
         }
         aslresponse_free(r);

   FILTERING AND REMOTE CONTROL
     Clients may set a filter mask value with asl_set_filter.  The mask 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.

     asl_set_filter returns the previous value of the filter, i.e. the value
     of the filter before the routine was called.

     As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FIL-
     TER_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.

     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 mes-
     sages are not sent to the server.

     Three different filters exist for each application.  The first is the
     filter mask set using asl_set_filter as described above.  The Apple 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 ASL_OPT_NO_REMOTE option to asl_open causes both the master and per-
     client remote-control masks to be ignored in the library.  In that case,
     only the client's own filter mask is used to determine which messages are
     sent to the server.  This may be useful for Applications that produce log
     messages that should never be filtered, due to security considerations.
     Note that root (administrator) access is required to set or change the
     master filter mask, and that only root may change a per-client remote-
     control filter mask for a root (UID 0) process.

     The per-process remote control filter value is kept as a state value
     associated with a key managed by 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 syslog -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.


HISTORY

     These functions first appeared in Mac OS X 10.4.


SEE ALSO

     syslog(1), strvis(3), syslogd(8)

Mac OS X                        October 1, 2011                       Mac OS X

Mac OS X 10.9.1 - Generated Mon Jan 6 19:04:04 CST 2014
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.