1 .\" Copyright (c) 2005-2012 Apple Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 4. Neither the name of Apple Computer nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nm asl_add_log_file ,
34 .Nm asl_add_outout_file ,
36 .Nm asl_close_auxiliary_file ,
37 .Nm asl_create_auxiliary_file ,
42 .Nm asl_log_auxiliary_location ,
43 .Nm asl_log_descriptor ,
46 .Nm asl_open_from_file ,
47 .Nm asl_remove_log_file ,
52 .Nm asl_set_output_file_filter ,
56 .Nm aslresponse_free ,
58 .Nd system log message sending and searching functions
68 .Fo asl_add_output_file
71 .Fa "const char *msg_fmt"
72 .Fa "const char *time_fmt"
74 .Fa "int text_encoding"
81 .Fo asl_close_auxiliary_file
85 .Fo asl_create_auxiliary_file
87 .Fa "const char *title"
89 .Fa "int *out_descriptor"
110 .Fa "const char *format"
114 .Fo asl_log_auxiliary_location
116 .Fa "const char *title"
117 .Fa "const char *uti"
118 .Fa "const char *url"
121 .Fo asl_log_descriptor
126 .Fa "uint32_t fd_type"
134 .Fa "const char *ident"
135 .Fa "const char *facility"
139 .Fo asl_open_from_file
141 .Fa "const char *ident"
142 .Fa "const char *facility"
145 .Fo asl_remove_log_file
162 .Fa "const char *key"
163 .Fa "const char *value"
171 .Fo asl_set_output_file_filter
179 .Fa "const char *key"
180 .Fa "const char *value"
186 .Fa "const char *key"
193 .Fa "const char *format"
205 These routines provide an interface to the Apple System Log facility.
206 They are intended to be a replacement for the
208 API, which will continue to be supported for backwards compatibility.
209 The new API allows client applications
210 to create flexible, structured messages and send them to the
212 server, where they may undergo additional processing.
213 Messages received by the server are saved in a data store
214 (subject to input filtering constraints).
215 This API permits clients to create queries
216 and search the message data store for matching messages.
218 An introduction to the concepts underlying this interface follows the interface summary below.
219 .Ss INTERFACE SUMMARY
225 creates and returns a client handle, or NULL if an error occurs in the library.
226 Messages sent using this handle will default to having the string
228 as the value associated with the ASL_KEY_SENDER key, and the value
230 associated with the ASL_KEY_FACILITY key.
231 Several options are available, as described in the
235 Each client handle holds state information that is used when a message is logged using that handle.
236 This information includes the
240 strings and the options from the
243 Client handles also contain various filter, file descriptor, and control data.
245 The state information in a client handle is not protected by any locking or thread synchronization mechanism.
246 It is not safe for two or more threads to use a single client handle simultaneously.
247 Multi-threaded applications should generally create one client handle for each thread that logs messages.
248 A client handle may only be safely shared amongst multiple threads if the application uses locks or some
249 synchronization strategy to ensure single-threaded access.
251 As a special case, the ASL library allows the use of NULL in place of a client handle.
252 In this case, the library uses an internal structure which contains its own lock.
253 Multiple threads may safely use NULL, although there may be contention for the lock.
255 Applications that use libdispatch may use NULL in place of a client handle,
256 although this may cause undesirable synchronization behavior and degraded performance because of lock contention.
257 A better design is often to use one or more serial dispatch queues specifically for logging.
258 Each such serial queue should use a separate client handle.
263 closes the client handle
265 and releases its associated resources.
267 .Fo asl_add_output_file
275 adds the file descriptor
277 to the a set of file descriptors associated with the client handle
279 Each log message sent by that client handle is also written to these file descriptors
280 (depending on the setting of the
283 The message format is specified by the
286 The format for timestamps is specified by the
288 argument, although custom format strings may specify more advanced formats for timestamps.
289 Details on custom format strings are below.
291 Each output file has an associated
294 The filter determines which messages are formatted and written to the file based on the message priority level.
296 Special handling for certain characters is specified by the
299 The supported values and their effect are described below.
303 argument is a character string that tells the library how to format each message written to the output file.
304 There are several pre-defined message formats, described below.
305 Custom formats are also supported,
306 giving complete control over which ASL message keys should be written
307 and the overall format of each output line.
308 The pre-defined formats are identified by constants in the asl.h header file.
310 .Bl -tag -width "ASL_MSG_FMT_RAW" -compact
312 The contents of the ASL message dictionaries are formatted as a list,
313 with each key-value pair formatted as
317 Messages are formatted using the standard ASL message format of the form
319 .Dl Time Host Sender[PID] <Level>: Message
321 Time formats are described below.
324 The legacy format used for plain-text log files.
325 Similar to the ASL_MSG_FMT_STD format, but the message priority level is excluded.
328 The output line contains only the value of the Message key in each ASL message dictionary.
331 Produces multiple lines of output for each ASL message.
332 The message is formatted as an XML dictionary:
335 .Dl \t<key>ASLMessageKey1</key>
336 .Dl \t<string>Key 1 Value</string>
337 .Dl \t<key>ASLMessageKey2</key>
338 .Dl \t<string>Key 2 Value</string>
346 causes the library to use the
350 Custom format strings may contain a mix of characters that are directly copied to the output line
351 and variables, which are a dollar sign
353 followed by specific ASL message dictionary keys, whose values will be interpolated into the output.
354 For example, the format string:
356 .Dl This message from $Sender PID=$PID at $Time *** $Message
358 would result in lines in the output file like, e.g.:
360 .Dl This message from login PID=982 at Jul 27 08:41:27 *** USER_PROCESS: 330 ttys000
361 .Dl This message from Mail PID=987 at Jul 27 08:42:16 *** Using V2 Layout
363 Normally, a space character terminates a variable name.
364 However, the name may be wrapped in parentheses if a space character is not desired in the output.
367 .Dl $(Sender)[$(PID)]: $Message
369 A third form for specifying variables may be used for the ASL
376 specification using one of the forms below will override the
378 argument to the function.
380 The following forms are recognized:
382 .Bl -tag -width "$((Time)([+|-]HH[:MM]))"
384 Formats a Level value as a string, for example
389 Note that $(Level) or $Level formats the value as an integer 0 through 7.
391 Formats a Time value as the number of seconds since the Epoch.
393 Alias for $((Time)(sec)).
395 Formats a Time value as a string of the form
396 .Dq "Mmm dd hh:mm:ss" ,
397 where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
398 The local timezone is used.
400 Alias for $((Time)(local)).
402 Formats a Time value as a string of the form
403 .Dq "yyyy-mm-dd hh:mm:ssZ" ,
404 using Coordinated Universal Time, or the
408 Alias for $((Time)(utc)).
410 Where X may be any letter in the range A - Z or a - z.
411 Formats the Time using the format
412 .Dq "yyyy-mm-dd hh:mm:ssX" ,
413 using the specified nautical timezone.
414 Z is the same as UTC/Zulu time. Timezones A - M (except J) decrease by one hour to the east of the
416 Timezones N - Y increase by one hour to the west of Z.
417 M and Y have the same clock time, but differ by one day.
418 J is used to indicate the local timezone.
419 When printing using $((Time)(J)), the output format is
420 .Dq "yyyy-mm-dd hh:mm:ss" ,
421 without a trailing timezone letter.
423 Specifies the local timezone.
424 The timezone offset from UTC follows the date and time.
425 The time is formatted as
426 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
427 Minutes in the timezone offset are only printed if they are non-zero.
428 .It $((Time)(ISO8601))
429 Specifies the local timezone, formatted as specified by ISO 8601.
430 The timezone offset from UTC follows the date and time.
431 The time is formatted as
432 .Dq "yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]" .
433 Minutes in the timezone offset are only printed if they are non-zero.
434 Note that this differs from
436 format only in that a
438 character separates the date and time.
439 .It $((Time)([+|-]HH[:MM]))
440 Specifies an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC.
441 The value is formatted as a string of the form
442 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
443 Minutes in the timezone offset are only printed if they are non-zero.
446 Unless a custom message format uses one of the specialized forms for
448 described above, then any timestamps in an output message will be formatted according the the
451 The known formats are identified by constants in the asl.h header file.
453 .Bl -tag -width "ASL_TIME_FMT_SEC"
455 Formats timestamps as the number of seconds since the Epoch.
458 Formats a Time value as a string of the form
459 .Dq "yyyy-mm-dd hh:mm:ssZ" ,
460 using Coordinated Universal Time, or the
464 Formats a Time value as a string of the form
465 .Dq "Mmm dd hh:mm:ss" ,
466 where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
467 The local timezone is used.
470 A value of NULL for the
472 argument will cause the default format ASL_TIME_FMT_LCL to be used.
476 parameter specifies how certain characters are to be treated when preparing a message for output.
477 The known encodings are:
478 .Bl -tag -width "ASL_ENCODE_NONE"
480 No special character encode is done.
483 Newlines and tabs are also encoded as "\\n" and "\\t" respectively.
486 format, space characters embedded in log message keys are encoded as "\\s"
487 and embedded brackets are escaped to print as "\\[" and "\\]".
490 Encodes backspace characters as ^H.
491 Carriage returns are mapped to newlines.
492 A tab character is appended after newlines so that message text is indented.
495 This encoding should be used when formatting messages using ASL_MSG_FMT_XML.
496 XML format output requires that keys are valid UTF8 strings.
497 Keys which are not valid UTF8 are ignored, and the associated value is not printed.
499 Values that contain legal UTF8 are printed as strings.
500 Ampersand, less than, greater than, quotation mark, and apostrophe characters are encoded according to XML conventions.
501 Embedded control characters are encoded as
503 where NN is the character's hexadecimal value.
505 Values that do not contain legal UTF8 are encoded in base-64 and printed as data objects.
508 .Nm asl_add_output_file
509 Returns 0 on success, non-zero on failure.
518 .Dl asl_add_output_file(asl, descriptor, ASL_MSG_FMT_STD, ASL_TIME_FMT_LCL, ASL_FILTER_MASK_UPTO(ASL_LEVEL_DEBUG), ASL_ENCODE_SAFE);
520 Returns 0 on success, non-zero on failure.
522 .Fo asl_set_output_file_filter
527 replaces the current filter value associated with a file descriptor that has been added to a client handle.
528 Returns the previous filter value.
530 .Fo asl_remove_log_file
534 removes a file descriptor from the set of file descriptors associated with a client handle.
535 Returns 0 on success, non-zero on failure.
540 allocates and returns an aslmsg structure, or NULL in the case of a failure in the library.
543 argument must be ASL_TYPE_MSG or ASL_TYPE_QUERY.
548 frees an aslmsg and releases resources associated with the structure.
555 creates a new key and value in an aslmsg structure, or replaces the value of an existing key.
556 Returns 0 on success, non-zero on failure.
564 is used to construct searches.
567 except that it takes an additional
569 (operation) argument.
570 Creates a new (key, op, value) triple in an aslmsg structure,
571 or replaces the value and operation for an existing key.
574 section for more information.
575 Returns 0 on success, non-zero on failure.
581 removes a key and its associated value from an aslmsg structure.
582 Returns 0 on success, non-zero on failure.
588 returns the nth key in an aslmsg (beginning at zero),
589 allowing an application to iterate through the keys.
592 indexes beyond the number of keys in
599 returns the value associated with
612 sets a filter for messages being sent to the server.
613 The filter is a bitmask representing priority levels.
614 Only messages having a priority level with a corresponding bit set in the filter mask are sent to the
617 The filter does not control writes to additional files associated with the client handle using
618 .Fn asl_add_log_file .
619 Returns the previous filter value.
628 sends a log to the server (subject to filtering, see
630 above) and to any file descriptors associated with the client handle
634 argument may contain any keys and values, which will be formatted as part of the log message.
635 The value for ASL_KEY_LEVEL is supplied by the
638 The value for ASL_KEY_MESSAGE is computed from
640 and the associated arguments
644 style argument processing is applied to the format and the arguments.
645 The format may also contain
647 which will be substituted with the string value corresponding to the current
650 The ASL_PREFILTER_LOG(asl, msg, level, format, ...) macro may be used in
653 The macro avoids processing the variable argument list in those cases where
654 the message would be filtered out due to filter settings, would not be
655 written to a log file associated with the aslclient, or would not be
657 The macro may provide a performance benefit for some applications.
658 Details on filter setting, additional log files, and aslclient options
659 are described below in this manual.
670 except that it takes a va_list argument.
678 except the value for ASL_KEY_MESSAGE is taken from
680 rather than being constructed using a
684 .Fo asl_log_descriptor
691 provides functionality to use file descriptors to send logging data to ASL.
693 is retained by ASL and must still be closed by the caller by calling
695 if the caller loses reference to it.
697 is copied by ASL and similarly must still be freed by the caller by calling
699 if the caller loses reference to it. Any changes made to it after calling
700 .Fn asl_log_descriptor()
701 are not applicable to the message used.
702 .Ar descriptor is treated differently based on the value of
707 is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read access. ASL
710 to read from the descriptor as data becomes available. These data are line
711 buffered and passed to
713 When EOF is read, ASL will
719 is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new writable
720 descriptor is created with the same fileno. Any data written to this new
721 descriptor are line buffered and passed to
723 When EOF is sent, no further data are read. The caller is responsible for
724 closing the new descriptor. One common use for this API is to redirect writes
725 to stdout or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as
732 searches for messages that match the keys and values in
734 subject to matching operations associated with those keys and values.
737 argument should be constructed using
741 section for details on constructing queries.
742 Returns an aslresponse structure that contains matching log messages.
743 NULL is returned in case of error or if there are no matching messages in the ASL database.
748 iterates over an aslresponse structure returned by
750 Each call returns the next aslmsg in the response.
751 Returns NULL when there are no further messages.
756 frees the aslresponse structure
758 and all of its associated resources.
760 .Fo asl_create_auxiliary_file
766 Creates an auxiliary file that may be used by the client to save arbitrary data.
767 When the file is closed using
768 .Fo asl_close_auxiliary_file
771 will log the specified
775 and the Uniform Type Identifier provided by
777 If a NULL value is supplied for
784 application will display the message with a link to the file.
786 Auxiliary files are saved in the ASL data store.
787 They are automatically deleted at the same time that the log message expires.
788 Messages expire in 7 days by default.
789 A value set for the ASLExpireTime key will override the default.
790 Read access for the auxiliary file will be the same as read access for
792 By default, messages (and auxiliary files) are world-readable.
793 Access may be limited by setting values for the ReadUID and ReadGID keys.
795 .Fo asl_close_auxiliary_file
798 closes the file descriptor
800 previously returned by a call to
801 .Fn asl_create_auxiliary_file .
803 .Fo asl_log_auxiliary_location
809 will log the specified
813 the Uniform Type Identifier provided by
815 and the Uniform Resource Locator provided by
819 application will display the message with a link to the file.
820 This allows a client to save data in an auxiliary file, but unlike
821 .Fo asl_create_auxiliary_file
823 the life-cycle of this file must be managed by some external system.
824 The file will not be removed when the corresponding log message expired from the ASL data store.
826 .Fo asl_open_from_file
831 creates a client handle for an open file descriptor
833 This routine may be used in conjunction with
834 .Fo asl_create_auxiliary_file
837 .Fo asl_log_auxiliary_location
839 to save ASL format log messages in an auxiliary file.
841 .Dq com.apple.asl-file
842 should be used for ASL format auxiliary files.
844 Files with this format may be read from the command line using
845 .Nm syslog Fl f Ar file ,
850 The file must be open for read and write access.
851 The file will be truncated and its existing contents will be lost.
854 must be called to close the client handle when logging to this file is complete.
855 The file should be closed using
856 .Fo asl_close_auxiliary_file
858 if it was returned by
859 .Fo asl_create_auxiliary_file
866 The client handle returned by
867 .Fn asl_open_from_file
868 contains an internal lock, and may be used safely by multiple threads or from independent dispatch queues.
869 Note that callers will contend for the internal lock when saving log messages to a file.
871 Note that messages with ReadUID or ReadGID values will simply be saved to the file,
872 and will not effect read access to either the message or the file itself.
873 Similarly, messages with ASLExpireTime values will be saved, but will not effect the
874 life-cycle of either the individual messages or the file.
876 At the core of this API is the aslmsg structure.
877 Although the structure is opaque and may not be directly manipulated,
878 it contains a list of key/value pairs.
879 All keys and values are NUL-character terminated C language strings.
880 UTF-8 encoding may be used for non-ASCII characters.
882 Message structures are generally used to send log messages,
883 and are created thusly:
885 aslmsg m = asl_new(ASL_TYPE_MSG);
887 Another message type, ASL_TYPE_QUERY,
888 is used to create queries when searching the data store.
889 Query type messages and searching are described in detail in the
892 For the remainder of this section,
893 the messages described will be of the ASL_TYPE_MSG variety.
895 Each aslmsg contains a default set of keys
896 and values that are associated with them.
897 These keys are listed in the asl.h header file.
900 #define ASL_KEY_TIME "Time"
901 #define ASL_KEY_HOST "Host"
902 #define ASL_KEY_SENDER "Sender"
903 #define ASL_KEY_FACILITY "Facility"
904 #define ASL_KEY_PID "PID"
905 #define ASL_KEY_UID "UID"
906 #define ASL_KEY_GID "GID"
907 #define ASL_KEY_LEVEL "Level"
908 #define ASL_KEY_MSG "Message"
910 Many of these correspond to equivalent parts of messages described in the
913 Values associated with these message keys are assigned appropriate defaults.
914 The value for ASL_KEY_HOST is the local host name,
915 the value associated with ASL_KEY_SENDER is the process name,
916 the ASL_KEY_PID is the client's process ID number, and so on.
918 Note the addition of the UID and GID keys.
919 The values for UID and GID are set in library code by the message sender.
920 The server will attempt to confirm the values,
921 but no claim is made that these values cannot be maliciously overridden
922 in an attempt to deceive a log message reader
923 as to the identity of the sender of a message.
924 The contents of log messages must be regarded as insecure.
928 API does not require a process to choose a facility name.
931 server will use a default value of
933 if a facility is not set.
934 However, a client may set a facility name as an argument in the
936 call, or by setting a specific value for the ASL_KEY_FACILITY in a message:
938 asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");
940 An application may choose any facility name at will.
941 Different facility names may be attached to different messages, perhaps to distinguish different subsystems in log messages.
942 Developers are encouraged to adopt a
944 naming convention to avoid conflicting facility names.
946 Default values are set in the message for each of the keys listed above,
947 except for ASL_KEY_MSG,
948 which may be explicitly set at any time using the
950 routine, or implicitly set at the time the message is sent using the
955 These two routines also have an integer-level parameter
956 for specifying the log priority.
957 The ASL_KEY_LEVEL value is set accordingly.
958 Finally, the value associated with ASL_KEY_TIME
959 is set in the sending routine.
961 Although it may appear that there is significant overhead required
962 to send a log message using this API,
963 the opposite is actually true.
966 program requires only:
970 asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!");
976 will provide the appropriate default values
977 when passed a NULL aslmsg argument.
980 In this example, the aslclient argument is NULL.
981 This is sufficient for a single-threaded application,
982 or for an application which only sends log messages from a single thread.
983 When logging from multiple threads,
986 open a separate client handle using
988 The client handle may then be closed when it is no longer required using
990 Multiple threads may log messages safely using a NULL aslclient argument,
991 but the library will use an internal lock, so that in fact only one thread
994 When an application requires additional keys and values
995 to be associated with each log message,
996 a single message structure may be allocated and set up as
1000 aslmsg m = asl_new(ASL_TYPE_MSG);
1001 asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us");
1002 asl_set(m, "Clearance", "Top Secret");
1004 asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One");
1006 asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two");
1008 The message structure will carry the values set for the
1012 keys so that they are used in each call to
1014 while the log level and the message text
1015 are taken from the calling parameters.
1027 which is replaced by the current error message
1028 (as denoted by the global variable
1033 Key/value pairs may be removed from a message structure with
1035 A message may be freed using
1044 to transmit a message to the server.
1045 This routine sets the value associated with ASL_KEY_TIME
1046 and sends the message.
1047 It may be called directly if all of a message's key/value pairs
1048 have been created using
1051 Messages that are sent to the
1053 server may be saved in a message store.
1054 The store may be searched using
1057 By default, all messages are readable by any user.
1058 However, some applications may wish to restrict read access
1060 To accommodate this,
1061 a client may set a value for the "ReadUID" and "ReadGID" keys.
1062 These keys may be associated with a value
1063 containing an ASCII representation of a numeric UID or GID.
1064 Only the root user (UID 0),
1065 the user with the given UID,
1066 or a member of the group with the given GID
1067 may fetch access-controlled messages from the database.
1069 Although the ASL system does not require a "Facility" key in a message,
1070 many processes specify a "Facility" value similar
1071 to the common usage of the BSD
1073 API, although developers are encouraged to adopt facility names that make sense for their application.
1076 naming convention (e.g. "com.apple.system.syslog") should be adopted to avoid conflicting names.
1077 The ASL system generally allows any string to be used as a facility value,
1079 The value "com.apple.system",
1080 or any string that has "com.apple.system" as a prefix,
1081 may only be used by processes running with the UID 0.
1082 This allows system processes to log messages that can not be "spoofed" by user processes.
1083 Non-UID 0 client processes that specify "com.apple.system" as a facility, will be assigned the value "user"
1088 A client handle contains various parameters and control settings that are used when a message is logged.
1089 This includes an identification string, a facility name, filtering controls, additional file descriptors, and other data.
1090 Client handles are not thread-safe.
1091 Applications that log from multiple threads should create a client handle for each thread.
1093 Applications that use libdispatch must also avoid using a single client handle from multiple dispatch queues if those queues may run concurrently.
1094 A good approach is to create one or more serial dispatch queues specifically for logging.
1095 Each such queue should use its own ASL client handle.
1097 If a single handle must be accessed by multiple dispatch queues,
1098 then the application must use locks, semaphores, or some other mechanism to prevent concurrent access to a client handle.
1100 A NULL value may be used in any of the routines
1101 that require an aslclient argument.
1102 In this case, the library will use an internal client handle.
1103 This internal handle contains its own lock, allowing multiple threads to safely use the NULL client handle.
1104 Note, however, that contention for the lock may cause undesirable synchronization behavior or reduced performance.
1108 routine may be given an ident argument,
1109 which becomes the default value for the ASL_KEY_SENDER key,
1110 and a facility argument,
1111 which becomes the value associated with the ASL_KEY_FACILITY key.
1112 If NULL is passed as the value for
1114 the name of the currently running program will be used.
1115 If NULL is passed as the value for
1119 will be used for non UID 0 processes, and
1122 will be used for UID 0 processes.
1124 Several options are available when creating a client handle.
1127 .Bl -tag -width "ASL_OPT_NO_REMOTE" -compact
1129 adds stderr as an output file descriptor
1130 .It ASL_OPT_NO_DELAY
1131 connects to the server immediately
1132 .It ASL_OPT_NO_REMOTE
1133 disables remote-control filter adjustment
1136 ASL_OPT_NO_DELAY makes the client library connect to the
1138 server at the time that
1140 is called, rather than waiting for the first message to be sent.
1141 Opening the connection is quite fast, but some applications may want to avoid any unnecessary delays when calling
1147 See the FILTERING section below, and the
1149 for additional details on filter controls.
1151 A client handle is closed and its resources released using
1153 Note that if additional file descriptors were added to the handle,
1154 either using the ASL_OPT_STDERR option
1155 or afterwards with the
1156 .Nm asl_add_log_file
1157 routine, those file descriptors are not closed by
1159 .Ss LOGGING TO ADDITIONAL FILES
1160 If a client handle is opened with the ASL_OPT_STDERR option to
1162 a copy of each log message will be sent to stderr.
1163 Additional output streams may be include using
1164 .Nm asl_add_log_file .
1166 Messages sent to stderr or other files are printed in the "standard" message format
1167 also used as a default format by the
1169 command line utility.
1170 Non-ASCII characters in a message are encoded using the
1172 encoding style used by
1177 Backspace characters are printed as ^H.
1178 Carriage returns are mapped to newlines.
1179 A tab character is appended after newlines so that message text is indented.
1181 File descriptors may be removed from the list of outputs associated
1182 with a client handle with
1183 .Nm asl_remove_log_file .
1184 This routine simply removes the file descriptor from the output list.
1185 The file is not closed as a result.
1187 The ASL_OPT_STDERR option may not be unset
1188 after a client handle has been opened.
1192 server archives received messages in a data store
1193 that may be searched using the
1195 .Nm aslresponse_next ,
1197 .Nm aslresponse_free
1199 A query message is created using:
1201 aslmsg q = asl_new(ASL_TYPE_QUERY);
1203 Search settings are made in the query using
1205 A search is performed on the data store with
1210 The caller may then call
1211 .Nm aslresponse_next
1212 to iterate through matching messages.
1215 structure may be freed with
1216 .Nm aslresponse_free .
1218 Like other messages, ASL_TYPE_QUERY messages contain keys and values.
1219 They also associate an operation with each key and value.
1220 The operation is used to decide if a message matches the query.
1221 The simplest operation is ASL_QUERY_OP_EQUAL, which tests for equality.
1222 For example, the following code snippet searches for messages
1223 with a Sender value equal to
1228 q = asl_new(ASL_TYPE_QUERY);
1229 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
1230 r = asl_search(NULL, q);
1232 More complex searches may be performed using other query operations.
1234 .Bl -tag -width "ASL_QUERY_OP_GREATER_EQUAL" -compact
1235 .It ASL_QUERY_OP_EQUAL
1237 .It ASL_QUERY_OP_GREATER
1239 .It ASL_QUERY_OP_GREATER_EQUAL
1240 value greater than or equal to
1241 .It ASL_QUERY_OP_LESS
1243 .It ASL_QUERY_OP_LESS_EQUAL
1244 value less than or equal to
1245 .It ASL_QUERY_OP_NOT_EQUAL
1247 .It ASL_QUERY_OP_REGEX
1248 regular expression search
1249 .It ASL_QUERY_OP_TRUE
1250 always true - use to test for the existence of a key
1253 Regular expression search uses
1256 Patterns are compiled using the REG_EXTENDED and REG_NOSUB options.
1258 Modifiers that change the behavior of these operations
1259 may also be specified by ORing the modifier value with the operation.
1262 .Bl -tag -width "ASL_QUERY_OP_SUBSTRING" -compact
1263 .It ASL_QUERY_OP_CASEFOLD
1264 string comparisons are case-folded
1265 .It ASL_QUERY_OP_PREFIX
1266 match a leading substring
1267 .It ASL_QUERY_OP_SUFFIX
1268 match a trailing substring
1269 .It ASL_QUERY_OP_SUBSTRING
1271 .It ASL_QUERY_OP_NUMERIC
1272 values are converted to integer using
1276 The only modifier that is checked
1277 for ASL_QUERY_OP_REGEX search is ASL_QUERY_OP_CASEFOLD.
1278 This causes the regular expression to be compiled
1279 with the REG_ICASE option.
1281 If a query message contains more than one set of key/value/operation triples,
1282 the result will be a logical AND. For example, to find messages from
1284 with a priority level less than or equal to
1289 q = asl_new(ASL_TYPE_QUERY);
1290 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
1291 asl_set_query(q, ASL_KEY_LEVEL, "3",
1292 ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC);
1293 r = asl_search(NULL, q);
1300 .Nm aslresponse_next
1301 to iterate through all matching messages.
1302 To iterate through the keys and values in a message, use
1304 to iterate through the keys, then call
1306 to get the value associated with each key.
1310 const char *key, *val;
1313 r = asl_search(NULL, q);
1314 while (NULL != (m = aslresponse_next(r)))
1316 for (i = 0; (NULL != (key = asl_key(m, i))); i++)
1318 val = asl_get(m, key);
1322 aslresponse_free(r);
1324 .Ss FILTERING AND REMOTE CONTROL
1325 Clients may set a filter mask value with
1326 .Nm asl_set_filter .
1327 The mask specifies which messages should be sent to the
1329 daemon by specifying a yes/no setting for each priority level.
1330 Clients typically set a filter mask
1331 to avoid sending relatively unimportant messages.
1332 For example, Debug or Info priority level messages
1333 are generally only useful for debugging operations.
1334 By setting a filter mask, a process can improve performance
1335 by avoiding sending messages that are in most cases unnecessary.
1337 .Nm asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the routine was called.
1339 As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(level)
1340 may be used to construct a bit mask corresponding to a given priority level,
1341 or corresponding to a bit mask for all priority levels
1342 from ASL_LEVEL_EMERG to a given input level.
1344 The default filter mask is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
1345 This means that by default,
1346 and in the absence of remote-control changes (described below),
1347 ASL_LEVEL_DEBUG and ASL_LEVEL_INFO priority level messages
1352 Three different filters exist for each application.
1353 The first is the filter mask set using
1356 The Apple System Log facility also manages a
1359 The master filter mask usually has a value
1360 that indicates to the library that it is
1362 and thus it has no effect.
1363 However, the mask filter mask may be enabled
1364 by giving it a value using the
1369 When the master filter mask has been set,
1370 it takes precedence over the client's filter mask.
1371 The client's mask is unmodified,
1372 and will become active again if remote-control filtering is disabled.
1374 In addition to the master filter mask,
1375 The Apple System Log facility
1376 also manages a per-client remote-control filter mask.
1377 Like the master filter mask, the per-client mask is usually
1379 having no effect on a client.
1380 If a per-client filter mask is set using the
1384 option, then it takes precedence
1385 over both the client's filter mask and the master filter mask.
1386 As is the case with the master filter mask,
1387 a per-client mask ceases having any effect when if is disabled.
1389 The ASL_OPT_NO_REMOTE option to
1391 causes both the master and per-client remote-control masks
1392 to be ignored in the library.
1393 In that case, only the client's own filter mask
1394 is used to determine which messages are sent to the server.
1395 This may be useful for Applications that produce log messages
1396 that should never be filtered, due to security considerations.
1397 Note that root (administrator) access is required
1398 to set or change the master filter mask,
1399 and that only root may change a per-client remote-control filter mask
1400 for a root (UID 0) process.
1402 The per-process remote control filter value is kept as a state value
1403 associated with a key managed by
1405 The key is protected by an access control mechanism that only permits the
1406 filter value to be accessed and modified by the same effective UID as the
1407 ASL client at the time that the first ASL connection was created.
1408 Remote filter control using
1410 will fail for processes that change effective UID after starting an ASL connection.
1411 Those processes should close all ASL client handles and then re-open ASL connections
1412 if remote filter control support is desired.
1414 These functions first appeared in
projects / apple / syslog.git / blob