asl (3) Страница руководства Инструментов Разработчика Mac OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Получить эти инструменты:

Установите Инструменты XCode от developer.apple.com.

Если Вы выполняете версию Инструментов XCode кроме 5,0, просматриваете документацию локально:

В XCode
В Терминале, с помощью человека (1) команда

Читать страницы руководства

Страницы руководства предназначаются как справочник для людей, уже понимающих технологию.

Чтобы изучить, как руководство организовано или узнать о синтаксисе команды, прочитайте страницу руководства для страниц справочника (5).
Для получения дополнительной информации об этой технологии, ищите другую документацию в Библиотеке Разработчика Apple.
Для получения общей информации о записи сценариев оболочки, считайте Shell, Пишущий сценарий Учебника для начинающих.

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 -system
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 associ-ated associated
ated 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 mes-sages. messages.
sages. 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 handle, 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 (depending on the setting of the
filter argument). The message format is specified 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 val-ues values
ues 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 over-all overall
all format of each output line. The pre-defined formats are identified by constants in the asl.h
header file.

ASL_MSG_FMT_RAW The contents of the ASL message dictionaries are formatted as a list, with each key-value keyvalue
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. Similar to the ASL_MSG_FMT_STD for-mat, format,
mat, but the message priority level is excluded.

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

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 `$' followed 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 parenthe-ses parentheses
ses 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 abbreviation 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 Universal 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 offset from UTC follows the date
and time. The time is formatted as ``yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]''. Min-utes Minutes
utes in the timezone offset are only printed if they are non-zero.

$((Time)(ISO8601)) Specifies the local timezone, formatted as specified by ISO 8601. The time-zone timezone
zone offset from UTC follows the date and time. The time is formatted 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'' character separates the date and time.

$((Time)([+|-]HH[:MM])) Specifies an offset (+ or -) of the indicated number of hours (HH) and option-ally optionally
ally 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 for-mats formats
mats 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 Coordi-nated Coordinated
nated 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 for-mat format
mat 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 conven-tions. conventions.
tions. Embedded control characters are encoded as ``&#xNN;'' where NN is the charac-ter's character's
ter'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 associ-ated associated
ated 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 structure, 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 suc-cess, success,
cess, non-zero on failure.

asl_key(msg, n) returns the nth key in an aslmsg (beginning at zero), allowing an application to iter-ate iterate
ate 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 messages 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 (subject to filtering, see
asl_set_filter() above) and to any file descriptors 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 fil-ter filter
ter 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 functionality 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 cre-ated created
ated with the same fileno. Any data written 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 redirect 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 aslre-sponse aslresponse
sponse 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 Identifier provided by
uti. If a NULL value is supplied for uti the type ``public.data'' will be used. The Console applica-tion application
tion 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 override 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
application 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 corresponding 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 conjunction 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 truncated and its existing contents
will be lost. asl_close() must be called to close the client handle when logging to this file is com-plete. complete.
plete. 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 dispatch 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 messages 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 language strings. UTF-8 encoding may be used for non-ASCII characters.

Message structures are generally used to send log messages, and are created 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 asso-ciated associated
ciated 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 dif-ferent different
ferent messages, perhaps to distinguish different subsystems in log messages. Developers are encour-aged encouraged
aged 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 integer-level parame-ter parameter
ter 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 simple ``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 argu-ment. argument.
ment.

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 sin-gle single
gle 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 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 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 applications may wish to restrict read access for some messages. To accommodate 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.

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 gener-ally generally
ally allows any string to be used as a facility value, with one exception. The value "com.apple.sys-tem", "com.apple.system",
tem", 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 concurrently. 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 prevent 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 mul-tiple multiple
tiple threads to safely use the NULL client handle. Note, however, that contention for the lock may
cause undesirable synchronization behavior or reduced performance.

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_FACIL-ITY ASL_KEY_FACILITY
ITY 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 pro-cesses, processes,
cesses, 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" message 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 following 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 specified 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 log-ical logical
ical 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 specifies 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 prior-ity priority
ity 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.

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_FILTER_MASK_UPTO(level) may be used to con-struct construct
struct a bit mask corresponding to a given priority level, or corresponding to a bit mask for all pri-ority priority
ority 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 messages 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 System Log facility also manages a ``master'' filter
mask. The master filter 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 remotecontrol
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 remotecontrol
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 con-nection connection
nection was created. Remote filter control using syslog -c will fail for processes that change effec-tive effective
tive 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

Сообщение о проблемах

Способ сообщить о проблеме с этой страницей руководства зависит от типа проблемы:

Ошибки содержания: Ошибки отчета в содержании этой документации со ссылками на отзыв ниже.
Отчеты об ошибках: Сообщите об ошибках в функциональности описанного инструмента или API через Генератор отчетов Ошибки.
Форматирование проблем: Отчет, форматирующий ошибки в интерактивной версии этих страниц со ссылками на отзыв ниже.