1 .\" Copyright (c) 2005-2013 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_output_file ,
37 .Nm asl_close_auxiliary_file ,
39 .Nm asl_create_auxiliary_file ,
40 .Nm asl_decode_buffer ,
41 .Nm asl_encode_buffer ,
42 .Nm asl_fetch_key_val_op ,
50 .Nm asl_log_auxiliary_location ,
51 .Nm asl_log_descriptor ,
56 .Nm asl_open_from_file ,
61 .Nm asl_remove_index ,
62 .Nm asl_remove_log_file ,
63 .Nm asl_reset_iteration ,
69 .Nm asl_set_output_file_filter ,
73 .Nm aslresponse_free ,
75 .Nd system log message sending and searching functions
81 .Fa "asl_object_t client"
85 .Fo asl_add_output_file
86 .Fa "asl_object_t client"
88 .Fa "const char *msg_fmt"
89 .Fa "const char *time_fmt"
91 .Fa "int text_encoding"
95 .Fa "asl_object_t obj"
96 .Fa "asl_object_t msg"
101 .Fa "asl_object_t obj"
104 .Fo asl_close_auxiliary_file
109 .Fa "asl_object_t obj"
112 .Fo asl_create_auxiliary_file
113 .Fa "asl_object_t msg"
114 .Fa "const char *title"
115 .Fa "const char *uti"
116 .Fa "int *out_descriptor"
119 .Fo asl_decode_buffer
125 .Fo asl_encode_buffer
130 .Fo asl_fetch_key_val_op
131 .Fa "asl_object_t msg"
133 .Fa "const char **key"
134 .Fa "const char **val"
139 .Fa "asl_object_t msg"
140 .Fa "const char *msg_fmt"
141 .Fa "const char *time_fmt"
142 .Fa "uint32_t text_encoding"
144 .Ft [DEPRECATED] void
146 .Fa "asl_object_t obj"
150 .Fa "asl_object_t msg"
151 .Fa "const char *key"
155 .Fa "asl_object_t list"
160 .Fa "asl_object_t obj"
164 .Fa "asl_object_t msg"
169 .Fa "asl_object_t obj"
170 .Fa "asl_object_t msg"
172 .Fa "const char *format"
176 .Fo asl_log_auxiliary_location
177 .Fa "asl_object_t msg"
178 .Fa "const char *title"
179 .Fa "const char *uti"
180 .Fa "const char *url"
183 .Fo asl_log_descriptor
184 .Fa "asl_object_t client"
185 .Fa "asl_object_t msg"
188 .Fa "uint32_t fd_type"
193 .Fa "const char *format"
198 .Fa "asl_object_t obj"
199 .Fa "asl_object_t querylist"
203 .Fa "uint32_t duration"
204 .Fa "int32_t direction"
212 .Fa "asl_object_t obj"
216 .Fa "const char *ident"
217 .Fa "const char *facility"
221 .Fo asl_open_from_file
223 .Fa "const char *ident"
224 .Fa "const char *facility"
228 .Fa "const char *path"
233 .Fa "asl_object_t obj"
234 .Fa "asl_object_t msg"
238 .Fa "asl_object_t obj"
242 .Fa "asl_object_t obj"
246 .Fa "asl_object_t list"
250 .Fo asl_remove_log_file
251 .Fa "asl_object_t asl"
255 .Fo asl_reset_iteration
256 .Fa "asl_object_t obj"
257 .Fa "size_t position"
261 .Fa "asl_object_t obj"
265 .Fa "asl_object_t obj"
266 .Fa "asl_object_t query"
270 .Fa "asl_object_t obj"
271 .Fa "asl_object_t msg"
275 .Fa "asl_object_t msg"
276 .Fa "const char *key"
277 .Fa "const char *value"
281 .Fa "asl_object_t asl"
285 .Fo asl_set_output_file_filter
286 .Fa "asl_object_t asl"
292 .Fa "asl_object_t msg"
293 .Fa "const char *key"
294 .Fa "const char *value"
299 .Fa "asl_object_t msg"
300 .Fa "const char *key"
304 .Fa "asl_object_t obj"
305 .Fa "asl_object_t msg"
307 .Fa "const char *format"
310 .Ft [DEPRECATED] void
312 .Fa "asl_object_t obj"
314 .Ft [DEPRECATED] asl_object_t
316 .Fa "asl_object_t obj"
320 This interface is obsoleted by
324 These routines provide an interface to the Apple System Log facility and to various
325 data bearing memory objects, files, and storage directories.
327 The API allows client applications to create and manipulate
328 flexible, structured messages, send them to the
330 server, where they may undergo additional processing.
331 Messages received by the server are saved in a data store
332 (subject to input filtering constraints).
334 Log messages may also be written directly to the filesystem from the ASL library.
335 This output may go to plain text files, to ASL-format data files, or to ASL databases.
337 This API permits clients to create queries
338 and search the system ASL database, ASL-format files, or other ASL databases for matching messages.
340 Clients that simply need to send messages to the ASL server may do so using
341 .Fn asl_log_message .
342 Other routines allow for more complex logging tasks.
344 An introduction to the concepts underlying this interface follows the interface summary below.
345 .Ss INTERFACE SUMMARY
351 sends a message to the ASL server
354 is an integer between 7 (ASL_LEVEL_DEBUG) and 0 (ASL_LEVEL_EMERG),
355 indicating the priority of the message.
356 Note that message priority levels are used as the basis of filtering
357 messages in several places in the ASL system.
358 In general, messages with level ASL_LEVEL_DEBUG and ASL_LEVEL_INFO are often excluded from long-term storage,
359 or have shorter time-to-live durations.
362 is a printf-like format string.
363 In addition to the conversion specifications supported by
368 conversion, which is converted to the current error string returned by the
370 function for the current value of
374 is a simplified version of the
377 It uses the default (NULL) ASL client handle.
378 This interface is thread-safe, although callers will contend for a mutex lock when using this routine.
379 Applications that log from multiple threads or dispatch queues may experience undesired performance
380 characteristics when using this routine.
388 is advised for applications that log from multiple threads.
397 prepares a message, normally to be sent to the ASL server
401 may be an asl_object_t of any type.
402 It is typically of type ASL_TYPE_CLIENT.
403 In this case the settings and options associated with the ASL client handle
405 are used when preparing the message.
406 The client may direct the ASL library to
407 print copies of the message to various output files as well as sending it to the ASL server.
408 Filter settings in the client may further direct the library in selecting where the message
409 will be sent, and may in fact prevent the message from being sent to the ASL server at all.
410 ASL client handles are created using
412 and are described extensively below.
414 ASL message are dictionaries.
417 routine combines information carried in the ASL client handle
419 and the ASL message dictionary
423 string and the associated arguments to construct a final message to be sent
424 to the ASL server and/or to be written to output files.
425 In general, the ASL client handle will provide the values for the
426 ASL_KEY_SENDER and ASL_KEY_FACILITY keys.
429 is non-NULL, it may override the values for ASL_KEY_SENDER and ASL_KEY_FACILITY,
430 and it may supply additional key/value pairs.
433 string and its associated arguments are used to construct a string value for the
434 ASL_KEY_MSG key in the final log message dictionary.
438 parameter is of a type other than ASL_TYPE_CLIENT, then
440 creates a message as if it were to be sent to
442 but rather than sending the message, it stores the message in the
447 is of type ASL_TYPE_FILE or ASL_TYPE_STORE that has been opened for writing,
448 then the message is saved to the file or ASL data store.
451 is of type ASL_TYPE_LIST, then the message is appended to the list.
454 is of type ASL_TYPE_MSG, then the message key/value pairs constructed by
458 In a merge operation, existing keys and values in
463 message are attached.
464 Although this routine works for type ASL_TYPE_QUERY,
465 new key/value pairs are attached with an operation value of zero.
467 The ASL_PREFILTER_LOG(obj, msg, level, format, ...) macro may be used in
472 is of type ASL_TYPE_CLIENT.
473 The macro avoids processing the variable argument list in those cases where
474 the message would be filtered out due to filter settings, would not be
475 written to a log file associated with the asl_object_t, or would not be
477 The macro may provide a performance benefit for some applications.
478 Details on filter setting, additional log files, and asl_object_t options
479 are described below in this manual.
490 except that it takes a va_list argument.
498 except the value for ASL_KEY_MSG is taken from
500 rather than being constructed using a
509 creates and returns a client handle, or NULL if an error occurs in the library.
510 Messages sent using this handle will default to having the string
512 as the value associated with the ASL_KEY_SENDER key, and the value
514 associated with the ASL_KEY_FACILITY key.
517 is NULL, the library uses the sending process name.
520 is NULL, the library will use the
522 facility for processes with non-zero UID, and
524 for processes with zero UID.
526 Several options are available, as described in the
530 Each client handle holds state information that is used when a message is logged using that handle.
531 This information includes the
535 strings and the options from the
538 Client handles also contain various filter, file descriptor, and control data.
540 The state information in a client handle is not protected by locking or thread synchronization mechanisms,
541 except for one special case where NULL is used as a client handle.
542 That special case is described below.
544 It is not safe for two or more threads to use a single client handle simultaneously.
545 Multi-threaded applications should generally create one client handle for each thread
546 or serial dispatch queue that logs messages.
547 A client handle may only be safely shared amongst multiple threads if the application uses locks or some
548 synchronization strategy to ensure single-threaded access.
550 As a special case, the ASL library allows the use of NULL in place of a client handle.
551 In this case, the library uses an internal structure which contains its own lock.
552 Multiple threads may safely use NULL in place of an ASL client handle,
553 although there may be contention for the lock.
555 Applications that use libdispatch may use NULL in place of a client handle,
556 although this may cause undesirable synchronization behavior and degraded performance because of lock contention.
557 A better design is often to use one or more serial dispatch queues specifically for logging.
558 Each such serial queue should use a separate client handle.
564 opens an ASL data store or ASL data file for read or write access.
565 Returns an object of type ASL_TYPE_STORE or ASL_TYPE_FILE,
566 depending on the input parameters.
567 By default, the ASL store or file is opened for reading.
568 The routine checks the filesystem type of
570 and returns an object of type ASL_TYPE_STORE for an ASL data store (a directory in the filesystem)
571 or an object of type ASL_TYPE_FILE for an ASL data file.
574 is NULL, the system's ASL database (/var/log/asl) is opened.
576 If the ASL_OPT_OPEN_WRITE option is specified, an existing file or database is
578 New messages may be added to the file or database using
584 Existing messages in the store or file may not be deleted or modified.
586 If the path does not exist in the filesystem,
588 will create a new data store if ASL_OPT_CREATE_STORE is set in the options,
589 The file will be created with the user's effective UID and GID as owner and group.
590 The mode will be 0644.
591 If a different mode, UID, or GID is desired, an empty file or directory may be
592 pre-created with the desired settings.
597 closes the client handle
599 and releases its associated resources.
601 may also be used to close a client handle.
607 sets a filter for messages being sent to the server.
608 The filter is a bitmask representing priority levels.
609 Only messages having a priority level with a corresponding bit set in the filter mask are sent to the
612 The filter does not control writes to additional files associated with the client handle using
613 .Fn asl_add_output_file .
615 returns the previous filter value.
617 .Fo asl_add_output_file
625 adds the file descriptor
627 to the a set of file descriptors associated with the client handle
629 Each log message sent by that client handle is also written to these file descriptors
630 (depending on the setting of the
633 The message format is specified by the
636 The format for timestamps is specified by the
638 argument, although custom format strings may specify more advanced formats for timestamps.
639 Details on custom format strings are below.
641 Each output file has an associated
644 The filter determines which messages are formatted and written to the file based on the message priority level.
646 Special handling for certain characters is specified by the
649 The supported values and their effect are described below.
653 argument is a character string that tells the library how to format each message written to the output file.
654 There are several pre-defined message formats, described below.
655 Custom formats are also supported,
656 giving complete control over which ASL message keys should be written
657 and the overall format of each output line.
658 The pre-defined formats are identified by constants in the asl.h header file.
660 .Bl -tag -width "ASL_MSG_FMT_RAW" -compact
662 The contents of the ASL message dictionaries are formatted as a list,
663 with each key-value pair formatted as
667 Messages are formatted using the standard ASL message format of the form
669 .Dl Time Host Sender[PID] <Level>: Message
671 Time formats are described below.
674 The legacy format used for plain-text log files.
675 Similar to the ASL_MSG_FMT_STD format, but the message priority level is excluded.
678 The output line contains only the value of the Message key in each ASL message dictionary.
681 Produces multiple lines of output for each ASL message.
682 The message is formatted as an XML dictionary:
685 .Dl \t<key>ASLMessageKey1</key>
686 .Dl \t<string>Key 1 Value</string>
687 .Dl \t<key>ASLMessageKey2</key>
688 .Dl \t<string>Key 2 Value</string>
696 causes the library to use the ASL_MSG_FMT_STD format.
698 Custom format strings may contain a mix of characters that are directly copied to the output line
699 and variables, which are a dollar sign
701 followed by specific ASL message dictionary keys, whose values will be interpolated into the output.
702 For example, the format string:
704 .Dl This message from $Sender PID=$PID at $Time *** $Message
706 would result in lines in the output file like, e.g.:
708 .Dl This message from login PID=982 at Jul 27 08:41:27 *** USER_PROCESS: 330 ttys000
709 .Dl This message from Mail PID=987 at Jul 27 08:42:16 *** Using V2 Layout
711 Normally, a space character terminates a variable name.
712 However, the name may be wrapped in parentheses if a space character is not desired in the output.
715 .Dl $(Sender)[$(PID)]: $Message
717 A third form for specifying variables may be used for the ASL
724 specification using one of the forms below will override the
726 argument to the function.
728 The following forms are recognized:
730 .Bl -tag -width "$((Time)([+|-]HH[:MM]))"
732 Formats a Level value as a string, for example
737 Note that $(Level) or $Level formats the value as an integer 0 through 7.
739 Formats a Level value as a single character from the set
741 for levels 0 through 7.
742 These are abbreviations for Panic, Alert, Critical, Error, Warning, Notice, Info, and Debug.
744 Formats a Time value as the number of seconds since the Epoch.
746 Alias for $((Time)(sec)).
748 Formats a Time value as a string of the form
749 .Dq "Mmm dd hh:mm:ss" ,
750 where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
751 The local timezone is used.
753 Alias for $((Time)(local)).
755 Formats a Time value as a string of the form
756 .Dq "yyyy-mm-dd hh:mm:ssZ" ,
757 using Coordinated Universal Time, or the
761 Alias for $((Time)(utc)).
763 Where X may be any letter in the range A - Z or a - z.
764 Formats the Time using the format
765 .Dq "yyyy-mm-dd hh:mm:ssX" ,
766 using the specified nautical timezone.
767 Z is the same as UTC/Zulu time. Timezones A - M (except J) decrease by one hour to the east of the
769 Timezones N - Y increase by one hour to the west of Z.
770 M and Y have the same clock time, but differ by one day.
771 J is used to indicate the local timezone.
772 When printing using $((Time)(J)), the output format is
773 .Dq "yyyy-mm-dd hh:mm:ss" ,
774 without a trailing timezone letter.
776 Specifies the local timezone.
777 The timezone offset from UTC follows the date and time.
778 The time is formatted as
779 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
780 Minutes in the timezone offset are only printed if they are non-zero.
781 .It $((Time)(ISO8601))
782 Specifies the local timezone, formatted as specified by ISO 8601.
783 The timezone offset from UTC follows the date and time.
784 The time is formatted as
785 .Dq "yyyy-mm-ddThh:mm:ss[+|-]HH[:MM]" .
786 Minutes in the timezone offset are only printed if they are non-zero.
787 Note that this differs from
789 format only in that a
791 character separates the date and time.
792 .It $((Time)([+|-]HH[:MM]))
793 Specifies an offset (+ or -) of the indicated number of hours (HH) and optionally minutes (MM) to UTC.
794 The value is formatted as a string of the form
795 .Dq "yyyy-mm-dd hh:mm:ss[+|-]HH[:MM]" .
796 Minutes in the timezone offset are only printed if they are non-zero.
799 Unless a custom message format uses one of the specialized forms for
801 described above, then any timestamps in an output message will be formatted according the the
804 The known formats are identified by constants in the asl.h header file.
806 .Bl -tag -width "ASL_TIME_FMT_SEC"
808 Formats timestamps as the number of seconds since the Epoch.
811 Formats a Time value as a string of the form
812 .Dq "yyyy-mm-dd hh:mm:ssZ" ,
813 using Coordinated Universal Time, or the
817 Formats a Time value as a string of the form
818 .Dq "Mmm dd hh:mm:ss" ,
819 where Mmm is the abbreviation for the month, dd is the date (1 - 31) and hh:mm:ss is the time.
820 The local timezone is used.
823 A value of NULL for the
825 argument will cause the default format ASL_TIME_FMT_LCL to be used.
829 parameter specifies how certain characters are to be treated when preparing a message for output.
830 The known encodings are:
831 .Bl -tag -width "ASL_ENCODE_NONE"
833 No special character encode is done.
836 Newlines and tabs are also encoded as "\\n" and "\\t" respectively.
839 format, space characters embedded in log message keys are encoded as "\\s"
840 and embedded brackets are escaped to print as "\\[" and "\\]".
843 Encodes backspace characters as ^H.
844 Carriage returns are mapped to newlines.
845 A tab character is appended after newlines so that message text is indented.
848 This encoding should be used when formatting messages using ASL_MSG_FMT_XML.
849 XML format output requires that keys are valid UTF8 strings.
850 Keys which are not valid UTF8 are ignored, and the associated value is not printed.
852 Values that contain legal UTF8 are printed as strings.
853 Ampersand, less than, greater than, quotation mark, and apostrophe characters are encoded according to XML conventions.
854 Embedded control characters are encoded as
856 where NN is the character's hexadecimal value.
858 Values that do not contain legal UTF8 are encoded in base-64 and printed as data objects.
861 .Fn asl_add_output_file
862 Returns 0 on success, non-zero on failure.
871 .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);
873 Returns 0 on success, non-zero on failure.
875 .Fo asl_set_output_file_filter
880 replaces the current filter value associated with a file descriptor that has been added to a client handle.
881 Returns the previous filter value.
883 .Fo asl_remove_log_file
887 removes a file descriptor from the set of file descriptors associated with a client handle.
888 Returns 0 on success, non-zero on failure.
898 object using the message format string, time format string, and text encoding specified.
899 Message formatting is described above for the
900 .Fn asl_add_output_file
902 The caller must free the returned character string.
907 allocates and returns an asl_object_t structure, or NULL in the case of a failure in the library.
910 argument should be ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_LIST.
915 Returns the type of the object
917 or ASL_TYPE_UNDEF if the object is not a recognized type.
922 Increments an internal reference count for
924 ASL objects are created with a reference count of 1.
925 Objects returned by ASL routines should be retained if they are used outside
926 of the immediate scope of the call that returned them.
931 Decrements the internal reference count for
933 It frees the object and its associated resources when the reference count becomes zero.
939 This interface is deprecated in favor of
941 It is implemented as a call to
949 creates a new key and value in an asl_object_t structure, or replaces the value of an existing key.
950 Returns 0 on success, non-zero on failure.
958 is used to construct searches.
961 except that it takes an additional
963 (operation) argument.
964 Creates a new (key, op, value) triple in an asl_object_t structure,
965 or replaces the value and operation for an existing key.
968 section for more information.
969 Returns 0 on success, non-zero on failure.
975 removes a key and its associated value from an asl_object_t structure.
976 Returns 0 on success, non-zero on failure.
982 returns the nth key in an asl_object_t (beginning at zero),
983 allowing an application to iterate through the keys.
986 indexes beyond the number of keys in
993 returns the value associated with
1002 .Fo asl_fetch_key_val_op
1014 output parameters, the key, value, and operation (for ASL_TYPE_QUERY) at index
1020 should be of type ASL_TYPE_MSG or ASL_TYPE_QUERY.
1021 Returns 0 on success, or non-zero otherwise.
1022 Any of the output parameters may be NULL, in which case that parameter value will not
1028 returns a count of the number of elements contained in
1030 For objects of type ASL_TYPE_MSG or ASL_TYPE_QUERY,
1031 this is the number of dictionary keys.
1032 For ASL_TYPE_LIST, it is the number of items in the list.
1033 For ASL_TYPE_FILE, returns the number of messages contained in the file.
1034 Returns zero for ASL_TYPE_STORE and ASL_TYPE_CLIENT.
1042 object, which is typically of type ASL_TYPE_MSG or ASL_TYPE_QUERY, to the target
1046 is typically a type that contains a collection of messages,
1047 i.e. ASL_TYPE_LIST, ASL_TYPE_FILE, ASL_TYPE_STORE, or ASL_TYPE_CLIENT
1048 (where the collection is the system ASL database).
1052 object to the end of the target
1057 is of type ASL_TYPE_LIST and
1059 is of type ASL_TYPE_LIST, ASL_TYPE_FILE, ASL_TYPE_STORE, or ASL_TYPE_CLIENT,
1060 the each message in the
1062 list is appended in sequence to the the target
1069 are of type ASL_TYPE_MSG or ASL_TYPE_QUERY, then the message dictionary from
1076 For keys that are in
1080 the key and its value and operation are added to
1091 object is prepended to the target
1093 In the case where both parameters are of type ASL_TYPE_MSG or ASL_TYPE_QUERY,
1098 Existing keys are not preserved.
1103 returns the next item in the target
1105 which may be of type ASL_TYPE_LIST, ASL_TYPE_FILE, ASL_TYPE_STORE, or of type ASL_TYPE_CLIENT
1106 in which case the routine fetches messages consecutively from the system ASL database.
1107 Returned objects are of type ASL_TYPE_MSG, or of type ASL_TYPE_QUERY if the target object is a
1108 list containing query objects.
1109 Returns NULL when there are no more objects to return from the target.
1116 except that it returns objects in reverse order.
1117 Objects that contain messages have an internal index for the
1123 simply return the current item and move the index forward or backward.
1124 The index position can be set using
1125 .Fn asl_reset_iteration .
1127 .Fo asl_reset_iteration
1131 sets the current position index used be
1137 may be zero to set the position index for
1139 at the beginning of its contents,
1140 or it may be SIZE_MAX to set the position index for
1142 at the end of its contents.
1143 For objects of type ASL_TYPE_LIST, the position index is an actual index into the list.
1144 For other message containing objects, the index is an ID number which may not be sequential.
1150 returns the object at position
1154 object, which must be of type ASL_TYPE_LIST.
1155 Returns NULL if the index is out of range or if
1159 .Fo asl_remove_index
1163 removes the object at position
1167 object, which must be of type ASL_TYPE_LIST.
1169 .Fo asl_log_descriptor
1176 provides functionality to use file descriptors to send logging data to ASL.
1178 is retained by ASL and must still be closed by the caller by calling
1180 if the caller loses reference to it.
1182 is copied by ASL and similarly must still be releaser by the caller by calling
1184 if the caller loses reference to it. Any changes made to it after calling
1185 .Fn asl_log_descriptor()
1186 are not applicable to the message used.
1187 .Ar descriptor is treated differently based on the value of
1192 is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read access. ASL
1195 to read from the descriptor as data becomes available. These data are line
1196 buffered and passed to
1198 When EOF is read, ASL will
1204 is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new writable
1205 descriptor is created with the same fileno. Any data written to this new
1206 descriptor are line buffered and passed to
1208 When EOF is sent, no further data are read. The caller is responsible for
1209 closing the new descriptor. One common use for this API is to redirect writes
1210 to stdout or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as
1217 searches messages in the
1219 object for messages that match the keys and values in
1221 subject to matching operations associated with those keys and values.
1222 The return returns an object of type ASL_TYPE_LIST containing matching messages,
1223 or NULL if no matches are found.
1226 argument should be constructed using
1230 section for details on constructing queries.
1234 parameter may be any ASL object.
1235 For type ASL_TYPE_CLIENT, the main ASL system database is searched.
1236 If the object type is ASL_TYPE_STORE or ASL_TYPE_FILE,
1237 then the corresponding data store or data file is searched.
1238 For ASL_TYPE_LIST, matches are found in a message list.
1241 is of type ASL_TYPE_MSG and query is of type ASL_TYPE_QUERY,
1243 is matched against the query,
1244 and a list containing
1246 is returned if the match succeeds.
1251 are objects of type ASL_TYPE_MSG or both are of type ASL_TYPE_QUERY,
1252 they are tested for exact match.
1255 is returned if the match is exact.
1258 is of type ASL_TYPE_QUERY and
1260 is of type ASL_TYPE_MSG, the routine returns NULL.
1273 but allows more advanced searching of ASL objects.
1276 parameter may be of any type, as with
1280 parameter must be an object of type ASL_TYPE_LIST,
1281 containing zero or more objects of type ASL_TYPE_QUERY.
1284 or a list containing zero objects matches all messages in the target
1287 The caller may provide a starting ASL message ID, a direction, and a count.
1290 ID value of 0 means that matching should commence at the beginning of the target
1292 A value of SIZE_MAX indicates that matching should commence at the end (most recent message)
1296 value is supplied, the routine will return when it has found that many messages,
1297 or it has checked all messages.
1300 is supplied, the routine will return after the specified time (in microseconds).
1305 are non-zero, the routine will return when the desired number of items has been matched
1306 or when the specified duration has been exceeded, whichever occurs first.
1307 The search direction may be ASL_MATCH_DIRECTION_FORWARD or ASL_MATCH_DIRECTION_REVERSE.
1308 The routine sets the value of the out parameter
1310 to be an index of the last message checked while matching.
1311 To fetch matching messages in batches (using a small count or duration value), the
1313 value for each iteration should be set to
1315 + 1 if searching forward, or
1317 - 1 for reverse search.
1320 .Fo aslresponse_next
1323 This interface is deprecated in favor of
1325 It is implemented as a call to
1329 .Fo aslresponse_free
1332 This interface is deprecated in favor of
1334 It is implemented as a call to
1337 .Fo asl_create_auxiliary_file
1343 Creates an auxiliary file that may be used by the client to save arbitrary data.
1344 When the file is closed using
1345 .Fo asl_close_auxiliary_file
1348 will log the specified
1352 and the Uniform Type Identifier provided by
1354 If a NULL value is supplied for
1361 application will display the message with a link to the file.
1363 Auxiliary files are saved in the ASL data store.
1364 They are automatically deleted at the same time that the log message expires.
1365 Messages expire in 7 days by default.
1366 A value set for the ASLExpireTime key will override the default.
1367 Read access for the auxiliary file will be the same as read access for
1369 By default, messages (and auxiliary files) are world-readable.
1370 Access may be limited by setting values for the ReadUID and ReadGID keys.
1372 .Fo asl_close_auxiliary_file
1375 closes the file descriptor
1377 previously returned by a call to
1378 .Fn asl_create_auxiliary_file .
1380 .Fo asl_log_auxiliary_location
1386 will log the specified
1390 the Uniform Type Identifier provided by
1392 and the Uniform Resource Locator provided by
1396 application will display the message with a link to the file.
1397 This allows a client to save data in an auxiliary file, but unlike
1398 .Fn asl_create_auxiliary_file ,
1399 the life-cycle of this file must be managed by some external system.
1400 The file will not be removed when the corresponding log message expired from the ASL data store.
1402 .Fo asl_open_from_file
1407 creates a client handle for an open file descriptor
1409 This routine may be used in conjunction with
1410 .Fn asl_create_auxiliary_file
1412 .Fn asl_log_auxiliary_location
1413 to save ASL format log messages in an auxiliary file.
1415 .Dq com.apple.asl-file
1416 should be used for ASL format auxiliary files.
1418 Files with this format may be read from the command line using
1419 .Nm syslog Fl f Ar file ,
1424 The file must be open for read and write access.
1425 The file will be truncated and its existing contents will be lost.
1428 must be called to close the client handle when logging to this file is complete.
1429 The file should be closed using
1430 .Fo asl_close_auxiliary_file
1432 if it was returned by
1433 .Fo asl_create_auxiliary_file
1440 The client handle returned by
1441 .Fn asl_open_from_file
1442 contains an internal lock, and may be used safely by multiple threads or from independent dispatch queues.
1443 Note that callers will contend for the internal lock when saving log messages to a file.
1445 Note that messages with ReadUID or ReadGID values will simply be saved to the file,
1446 and will not effect read access to either the message or the file itself.
1447 Similarly, messages with ASLExpireTime values will be saved, but will not effect the
1448 life-cycle of either the individual messages or the file.
1450 .Fo asl_encode_buffer
1454 is a utility routine for encoding arbitrary data buffers.
1455 ASL message dictionary keys and values are nul-terminated C strings.
1456 If an application wishes to include arbitrary data which may contain zero bytes,
1457 the data buffer must first be encoded in a manner that eliminates any embedded zeros.
1459 .Fn asl_encode_buffer
1460 routine will encode an arbitrary data buffer at the address
1464 bytes (octets) of data.
1465 The output of the routine is a nul-terminated C string.
1466 The encoded string may be decoded using the companion
1467 .Fn asl_decode_buffer
1470 This utility is used by the ASL server
1472 to encode the value associated with ASL_KEY_AUX_DATA in an ASL_TYPE_MSG object.
1473 An ASL_KEY_AUX_DATA key/value pair is used to hold the data written to a file descriptor
1475 .Fn asl_create_auxiliary_file
1476 on iOS systems, where the ASL database is stored in memory.
1478 .Fo asl_decode_buffer
1483 decodes a C string previously created by
1484 .Fn asl_encode_buffer
1485 back into a buffer, possibly containing embedded zero bytes (octets).
1486 The routine allocates memory for the buffer and returns a pointer in an output
1489 The caller is responsible for freeing the buffer.
1491 This routine should be used to decode the value associated with an
1492 ASL_KEY_AUX_DATA key in an ASL_TYPE_MSG object.
1495 At the core of this API is the asl_object_t structure.
1496 Although the structure is opaque and may not be directly manipulated,
1497 it contains a list of key/value pairs.
1498 All keys and values are NUL-character terminated C language strings.
1499 UTF-8 encoding may be used for non-ASCII characters.
1501 Message structures are generally used to send log messages,
1502 and are created thusly:
1504 asl_object_t m = asl_new(ASL_TYPE_MSG);
1506 Another message type, ASL_TYPE_QUERY,
1507 is used to create queries when searching the data store.
1508 Query type messages and searching are described in detail in the
1511 For the remainder of this section,
1512 the messages described will be of the ASL_TYPE_MSG variety.
1514 Each asl_object_t contains a default set of keys
1515 and values that are associated with them.
1516 These keys are listed in the asl.h header file.
1519 #define ASL_KEY_TIME "Time"
1520 #define ASL_KEY_HOST "Host"
1521 #define ASL_KEY_SENDER "Sender"
1522 #define ASL_KEY_FACILITY "Facility"
1523 #define ASL_KEY_PID "PID"
1524 #define ASL_KEY_UID "UID"
1525 #define ASL_KEY_GID "GID"
1526 #define ASL_KEY_LEVEL "Level"
1527 #define ASL_KEY_MSG "Message"
1529 Many of these correspond to equivalent parts of messages described in the
1532 Values associated with these message keys are assigned appropriate defaults.
1533 The value for ASL_KEY_HOST is the local host name,
1534 the value associated with ASL_KEY_SENDER is the process name,
1535 the ASL_KEY_PID is the client's process ID number, and so on.
1537 Note the addition of the UID and GID keys.
1538 The values for UID and GID are set in library code by the message sender.
1539 The server will attempt to confirm the values,
1540 but no claim is made that these values cannot be maliciously overridden
1541 in an attempt to deceive a log message reader
1542 as to the identity of the sender of a message.
1543 The contents of log messages must be regarded as insecure.
1547 API does not require a process to choose a facility name.
1550 server will use a default value of
1552 if a facility is not set.
1553 However, a client may set a facility name as an argument in the
1555 call, or by setting a specific value for the ASL_KEY_FACILITY in a message:
1557 asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");
1559 An application may choose any facility name at will.
1560 Different facility names may be attached to different messages, perhaps to distinguish different subsystems in log messages.
1561 Developers are encouraged to adopt a
1563 naming convention to avoid conflicting facility names.
1565 Default values are set in the message for each of the keys listed above,
1566 except for ASL_KEY_MSG,
1567 which may be explicitly set at any time using the
1569 routine, or implicitly set at the time the message is sent using the
1570 .Fn asl_log_message ,
1575 These three routines also have an integer-level parameter
1576 for specifying the log priority.
1577 The ASL_KEY_LEVEL value is set accordingly.
1578 Finally, the value associated with ASL_KEY_TIME
1579 is set in the sending routine.
1581 When logging from multiple threads,
1584 open a separate client handle using
1586 The client handle may then be closed when it is no longer required using
1588 Multiple threads may log messages safely using a NULL asl_object_t argument,
1589 but the library will use an internal lock, so that in fact only one thread
1592 When an application requires additional keys and values
1593 to be associated with each log message,
1594 a single message structure may be allocated and set up as
1598 asl_object_t m = asl_new(ASL_TYPE_MSG);
1599 asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us");
1600 asl_set(m, "Clearance", "Top Secret");
1602 asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One");
1604 asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two");
1606 The message structure will carry the values set for the
1610 keys so that they are used in each call to
1612 while the log level and the message text
1613 are taken from the calling parameters.
1625 which is replaced by the current error message
1626 (as denoted by the global variable
1631 Key/value pairs may be removed from a message structure with
1633 A message may be freed using
1642 to transmit a message to the server.
1643 This routine sets the value associated with ASL_KEY_TIME
1644 and sends the message.
1645 It may be called directly if all of a message's key/value pairs
1646 have been created using
1649 Messages that are sent to the
1651 server may be saved in a message store.
1652 The store may be searched using
1655 By default, all messages are readable by any user.
1656 However, some applications may wish to restrict read access
1658 To accommodate this,
1659 a client may set a value for the "ReadUID" and "ReadGID" keys.
1660 These keys may be associated with a value
1661 containing an ASCII representation of a numeric UID or GID.
1662 Only the root user (UID 0),
1663 the user with the given UID,
1664 or a member of the group with the given GID
1665 may fetch access-controlled messages from the database.
1667 Although the ASL system does not require a "Facility" key in a message,
1668 many processes specify a "Facility" value similar
1669 to the common usage of the BSD
1671 API, although developers are encouraged to adopt facility names that make sense for their application.
1674 naming convention (e.g. "com.apple.system.syslog") should be adopted to avoid conflicting names.
1675 The ASL system generally allows any string to be used as a facility value,
1677 The value "com.apple.system",
1678 or any string that has "com.apple.system" as a prefix,
1679 may only be used by processes running with the UID 0.
1680 This allows system processes to log messages that can not be "spoofed" by user processes.
1681 Non-UID 0 client processes that specify "com.apple.system" as a facility, will be assigned the value "user"
1686 A client handle contains various parameters and control settings that are used when a message is logged.
1687 This includes an identification string, a facility name, filtering controls, additional file descriptors, and other data.
1688 Client handles are not thread-safe.
1689 Applications that log from multiple threads should create a client handle for each thread.
1691 Applications that use libdispatch must also avoid using a single client handle from multiple dispatch queues if those queues may run concurrently.
1692 A good approach is to create one or more serial dispatch queues specifically for logging.
1693 Each such queue should use its own ASL client handle.
1695 If a single handle must be accessed by multiple dispatch queues,
1696 then the application must use locks, semaphores, or some other mechanism to prevent concurrent access to a client handle.
1698 A NULL value may be used in any of the routines
1699 that require an asl_object_t argument.
1700 In this case, the library will use an internal client handle.
1701 This internal handle contains its own lock, allowing multiple threads to safely use the NULL client handle.
1702 Note, however, that contention for the lock may cause undesirable synchronization behavior or reduced performance.
1706 routine may be given an ident argument,
1707 which becomes the default value for the ASL_KEY_SENDER key,
1708 and a facility argument,
1709 which becomes the value associated with the ASL_KEY_FACILITY key.
1710 If NULL is passed as the value for
1712 the name of the currently running program will be used.
1713 If NULL is passed as the value for
1717 will be used for non UID 0 processes, and
1720 will be used for UID 0 processes.
1722 Several options are available when creating a client handle.
1725 .Bl -tag -width "ASL_OPT_NO_REMOTE" -compact
1727 adds stderr as an output file descriptor
1728 .It ASL_OPT_NO_DELAY
1729 connects to the server immediately
1730 .It ASL_OPT_NO_REMOTE
1731 disables remote-control filter adjustment
1734 See the FILTERING section below, and the
1736 for additional details on filter controls.
1738 A client handle is closed and its resources released using
1740 Note that if additional file descriptors were added to the handle,
1741 either using the ASL_OPT_STDERR option
1742 or afterwards with the
1743 .Fn asl_add_log_file
1744 routine, those file descriptors are not closed by
1746 .Ss LOGGING TO ADDITIONAL FILES
1747 If a client handle is opened with the ASL_OPT_STDERR option to
1749 a copy of each log message will be sent to stderr.
1750 Additional output streams may be include using
1751 .Fn asl_add_log_file .
1753 Messages sent to stderr or other files are printed in the "standard" message format
1754 also used as a default format by the
1756 command line utility.
1757 Non-ASCII characters in a message are encoded using the
1759 encoding style used by
1764 Backspace characters are printed as ^H.
1765 Carriage returns are mapped to newlines.
1766 A tab character is appended after newlines so that message text is indented.
1768 File descriptors may be removed from the list of outputs associated
1769 with a client handle with
1770 .Fn asl_remove_log_file .
1771 This routine simply removes the file descriptor from the output list.
1772 The file is not closed as a result.
1774 The ASL_OPT_STDERR option may not be unset
1775 after a client handle has been opened.
1779 server archives received messages in a data store
1780 that may be searched using the
1786 A query message is created using:
1788 asl_object_t q = asl_new(ASL_TYPE_QUERY);
1790 Search settings are made in the query using
1792 A search is performed on the data store with
1794 It returns an object of type ASL_TYPE_LIST.
1795 The caller may use routines that operate on lists, such as
1800 to access the matching messages.
1802 Like other messages, ASL_TYPE_QUERY messages contain keys and values.
1803 They also associate an operation with each key and value.
1804 The operation is used to decide if a message matches the query.
1805 The simplest operation is ASL_QUERY_OP_EQUAL, which tests for equality.
1806 For example, the following code snippet searches for messages
1807 with a Sender value equal to
1811 q = asl_new(ASL_TYPE_QUERY);
1812 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
1813 r = asl_search(NULL, q);
1815 More complex searches may be performed using other query operations.
1817 .Bl -tag -width "ASL_QUERY_OP_GREATER_EQUAL" -compact
1818 .It ASL_QUERY_OP_EQUAL
1820 .It ASL_QUERY_OP_GREATER
1822 .It ASL_QUERY_OP_GREATER_EQUAL
1823 value greater than or equal to
1824 .It ASL_QUERY_OP_LESS
1826 .It ASL_QUERY_OP_LESS_EQUAL
1827 value less than or equal to
1828 .It ASL_QUERY_OP_NOT_EQUAL
1830 .It ASL_QUERY_OP_REGEX
1831 regular expression search
1832 .It ASL_QUERY_OP_TRUE
1833 always true - use to test for the existence of a key
1836 Regular expression search uses
1839 Patterns are compiled using the REG_EXTENDED and REG_NOSUB options.
1841 Modifiers that change the behavior of these operations
1842 may also be specified by ORing the modifier value with the operation.
1845 .Bl -tag -width "ASL_QUERY_OP_SUBSTRING" -compact
1846 .It ASL_QUERY_OP_CASEFOLD
1847 string comparisons are case-folded
1848 .It ASL_QUERY_OP_PREFIX
1849 match a leading substring
1850 .It ASL_QUERY_OP_SUFFIX
1851 match a trailing substring
1852 .It ASL_QUERY_OP_SUBSTRING
1854 .It ASL_QUERY_OP_NUMERIC
1855 values are converted to integer using
1859 The only modifier that is checked
1860 for ASL_QUERY_OP_REGEX search is ASL_QUERY_OP_CASEFOLD.
1861 This causes the regular expression to be compiled
1862 with the REG_ICASE option.
1864 If a query message contains more than one set of key/value/operation triples,
1865 the result will be a logical AND. For example, to find messages from
1867 with a priority level less than or equal to
1871 q = asl_new(ASL_TYPE_QUERY);
1872 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
1873 asl_set_query(q, ASL_KEY_LEVEL, "3",
1874 ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC);
1875 r = asl_search(NULL, q);
1879 to get a list of matching messages, one can use
1881 to iterate through the list, and
1882 .Fn asl_fetch_key_val_op
1883 To iterate through the message dictionary.
1888 r = asl_search(NULL, q);
1889 while (NULL != (m = asl_next(r)))
1893 for (i = 0; i < n; i++)
1895 const char *key, *val;
1896 asl_fetch_key_val_op(m, i, key, val, NULL);
1902 .Ss FILTERING AND REMOTE CONTROL
1903 Clients may set a filter mask value with
1904 .Fn asl_set_filter .
1905 The mask specifies which messages should be sent to the
1907 daemon by specifying a yes/no setting for each priority level.
1908 Clients typically set a filter mask
1909 to avoid sending relatively unimportant messages.
1910 For example, Debug or Info priority level messages
1911 are generally only useful for debugging operations.
1912 By setting a filter mask, a process can improve performance
1913 by avoiding sending messages that are in most cases unnecessary.
1915 .Fn asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the routine was called.
1917 As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(level)
1918 may be used to construct a bit mask corresponding to a given priority level,
1919 or corresponding to a bit mask for all priority levels
1920 from ASL_LEVEL_EMERG to a given input level.
1922 The default filter mask is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
1923 This means that by default,
1924 and in the absence of remote-control changes (described below),
1925 ASL_LEVEL_DEBUG and ASL_LEVEL_INFO priority level messages
1930 Three different filters exist for each application.
1931 The first is the filter mask set using
1934 The Apple System Log facility also manages a
1937 The master filter mask usually has a value
1938 that indicates to the library that it is
1940 and thus it has no effect.
1941 However, the mask filter mask may be enabled
1942 by giving it a value using the
1947 When the master filter mask has been set,
1948 it takes precedence over the client's filter mask.
1949 The client's mask is unmodified,
1950 and will become active again if remote-control filtering is disabled.
1952 In addition to the master filter mask,
1953 The Apple System Log facility
1954 also manages a per-client remote-control filter mask.
1955 Like the master filter mask, the per-client mask is usually
1957 having no effect on a client.
1958 If a per-client filter mask is set using the
1962 option, then it takes precedence
1963 over both the client's filter mask and the master filter mask.
1964 As is the case with the master filter mask,
1965 a per-client mask ceases having any effect when if is disabled.
1967 The ASL_OPT_NO_REMOTE option to
1969 causes both the master and per-client remote-control masks
1970 to be ignored in the library.
1971 In that case, only the client's own filter mask
1972 is used to determine which messages are sent to the server.
1973 This may be useful for Applications that produce log messages
1974 that should never be filtered, due to security considerations.
1975 Note that root (administrator) access is required
1976 to set or change the master filter mask,
1977 and that only root may change a per-client remote-control filter mask
1978 for a root (UID 0) process.
1980 The per-process remote control filter value is kept as a state value
1981 associated with a key managed by
1983 The key is protected by an access control mechanism that only permits the
1984 filter value to be accessed and modified by the same effective UID as the
1985 ASL client at the time that the first ASL connection was created.
1986 Remote filter control using
1988 will fail for processes that change effective UID after starting an ASL connection.
1989 Those processes should close all ASL client handles and then re-open ASL connections
1990 if remote filter control support is desired.
1992 These functions first appeared in
projects / apple / syslog.git / blob