1 .\" Copyright (c) 2005-2010 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 ,
44 .Nm asl_open_from_file ,
45 .Nm asl_remove_log_file ,
53 .Nm aslresponse_free ,
55 .Nd system log message sending and searching functions
69 .Fo asl_close_auxiliary_file
73 .Fo asl_create_auxiliary_file
75 .Fa "const char *title"
98 .Fa "const char *format"
102 .Fo asl_log_auxiliary_location
104 .Fa "const char *title"
105 .Fa "const char *uti"
106 .Fa "const char *url"
114 .Fa "const char *ident"
115 .Fa "const char *facility"
119 .Fo asl_open_from_file
121 .Fa "const char *ident"
122 .Fa "const char *facility"
125 .Fo asl_remove_log_file
142 .Fa "const char *key"
143 .Fa "const char *value"
153 .Fa "const char *key"
154 .Fa "const char *value"
160 .Fa "const char *key"
167 .Fa "const char *format"
179 These routines provide an interface to the Apple System Log facility.
180 They are intended to be a replacement for the
182 API, which will continue to be supported for backwards compatibility.
183 The new API allows client applications
184 to create flexible, structured messages and send them to the
186 server, where they may undergo additional processing.
187 Messages received by the server are saved in a data store
188 (subject to input filtering constraints).
189 This API permits clients to create queries
190 and search the message data store for matching messages.
192 An introduction to the concepts underlying this interface follows the interface summary below.
193 .Ss INTERFACE SUMMARY
199 creates and returns a client handle, or NULL if an error occurs in the library.
200 Messages sent using this handle will default to having the string
202 as the value associated with the ASL_KEY_SENDER key, and the value
204 associated with the ASL_KEY_FACILITY key.
205 Several options are available, as described in the
209 Multi-threaded applications should create one client handle for each thread that logs messages.
210 A client may use NULL as a client handle, in which case a default handle managed by the library will be used.
211 A NULL handle may be used safely by multiple threads, but the threads will contend for a single internal lock when
212 sending log messages using a NULL handle.
217 closes the client handle
219 and releases its associated resources.
225 adds the file descriptor
227 to the a set of file descriptors associated with the client handle
229 Each log message sent by that client handle is also written to these file descriptors.
230 Returns 0 on success, non-zero on failure.
232 .Fo asl_remove_log_file
236 removes a file descriptor from the set of file descriptors associated with a client handle.
237 Returns 0 on success, non-zero on failure.
242 allocates and returns an aslmsg structure, or NULL in the case of a failure in the library.
245 argument must be ASL_TYPE_MSG or ASL_TYPE_QUERY.
250 frees an aslmsg and releases resources associated with the structure.
257 creates a new key and value in an aslmsg structure, or replaces the value of an existing key.
258 Returns 0 on success, non-zero on failure.
266 is used to construct searches.
269 except that it takes an additional
271 (operation) argument.
272 Creates a new (key, op, value) triple in an aslmsg structure,
273 or replaces the value and operation for an existing key.
276 section for more information.
277 Returns 0 on success, non-zero on failure.
283 removes a key and its associated value from an aslmsg structure.
284 Returns 0 on success, non-zero on failure.
290 returns the nth key in an aslmsg (beginning at zero),
291 allowing an application to iterate through the keys.
294 indexes beyond the number of keys in
301 returns the value associated with
314 sets a filter for messages being sent to the server.
315 The filter is a bitmask representing priority levels.
316 Only messages having a priority level with a corresponding bit set in the filter mask are sent to the
319 The filter does not control writes to additional files associated with the client handle using
320 .Fn asl_add_log_file .
321 Returns the previous filter value.
330 sends a log to the server (subject to filtering, see
332 above) and to any file descriptors associated with the client handle
336 argument may contain any keys and values, which will be formatted as part of the log message.
337 The value for ASL_KEY_LEVEL is supplied by the
340 The value for ASL_KEY_MESSAGE is computed from
342 and the associated arguments
346 style argument processing is applied to the format and the arguments.
347 The format may also contain
349 which will be substituted with the string value corresponding to the current
361 except that it takes a va_list argument.
369 exceopt the value for ASL_KEY_MESSAGE is taken from
371 rather than being constructed using a
379 searches for messages that match the keys and values in
381 subject to matching operations associated with those keys and values.
384 argument should be constructed using
388 section for details on constructing queries.
389 Returns an aslresponse structure that contains matching log messages.
390 NULL is returned in case of error or if there are no matching messages in the ASL database.
395 iterates over an aslresponse structure returned by
397 Each call returns the next aslmsg in the response.
398 Returns NULL when there are no further messages.
403 frees the aslresponse structure
405 and all of its associated resources.
407 .Fo asl_create_auxiliary_file
413 Creates an auxiliary file that may be used by the client to save arbitrary data.
414 When the file is closed using
415 .Fo asl_close_auxiliary_file
418 will log the specified
422 and the Uniform Type Identifier provided by
424 If a NULL value is supplied for
431 application will display the message with a link to the file.
433 Auxiliary files are saved in the ASL data store.
434 They are automatically deleted at the same time that the log message expires.
435 Messages expire in 7 days by default.
436 A value set for the ASLExpireTime key will override the default.
437 Read access for the auxiliary file will be the same as read access for
439 By default, messages (and auxiliary files) are world-readable.
440 Access may be limited by setting values for the ReadUID and ReadGID keys.
442 .Fo asl_close_auxiliary_file
445 closes the file descriptor
447 previously returned by a call to
448 .Fn asl_create_auxiliary_file .
450 .Fo asl_log_auxiliary_location
456 will log the specified
460 the Uniform Type Identifier provided by
462 and the Uniform Resource Locator provided by
466 application will display the message with a link to the file.
467 This allows a client to save data in an auxiliary file, but unlike
468 .Fo asl_create_auxiliary_file
470 the life-cycle of this file must be managed by some external system.
471 The file will not be removed when the corresponding log message expired from the ASL data store.
473 .Fo asl_open_from_file
478 creates a client handle for an open file descriptor
480 This routine may be used in conjunction with
481 .Fo asl_create_auxiliary_file
484 .Fo asl_log_auxiliary_location
486 to save ASL format log messages in an auxiliary file.
488 .Dq com.apple.asl-file
489 should be used for ASL format auxiliary files.
491 Files with this format may be read from the command line using
492 .Nm syslog Fl f Ar file ,
497 The file must be open for read and write access.
498 The file will be truncated and its existing contents will be lost.
501 must be called to close the client handle when logging to this file is complete.
502 The file should be closed using
503 .Fo asl_close_auxiliary_file
505 if it was returned by
506 .Fo asl_create_auxiliary_file
513 The client handle may be used safely by multiple threads.
514 The threads will contend for a single internal lock when saving log messages to a file.
516 Note that messages with ReadUID or ReadGID values will simply be saved to the file,
517 and will not effect read access to either the message or the file itself.
518 Similarly, messages with ASLExpireTime values will be saved, but will not effect the
519 life-cycle of either the individual messages or the file.
521 At the core of this API is the aslmsg structure.
522 Although the structure is opaque and may not be directly manipulated,
523 it contains a list of key/value pairs.
524 All keys and values are NUL-character terminated C language strings.
525 UTF-8 encoding may be used for non-ASCII characters.
527 Message structures are generally used to send log messages,
528 and are created thusly:
530 aslmsg m = asl_new(ASL_TYPE_MSG);
532 Another message type, ASL_TYPE_QUERY,
533 is used to create queries when searching the data store.
534 Query type messages and searching are described in detail in the
537 For the remainder of this section,
538 the messages described will be of the ASL_TYPE_MSG variety.
540 Each aslmsg contains a default set of keys
541 and values that are associated with them.
542 These keys are listed in the asl.h header file.
545 #define ASL_KEY_TIME "Time"
546 #define ASL_KEY_HOST "Host"
547 #define ASL_KEY_SENDER "Sender"
548 #define ASL_KEY_FACILITY "Facility"
549 #define ASL_KEY_PID "PID"
550 #define ASL_KEY_UID "UID"
551 #define ASL_KEY_GID "GID"
552 #define ASL_KEY_LEVEL "Level"
553 #define ASL_KEY_MSG "Message"
555 Many of these correspond to equivalent parts of messages described in the
558 Values associated with these message keys are assigned appropriate defaults.
559 The value for ASL_KEY_HOST is the local host name,
560 the value associated with ASL_KEY_SENDER is the process name,
561 the ASL_KEY_PID is the client's process ID number, and so on.
563 Note the addition of the UID and GID keys.
564 The values for UID and GID are set in library code by the message sender.
565 The server will attempt to confirm the values,
566 but no claim is made that these values cannot be maliciously overridden
567 in an attempt to deceive a log message reader
568 as to the identity of the sender of a message.
569 The contents of log messages must be regarded as insecure.
573 API does not require a process to choose a facility name.
576 server will use a default value of
578 if a facility is not set.
579 However, a client may set a facility name as an argument in the
581 call, or by setting a specific value for the ASL_KEY_FACILITY in a message:
583 asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice");
585 An application may choose any facility name at will.
586 Different facility names may be attached to different messages, perhaps to distinguish different subsystems in log messages.
587 Developers are encouraged to adopt a
589 naming convention to avoid conflicting facility names.
591 Default values are set in the message for each of the keys listed above,
592 except for ASL_KEY_MSG,
593 which may be explicitly set at any time using the
595 routine, or implicitly set at the time the message is sent using the
600 These two routines also have an integer-level parameter
601 for specifying the log priority.
602 The ASL_KEY_LEVEL value is set accordingly.
603 Finally, the value associated with ASL_KEY_TIME
604 is set in the sending routine.
606 Although it may appear that there is significant overhead required
607 to send a log message using this API,
608 the opposite is actually true.
611 program requires only:
615 asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!");
621 will provide the appropriate default values
622 when passed a NULL aslmsg argument.
625 In this example, the aslclient argument is NULL.
626 This is sufficient for a single-threaded application,
627 or for an application which only sends log messages from a single thread.
628 When logging from multiple threads,
631 open a separate client handle using
633 The client handle may then be closed when it is no longer required using
635 Multiple threads may log messages safely using a NULL aslclient argument,
636 but the library will use an internal lock, so that in fact only one thread
639 When an application requires additional keys and values
640 to be associated with each log message,
641 a single message structure may be allocated and set up as
645 aslmsg m = asl_new(ASL_TYPE_MSG);
646 asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us");
647 asl_set(m, "Clearance", "Top Secret");
649 asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One");
651 asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two");
653 The message structure will carry the values set for the
657 keys so that they are used in each call to
659 while the log level and the message text
660 are taken from the calling parameters.
672 which is replaced by the current error message
673 (as denoted by the global variable
678 Key/value pairs may be removed from a message structure with
680 A message may be freed using
689 to transmit a message to the server.
690 This routine sets the value associated with ASL_KEY_TIME
691 and sends the message.
692 It may be called directly if all of a message's key/value pairs
693 have been created using
696 Messages that are sent to the
698 server may be saved in a message store.
699 The store may be searched using
702 By default, all messages are readable by any user.
703 However, some applications may wish to restrict read access
706 a client may set a value for the "ReadUID" and "ReadGID" keys.
707 These keys may be associated with a value
708 containing an ASCII representation of a numeric UID or GID.
709 Only the root user (UID 0),
710 the user with the given UID,
711 or a member of the group with the given GID
712 may fetch access-controlled messages from the database.
714 Although the ASL system does not require a "Facility" key in a message,
715 many processes specify a "Facility" value similar
716 to the common usage of the BSD
718 API, although developers are encouraged to adopt facility names that make sense for their application.
721 naming convention (e.g. "com.apple.system.syslog") should be adopted to avoid conflicting names.
722 The ASL system generally allows any string to be used as a facility value,
724 The value "com.apple.system",
725 or any string that has "com.apple.system" as a prefix,
726 may only be used by processes running with the UID 0.
727 This allows system processes to log messages that can not be "spoofed" by user processes.
728 Non-UID 0 client processes that specify "com.apple.system" as a facility, will be assigned the value "user"
733 When logging is done from a single thread,
734 a NULL value may be used in any of the routines
735 that require an aslclient argument.
736 In this case, the library will open an internal client handle
737 on behalf of the application.
739 If multiple threads must do logging,
740 or if client options are desired,
741 then the application should call
743 to create a client handle for each thread.
747 routine may be given an ident argument,
748 which becomes the default value for the ASL_KEY_SENDER key,
749 and a facility argument,
750 which becomes the value associated with the ASL_KEY_FACILITY key.
752 Several options are available when creating a client handle.
755 .Bl -tag -width "ASL_OPT_NO_REMOTE" -compact
757 adds stderr as an output file descriptor
759 connects to the server immediately
760 .It ASL_OPT_NO_REMOTE
761 disables remote-control filter adjustment
764 ASL_OPT_NO_DELAY makes the client library connect to the
766 server at the time that
768 is called, rather than waiting for the first message to be sent.
769 Opening the connection is quite fast, but some applications may want to avoid any unnecessary delays when calling
775 See the FILTERING section below, and the
777 for additional details on filter controls.
779 A client handle is closed and it's resources released using
781 Note that if additional file descriptors were added to the handle,
782 either using the ASL_OPT_STDERR option
783 or afterwards with the
785 routine, those file descriptors are not closed by
787 .Ss LOGGING TO ADDITIONAL FILES
788 If a client handle is opened with the ASL_OPT_STDERR option to
790 a copy of each log message will be sent to stderr.
791 Additional output streams may be include using
792 .Nm asl_add_log_file .
794 Messages sent to stderr or other files are printed in the "standard" message format
795 also used as a default format by the
797 command line utility.
798 Non-ASCII characters in a message are encoded using the
800 encoding style used by
805 Backspace characters are printed as ^H.
806 Carriage returns are mapped to newlines.
807 A tab character is appended after newlines so that message text is indented.
809 File descriptors may be removed from the list of outputs associated
810 with a client handle with
811 .Nm asl_remove_log_file .
812 This routine simply removes the file descriptor from the output list.
813 The file is not closed as a result.
815 The ASL_OPT_STDERR option may not be unset
816 after a client handle has been opened.
820 server archives received messages in a data store
821 that may be searched using the
823 .Nm aslresponse_next ,
827 A query message is created using:
829 aslmsg q = asl_new(ASL_TYPE_QUERY);
831 Search settings are made in the query using
833 A search is performed on the data store with
838 The caller may then call
840 to iterate through matching messages.
843 structure may be freed with
844 .Nm aslresponse_free .
846 Like other messages, ASL_TYPE_QUERY messages contain keys and values.
847 They also associate an operation with each key and value.
848 The operation is used to decide if a message matches the query.
849 The simplest operation is ASL_QUERY_OP_EQUAL, which tests for equality.
850 For example, the following code snippet searches for messages
851 with a Sender value equal to
856 q = asl_new(ASL_TYPE_QUERY);
857 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
858 r = asl_search(NULL, q);
860 More complex searches may be performed using other query operations.
862 .Bl -tag -width "ASL_QUERY_OP_GREATER_EQUAL" -compact
863 .It ASL_QUERY_OP_EQUAL
865 .It ASL_QUERY_OP_GREATER
867 .It ASL_QUERY_OP_GREATER_EQUAL
868 value greater than or equal to
869 .It ASL_QUERY_OP_LESS
871 .It ASL_QUERY_OP_LESS_EQUAL
872 value less than or equal to
873 .It ASL_QUERY_OP_NOT_EQUAL
875 .It ASL_QUERY_OP_REGEX
876 regular expression search
877 .It ASL_QUERY_OP_TRUE
878 always true - use to test for the existence of a key
881 Regular expression search uses
884 Patterns are compiled using the REG_EXTENDED and REG_NOSUB options.
886 Modifiers that change the behavior of these operations
887 may also be specified by ORing the modifier value with the operation.
890 .Bl -tag -width "ASL_QUERY_OP_SUBSTRING" -compact
891 .It ASL_QUERY_OP_CASEFOLD
892 string comparisons are case-folded
893 .It ASL_QUERY_OP_PREFIX
894 match a leading substring
895 .It ASL_QUERY_OP_SUFFIX
896 match a trailing substring
897 .It ASL_QUERY_OP_SUBSTRING
899 .It ASL_QUERY_OP_NUMERIC
900 values are converted to integer using
904 The only modifier that is checked
905 for ASL_QUERY_OP_REGEX search is ASL_QUERY_OP_CASEFOLD.
906 This causes the regular expression to be compiled
907 with the REG_ICASE option.
909 If a query message contains more than one set of key/value/operation triples,
910 the result will be a logical AND. For example, to find messages from
912 with a priority level less than or equal to
917 q = asl_new(ASL_TYPE_QUERY);
918 asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL);
919 asl_set_query(q, ASL_KEY_LEVEL, "3",
920 ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC);
921 r = asl_search(NULL, q);
929 to iterate through all matching messages.
930 To iterate through the keys and values in a message, use
932 to iterate through the keys, then call
934 to get the value associated with each key.
938 const char *key, *val;
941 r = asl_search(NULL, q);
942 while (NULL != (m = aslresponse_next(r)))
944 for (i = 0; (NULL != (key = asl_key(m, i))); i++)
946 val = asl_get(m, key);
952 .Ss FILTERING AND REMOTE CONTROL
953 Clients may set a filter mask value with
955 The mask specifies which messages should be sent to the
957 daemon by specifying a yes/no setting for each priority level.
958 Clients typically set a filter mask
959 to avoid sending relatively unimportant messages.
960 For example, Debug or Info priority level messages
961 are generally only useful for debugging operations.
962 By setting a filter mask, a process can improve performance
963 by avoiding sending messages that are in most cases unnecessary.
965 .Nm asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the routine was called.
967 As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(level)
968 may be used to construct a bit mask corresponding to a given priority level,
969 or corresponding to a bit mask for all priority levels
970 from ASL_LEVEL_EMERG to a given input level.
972 The default filter mask is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
973 This means that by default,
974 and in the absence of remote-control changes (described below),
975 ASL_LEVEL_DEBUG and ASL_LEVEL_INFO priority level messages
980 Three different filters exist for each application.
981 The first is the filter mask set using
984 The Apple System Log facility also manages a
987 The master filter mask usually has a value
988 that indicates to the library that it is
990 and thus it has no effect.
991 However, the mask filter mask may be enabled
992 by giving it a value using the
997 When the master filter mask has been set,
998 it takes precedence over the client's filter mask.
999 The client's mask is unmodified,
1000 and will become active again if remote-control filtering is disabled.
1002 In addition to the master filter mask,
1003 The Apple System Log facility
1004 also manages a per-client remote-control filter mask.
1005 Like the master filter mask, the per-client mask is usually
1007 having no effect on a client.
1008 If a per-client filter mask is set using the
1012 option, then it takes precedence
1013 over both the client's filter mask and the master filter mask.
1014 As is the case with the master filter mask,
1015 a per-client mask ceases having any effect when if is disabled.
1017 The ASL_OPT_NO_REMOTE option to
1019 causes both the master and per-client remote-control masks
1020 to be ignored in the library.
1021 In that case, only the client's own filter mask
1022 is used to determine which messages are sent to the server.
1023 This may be useful for Applications that produce log messages
1024 that should never be filtered, due to security considerations.
1025 Note that root (administrator) access is required
1026 to set or change the master filter mask,
1027 and that only root may change a per-client remote-control filter mask
1028 for a root (UID 0) process.
1030 The per-process remote control filter value is kept as a state value
1031 associated with a key managed by
1033 The key is protected by an access control mechanism that only permits the
1034 filter value to be accessed and modified by the same effective UID as the
1035 ASL client at the time that the first ASL connection was created.
1036 Remote filter control using
1038 will fail for processes that change effective UID after starting an ASL connection.
1039 Those processes should close all ASL client handles and then re-open ASL connections
1040 if remote filter control support is desired.
1042 These functions first appeared in
projects / apple / libc.git / blob