1 .\" Copyright (c) 2005-2011 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 ,
35 .Nm asl_close_auxiliary_file ,
36 .Nm asl_create_auxiliary_file ,
41 .Nm asl_log_auxiliary_location ,
42 .Nm asl_log_descriptor ,
45 .Nm asl_open_from_file ,
46 .Nm asl_remove_log_file ,
54 .Nm aslresponse_free ,
56 .Nd system log message sending and searching functions
70 .Fo asl_close_auxiliary_file
74 .Fo asl_create_auxiliary_file
76 .Fa "const char *title"
78 .Fa "int *out_descriptor"
99 .Fa "const char *format"
103 .Fo asl_log_auxiliary_location
105 .Fa "const char *title"
106 .Fa "const char *uti"
107 .Fa "const char *url"
110 .Fo asl_log_descriptor
115 .Fa "uint32_t fd_type"
123 .Fa "const char *ident"
124 .Fa "const char *facility"
128 .Fo asl_open_from_file
130 .Fa "const char *ident"
131 .Fa "const char *facility"
134 .Fo asl_remove_log_file
151 .Fa "const char *key"
152 .Fa "const char *value"
162 .Fa "const char *key"
163 .Fa "const char *value"
169 .Fa "const char *key"
176 .Fa "const char *format"
188 These routines provide an interface to the Apple System Log facility.
189 They are intended to be a replacement for the
191 API, which will continue to be supported for backwards compatibility.
192 The new API allows client applications
193 to create flexible, structured messages and send them to the
195 server, where they may undergo additional processing.
196 Messages received by the server are saved in a data store
197 (subject to input filtering constraints).
198 This API permits clients to create queries
199 and search the message data store for matching messages.
201 An introduction to the concepts underlying this interface follows the interface summary below.
202 .Ss INTERFACE SUMMARY
208 creates and returns a client handle, or NULL if an error occurs in the library.
209 Messages sent using this handle will default to having the string
211 as the value associated with the ASL_KEY_SENDER key, and the value
213 associated with the ASL_KEY_FACILITY key.
214 Several options are available, as described in the
218 Multi-threaded applications should create one client handle for each thread that logs messages.
219 A client may use NULL as a client handle, in which case a default handle managed by the library will be used.
220 A NULL handle may be used safely by multiple threads, but the threads will contend for a single internal lock when
221 sending log messages using a NULL handle.
226 closes the client handle
228 and releases its associated resources.
234 adds the file descriptor
236 to the a set of file descriptors associated with the client handle
238 Each log message sent by that client handle is also written to these file descriptors.
239 Returns 0 on success, non-zero on failure.
241 .Fo asl_remove_log_file
245 removes a file descriptor from the set of file descriptors associated with a client handle.
246 Returns 0 on success, non-zero on failure.
251 allocates and returns an aslmsg structure, or NULL in the case of a failure in the library.
254 argument must be ASL_TYPE_MSG or ASL_TYPE_QUERY.
259 frees an aslmsg and releases resources associated with the structure.
266 creates a new key and value in an aslmsg structure, or replaces the value of an existing key.
267 Returns 0 on success, non-zero on failure.
275 is used to construct searches.
278 except that it takes an additional
280 (operation) argument.
281 Creates a new (key, op, value) triple in an aslmsg structure,
282 or replaces the value and operation for an existing key.
285 section for more information.
286 Returns 0 on success, non-zero on failure.
292 removes a key and its associated value from an aslmsg structure.
293 Returns 0 on success, non-zero on failure.
299 returns the nth key in an aslmsg (beginning at zero),
300 allowing an application to iterate through the keys.
303 indexes beyond the number of keys in
310 returns the value associated with
323 sets a filter for messages being sent to the server.
324 The filter is a bitmask representing priority levels.
325 Only messages having a priority level with a corresponding bit set in the filter mask are sent to the
328 The filter does not control writes to additional files associated with the client handle using
329 .Fn asl_add_log_file .
330 Returns the previous filter value.
339 sends a log to the server (subject to filtering, see
341 above) and to any file descriptors associated with the client handle
345 argument may contain any keys and values, which will be formatted as part of the log message.
346 The value for ASL_KEY_LEVEL is supplied by the
349 The value for ASL_KEY_MESSAGE is computed from
351 and the associated arguments
355 style argument processing is applied to the format and the arguments.
356 The format may also contain
358 which will be substituted with the string value corresponding to the current
361 The ASL_PREFILTER_LOG(asl, msg, level, format, ...) macro may be used in
364 The macro avoids processing the variable argument list in those cases where
365 the message would be filtered out due to filter settings, would not be
366 written to a log file associated with the aslclient, or would not be
368 The macro may provide a performance benefit for some applications.
369 Details on filter setting, additional log files, and aslclient options
370 are described below in this manual.
381 except that it takes a va_list argument.
389 exceopt the value for ASL_KEY_MESSAGE is taken from
391 rather than being constructed using a
395 .Fo asl_log_descriptor
402 provides functionality to use file descriptors to send logging data to ASL.
404 is retained by ASL and must still be closed by the caller by calling
406 if the caller loses reference to it.
408 is copied by ASL and similarly must still be freed by the caller by calling
410 if the caller loses reference to it. Any changes made to it after calling
411 .Fn asl_log_descriptor()
412 are not applicable to the message used.
413 .Ar descriptor is treated differentlty based on the value of
418 is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read access. ASL
421 to read from the descriptor as data becomes available. These data are line
422 buffered and passed to
424 When EOF is read, ASL will
430 is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new writable
431 descriptor is created with the same fileno. Any data written to this new
432 descriptor are line buffered and passed to
434 When EOF is sent, no further data are read. The caller is responsible for
435 closing the new descriptor. One common use for this API is to redirect writes
436 to stdout or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as
443 searches for messages that match the keys and values in
445 subject to matching operations associated with those keys and values.
448 argument should be constructed using
452 section for details on constructing queries.
453 Returns an aslresponse structure that contains matching log messages.
454 NULL is returned in case of error or if there are no matching messages in the ASL database.
459 iterates over an aslresponse structure returned by
461 Each call returns the next aslmsg in the response.
462 Returns NULL when there are no further messages.
467 frees the aslresponse structure
469 and all of its associated resources.
471 .Fo asl_create_auxiliary_file
477 Creates an auxiliary file that may be used by the client to save arbitrary data.
478 When the file is closed using
479 .Fo asl_close_auxiliary_file
482 will log the specified
486 and the Uniform Type Identifier provided by
488 If a NULL value is supplied for
495 application will display the message with a link to the file.
497 Auxiliary files are saved in the ASL data store.
498 They are automatically deleted at the same time that the log message expires.
499 Messages expire in 7 days by default.
500 A value set for the ASLExpireTime key will override the default.
501 Read access for the auxiliary file will be the same as read access for
503 By default, messages (and auxiliary files) are world-readable.
504 Access may be limited by setting values for the ReadUID and ReadGID keys.
506 .Fo asl_close_auxiliary_file
509 closes the file descriptor
511 previously returned by a call to
512 .Fn asl_create_auxiliary_file .
514 .Fo asl_log_auxiliary_location
520 will log the specified
524 the Uniform Type Identifier provided by
526 and the Uniform Resource Locator provided by
530 application will display the message with a link to the file.
531 This allows a client to save data in an auxiliary file, but unlike
532 .Fo asl_create_auxiliary_file
534 the life-cycle of this file must be managed by some external system.
535 The file will not be removed when the corresponding log message expired from the ASL data store.
537 .Fo asl_open_from_file
542 creates a client handle for an open file descriptor
544 This routine may be used in conjunction with
545 .Fo asl_create_auxiliary_file
548 .Fo asl_log_auxiliary_location
550 to save ASL format log messages in an auxiliary file.
552 .Dq com.apple.asl-file
553 should be used for ASL format auxiliary files.
555 Files with this format may be read from the command line using
556 .Nm syslog Fl f Ar file ,
561 The file must be open for read and write access.
562 The file will be truncated and its existing contents will be lost.
565 must be called to close the client handle when logging to this file is complete.
566 The file should be closed using
567 .Fo asl_close_auxiliary_file
569 if it was returned by
570 .Fo asl_create_auxiliary_file
577 The client handle may be used safely by multiple threads.
578 The threads will contend for a single internal lock when saving log messages to a file.
580 Note that messages with ReadUID or ReadGID values will simply be saved to the file,
581 and will not effect read access to either the message or the file itself.
582 Similarly, messages with ASLExpireTime values will be saved, but will not effect the
583 life-cycle of either the individual messages or the file.
585 At the core of this API is the aslmsg structure.
586 Although the structure is opaque and may not be directly manipulated,
587 it contains a list of key/value pairs.
588 All keys and values are NUL-character terminated C language strings.
589 UTF-8 encoding may be used for non-ASCII characters.
591 Message structures are generally used to send log messages,
592 and are created thusly:
594 aslmsg m = asl_new(ASL_TYPE_MSG);
596 Another message type, ASL_TYPE_QUERY,
597 is used to create queries when searching the data store.
598 Query type messages and searching are described in detail in the
601 For the remainder of this section,
602 the messages described will be of the ASL_TYPE_MSG variety.
604 Each aslmsg contains a default set of keys
605 and values that are associated with them.
606 These keys are listed in the asl.h header file.
609 #define ASL_KEY_TIME "Time"
610 #define ASL_KEY_HOST "Host"
611 #define ASL_KEY_SENDER "Sender"
612 #define ASL_KEY_FACILITY "Facility"
613 #define ASL_KEY_PID "PID"
614 #define ASL_KEY_UID "UID"
615 #define ASL_KEY_GID "GID"
616 #define ASL_KEY_LEVEL "Level"
617 #define ASL_KEY_MSG "Message"
619 Many of these correspond to equivalent parts of messages described in the
622 Values associated with these message keys are assigned appropriate defaults.
623 The value for ASL_KEY_HOST is the local host name,
624 the value associated with ASL_KEY_SENDER is the process name,
625 the ASL_KEY_PID is the client's process ID number, and so on.
627 Note the addition of the UID and GID keys.
628 The values for UID and GID are set in library code by the message sender.
629 The server will attempt to confirm the values,
630 but no claim is made that these values cannot be maliciously overridden
631 in an attempt to deceive a log message reader
632 as to the identity of the sender of a message.
633 The contents of log messages must be regarded as insecure.
637 API does not require a process to choose a facility name.
640 server will use a default value of
642 if a facility is not set.
643 However, a client may set a facility name as an argument in the
645 call, or by setting a specific value for the ASL_KEY_FACILITY in a message:
647 asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");
649 An application may choose any facility name at will.
650 Different facility names may be attached to different messages, perhaps to distinguish different subsystems in log messages.
651 Developers are encouraged to adopt a
653 naming convention to avoid conflicting facility names.
655 Default values are set in the message for each of the keys listed above,
656 except for ASL_KEY_MSG,
657 which may be explicitly set at any time using the
659 routine, or implicitly set at the time the message is sent using the
664 These two routines also have an integer-level parameter
665 for specifying the log priority.
666 The ASL_KEY_LEVEL value is set accordingly.
667 Finally, the value associated with ASL_KEY_TIME
668 is set in the sending routine.
670 Although it may appear that there is significant overhead required
671 to send a log message using this API,
672 the opposite is actually true.
675 program requires only:
679 asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!");
685 will provide the appropriate default values
686 when passed a NULL aslmsg argument.
689 In this example, the aslclient argument is NULL.
690 This is sufficient for a single-threaded application,
691 or for an application which only sends log messages from a single thread.
692 When logging from multiple threads,
695 open a separate client handle using
697 The client handle may then be closed when it is no longer required using
699 Multiple threads may log messages safely using a NULL aslclient argument,
700 but the library will use an internal lock, so that in fact only one thread
703 When an application requires additional keys and values
704 to be associated with each log message,
705 a single message structure may be allocated and set up as
709 aslmsg m = asl_new(ASL_TYPE_MSG);
710 asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us");
711 asl_set(m, "Clearance", "Top Secret");
713 asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One");
715 asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two");
717 The message structure will carry the values set for the
721 keys so that they are used in each call to
723 while the log level and the message text
724 are taken from the calling parameters.
736 which is replaced by the current error message
737 (as denoted by the global variable
742 Key/value pairs may be removed from a message structure with
744 A message may be freed using
753 to transmit a message to the server.
754 This routine sets the value associated with ASL_KEY_TIME
755 and sends the message.
756 It may be called directly if all of a message's key/value pairs
757 have been created using
760 Messages that are sent to the
762 server may be saved in a message store.
763 The store may be searched using
766 By default, all messages are readable by any user.
767 However, some applications may wish to restrict read access
770 a client may set a value for the "ReadUID" and "ReadGID" keys.
771 These keys may be associated with a value
772 containing an ASCII representation of a numeric UID or GID.
773 Only the root user (UID 0),
774 the user with the given UID,
775 or a member of the group with the given GID
776 may fetch access-controlled messages from the database.
778 Although the ASL system does not require a "Facility" key in a message,
779 many processes specify a "Facility" value similar
780 to the common usage of the BSD
782 API, although developers are encouraged to adopt facility names that make sense for their application.
785 naming convention (e.g. "com.apple.system.syslog") should be adopted to avoid conflicting names.
786 The ASL system generally allows any string to be used as a facility value,
788 The value "com.apple.system",
789 or any string that has "com.apple.system" as a prefix,
790 may only be used by processes running with the UID 0.
791 This allows system processes to log messages that can not be "spoofed" by user processes.
792 Non-UID 0 client processes that specify "com.apple.system" as a facility, will be assigned the value "user"
797 When logging is done from a single thread,
798 a NULL value may be used in any of the routines
799 that require an aslclient argument.
800 In this case, the library will open an internal client handle
801 on behalf of the application.
803 If multiple threads must do logging,
804 or if client options are desired,
805 then the application should call
807 to create a client handle for each thread.
811 routine may be given an ident argument,
812 which becomes the default value for the ASL_KEY_SENDER key,
813 and a facility argument,
814 which becomes the value associated with the ASL_KEY_FACILITY key.
816 Several options are available when creating a client handle.
819 .Bl -tag -width "ASL_OPT_NO_REMOTE" -compact
821 adds stderr as an output file descriptor
823 connects to the server immediately
824 .It ASL_OPT_NO_REMOTE
825 disables remote-control filter adjustment
828 ASL_OPT_NO_DELAY makes the client library connect to the
830 server at the time that
832 is called, rather than waiting for the first message to be sent.
833 Opening the connection is quite fast, but some applications may want to avoid any unnecessary delays when calling
839 See the FILTERING section below, and the
841 for additional details on filter controls.
843 A client handle is closed and it's resources released using
845 Note that if additional file descriptors were added to the handle,
846 either using the ASL_OPT_STDERR option
847 or afterwards with the
849 routine, those file descriptors are not closed by
851 .Ss LOGGING TO ADDITIONAL FILES
852 If a client handle is opened with the ASL_OPT_STDERR option to
854 a copy of each log message will be sent to stderr.
855 Additional output streams may be include using
856 .Nm asl_add_log_file .
858 Messages sent to stderr or other files are printed in the "standard" message format
859 also used as a default format by the
861 command line utility.
862 Non-ASCII characters in a message are encoded using the
864 encoding style used by
869 Backspace characters are printed as ^H.
870 Carriage returns are mapped to newlines.
871 A tab character is appended after newlines so that message text is indented.
873 File descriptors may be removed from the list of outputs associated
874 with a client handle with
875 .Nm asl_remove_log_file .
876 This routine simply removes the file descriptor from the output list.
877 The file is not closed as a result.
879 The ASL_OPT_STDERR option may not be unset
880 after a client handle has been opened.
884 server archives received messages in a data store
885 that may be searched using the
887 .Nm aslresponse_next ,
891 A query message is created using:
893 aslmsg q = asl_new(ASL_TYPE_QUERY);
895 Search settings are made in the query using
897 A search is performed on the data store with
902 The caller may then call
904 to iterate through matching messages.
907 structure may be freed with
908 .Nm aslresponse_free .
910 Like other messages, ASL_TYPE_QUERY messages contain keys and values.
911 They also associate an operation with each key and value.
912 The operation is used to decide if a message matches the query.
913 The simplest operation is ASL_QUERY_OP_EQUAL, which tests for equality.
914 For example, the following code snippet searches for messages
915 with a Sender value equal to
920 q = asl_new(ASL_TYPE_QUERY);
921 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
922 r = asl_search(NULL, q);
924 More complex searches may be performed using other query operations.
926 .Bl -tag -width "ASL_QUERY_OP_GREATER_EQUAL" -compact
927 .It ASL_QUERY_OP_EQUAL
929 .It ASL_QUERY_OP_GREATER
931 .It ASL_QUERY_OP_GREATER_EQUAL
932 value greater than or equal to
933 .It ASL_QUERY_OP_LESS
935 .It ASL_QUERY_OP_LESS_EQUAL
936 value less than or equal to
937 .It ASL_QUERY_OP_NOT_EQUAL
939 .It ASL_QUERY_OP_REGEX
940 regular expression search
941 .It ASL_QUERY_OP_TRUE
942 always true - use to test for the existence of a key
945 Regular expression search uses
948 Patterns are compiled using the REG_EXTENDED and REG_NOSUB options.
950 Modifiers that change the behavior of these operations
951 may also be specified by ORing the modifier value with the operation.
954 .Bl -tag -width "ASL_QUERY_OP_SUBSTRING" -compact
955 .It ASL_QUERY_OP_CASEFOLD
956 string comparisons are case-folded
957 .It ASL_QUERY_OP_PREFIX
958 match a leading substring
959 .It ASL_QUERY_OP_SUFFIX
960 match a trailing substring
961 .It ASL_QUERY_OP_SUBSTRING
963 .It ASL_QUERY_OP_NUMERIC
964 values are converted to integer using
968 The only modifier that is checked
969 for ASL_QUERY_OP_REGEX search is ASL_QUERY_OP_CASEFOLD.
970 This causes the regular expression to be compiled
971 with the REG_ICASE option.
973 If a query message contains more than one set of key/value/operation triples,
974 the result will be a logical AND. For example, to find messages from
976 with a priority level less than or equal to
981 q = asl_new(ASL_TYPE_QUERY);
982 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
983 asl_set_query(q, ASL_KEY_LEVEL, "3",
984 ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC);
985 r = asl_search(NULL, q);
993 to iterate through all matching messages.
994 To iterate through the keys and values in a message, use
996 to iterate through the keys, then call
998 to get the value associated with each key.
1002 const char *key, *val;
1005 r = asl_search(NULL, q);
1006 while (NULL != (m = aslresponse_next(r)))
1008 for (i = 0; (NULL != (key = asl_key(m, i))); i++)
1010 val = asl_get(m, key);
1014 aslresponse_free(r);
1016 .Ss FILTERING AND REMOTE CONTROL
1017 Clients may set a filter mask value with
1018 .Nm asl_set_filter .
1019 The mask specifies which messages should be sent to the
1021 daemon by specifying a yes/no setting for each priority level.
1022 Clients typically set a filter mask
1023 to avoid sending relatively unimportant messages.
1024 For example, Debug or Info priority level messages
1025 are generally only useful for debugging operations.
1026 By setting a filter mask, a process can improve performance
1027 by avoiding sending messages that are in most cases unnecessary.
1029 .Nm asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the routine was called.
1031 As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(level)
1032 may be used to construct a bit mask corresponding to a given priority level,
1033 or corresponding to a bit mask for all priority levels
1034 from ASL_LEVEL_EMERG to a given input level.
1036 The default filter mask is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
1037 This means that by default,
1038 and in the absence of remote-control changes (described below),
1039 ASL_LEVEL_DEBUG and ASL_LEVEL_INFO priority level messages
1044 Three different filters exist for each application.
1045 The first is the filter mask set using
1048 The Apple System Log facility also manages a
1051 The master filter mask usually has a value
1052 that indicates to the library that it is
1054 and thus it has no effect.
1055 However, the mask filter mask may be enabled
1056 by giving it a value using the
1061 When the master filter mask has been set,
1062 it takes precedence over the client's filter mask.
1063 The client's mask is unmodified,
1064 and will become active again if remote-control filtering is disabled.
1066 In addition to the master filter mask,
1067 The Apple System Log facility
1068 also manages a per-client remote-control filter mask.
1069 Like the master filter mask, the per-client mask is usually
1071 having no effect on a client.
1072 If a per-client filter mask is set using the
1076 option, then it takes precedence
1077 over both the client's filter mask and the master filter mask.
1078 As is the case with the master filter mask,
1079 a per-client mask ceases having any effect when if is disabled.
1081 The ASL_OPT_NO_REMOTE option to
1083 causes both the master and per-client remote-control masks
1084 to be ignored in the library.
1085 In that case, only the client's own filter mask
1086 is used to determine which messages are sent to the server.
1087 This may be useful for Applications that produce log messages
1088 that should never be filtered, due to security considerations.
1089 Note that root (administrator) access is required
1090 to set or change the master filter mask,
1091 and that only root may change a per-client remote-control filter mask
1092 for a root (UID 0) process.
1094 The per-process remote control filter value is kept as a state value
1095 associated with a key managed by
1097 The key is protected by an access control mechanism that only permits the
1098 filter value to be accessed and modified by the same effective UID as the
1099 ASL client at the time that the first ASL connection was created.
1100 Remote filter control using
1102 will fail for processes that change effective UID after starting an ASL connection.
1103 Those processes should close all ASL client handles and then re-open ASL connections
1104 if remote filter control support is desired.
1106 These functions first appeared in
projects / apple / libc.git / blob