/* * Copyright (c) 2004-2013 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ #ifndef __ASL_H__ #define __ASL_H__ #include #include #include #include #include /* Version number encodes the date YYYYMMDD */ #define ASL_API_VERSION 20131108 typedef struct __asl_object_s *asl_object_t; typedef asl_object_t aslclient; typedef asl_object_t aslmsg; typedef asl_object_t aslresponse; /*! @header * These routines provide an interface to the Apple System Log facility. * The API allows client applications to create flexible, structured messages * and send them to the syslogd server. Messages received by the server are * saved in a data store, subject to input filtering constraints. * This API also permits clients to create queries and search the message * data store for matching messages. */ /* * NOTE FOR HeaderDoc * * These are added to allow headerdoc2html to process * the prototypes of asl_log and asl_vlog correctly. * The "-p" option to headerdoc2html is required. */ #ifndef __printflike /*! @parseOnly */ #define __printflike(a,b) #endif #pragma mark - /*! @defineblock Log Message Priority Levels * Log levels of the message. */ #define ASL_LEVEL_EMERG 0 #define ASL_LEVEL_ALERT 1 #define ASL_LEVEL_CRIT 2 #define ASL_LEVEL_ERR 3 #define ASL_LEVEL_WARNING 4 #define ASL_LEVEL_NOTICE 5 #define ASL_LEVEL_INFO 6 #define ASL_LEVEL_DEBUG 7 /*! @/defineblock */ #pragma mark - /*! @defineblock Log Message Priority Level Strings * Strings corresponding to log levels. */ #define ASL_STRING_EMERG "Emergency" #define ASL_STRING_ALERT "Alert" #define ASL_STRING_CRIT "Critical" #define ASL_STRING_ERR "Error" #define ASL_STRING_WARNING "Warning" #define ASL_STRING_NOTICE "Notice" #define ASL_STRING_INFO "Info" #define ASL_STRING_DEBUG "Debug" /*! @/defineblock */ #pragma mark - /*! @defineblock Attribute Matching * Attribute value comparison operations. */ #define ASL_QUERY_OP_CASEFOLD 0x0010 #define ASL_QUERY_OP_PREFIX 0x0020 #define ASL_QUERY_OP_SUFFIX 0x0040 #define ASL_QUERY_OP_SUBSTRING 0x0060 #define ASL_QUERY_OP_NUMERIC 0x0080 #define ASL_QUERY_OP_REGEX 0x0100 #define ASL_QUERY_OP_EQUAL 0x0001 #define ASL_QUERY_OP_GREATER 0x0002 #define ASL_QUERY_OP_GREATER_EQUAL 0x0003 #define ASL_QUERY_OP_LESS 0x0004 #define ASL_QUERY_OP_LESS_EQUAL 0x0005 #define ASL_QUERY_OP_NOT_EQUAL 0x0006 #define ASL_QUERY_OP_TRUE 0x0007 /*! @/defineblock */ #pragma mark - /*! @defineblock Message Attributes * These attributes are known by ASL, and are generally * associated with all log messages. * Additional attributes may be added as desired. */ #define ASL_KEY_TIME "Time" /* Timestamp. Set automatically */ #define ASL_KEY_TIME_NSEC "TimeNanoSec" /* Nanosecond time. */ #define ASL_KEY_HOST "Host" /* Sender's address (set by the server). */ #define ASL_KEY_SENDER "Sender" /* Sender's identification string. Default is process name. */ #define ASL_KEY_FACILITY "Facility" /* Sender's facility. Default is "user". */ #define ASL_KEY_PID "PID" /* Sending process ID encoded as a string. Set automatically. */ #define ASL_KEY_UID "UID" /* UID that sent the log message (set by the server). */ #define ASL_KEY_GID "GID" /* GID that sent the log message (set by the server). */ #define ASL_KEY_LEVEL "Level" /* Log level number encoded as a string. See levels above. */ #define ASL_KEY_MSG "Message" /* Message text. */ #define ASL_KEY_READ_UID "ReadUID" /* User read access (-1 is any user). */ #define ASL_KEY_READ_GID "ReadGID" /* Group read access (-1 is any group). */ #define ASL_KEY_EXPIRE_TIME "ASLExpireTime" /* Expiration time for messages with long TTL. */ #define ASL_KEY_MSG_ID "ASLMessageID" /* 64-bit message ID number (set by the server). */ #define ASL_KEY_SESSION "Session" /* Session (set by the launchd). */ #define ASL_KEY_REF_PID "RefPID" /* Reference PID for messages proxied by launchd */ #define ASL_KEY_REF_PROC "RefProc" /* Reference process for messages proxied by launchd */ #define ASL_KEY_AUX_TITLE "ASLAuxTitle" /* Auxiliary title string */ #define ASL_KEY_AUX_UTI "ASLAuxUTI" /* Auxiliary Uniform Type ID */ #define ASL_KEY_AUX_URL "ASLAuxURL" /* Auxiliary Uniform Resource Locator */ #define ASL_KEY_AUX_DATA "ASLAuxData" /* Auxiliary in-line data */ #define ASL_KEY_OPTION "ASLOption" /* Internal */ #define ASL_KEY_MODULE "ASLModule" /* Internal */ #define ASL_KEY_SENDER_INSTANCE "SenderInstance" /* Sender instance UUID. */ #define ASL_KEY_SENDER_MACH_UUID "SenderMachUUID" /* Sender Mach-O UUID. */ #define ASL_KEY_FINAL_NOTIFICATION "ASLFinalNotification" /* syslogd posts value as a notification when message has been processed */ #define ASL_KEY_OS_ACTIVITY_ID "OSActivityID" /* Current OS Activity for the logging thread */ /*! @/defineblock */ #pragma mark - /*! @defineblock ASL Object Types * The library uses only one opaque type - asl_object_t. * Many of the routines can operate on several different types. * For example, asl_search() can be used to search a list of messages, * an ASL database directory or data file, or the main ASL database. * It can even be used to check a single message against a query * message, or against another message to check for exact match. * * The first three types are container objects - messages, queries, * and lists of messages or queries. The following types are * abstractions for ASL data files and ASL data stores (directories * containing data files). * * ASL_TYPE_CLIENT is a high-level object that abstracts ASL * interactions. It may access ASL stores or files directly, * and it may communicate with ASL daemons. * */ #define ASL_TYPE_UNDEF 0xffffffff #define ASL_TYPE_MSG 0 #define ASL_TYPE_QUERY 1 #define ASL_TYPE_LIST 2 #define ASL_TYPE_FILE 3 #define ASL_TYPE_STORE 4 #define ASL_TYPE_CLIENT 5 /*! @/defineblock */ #pragma mark - /*! @defineblock search directions * Used for asl_store_match(), asl_file_match(), and asl_match(). */ #define ASL_MATCH_DIRECTION_FORWARD 1 #define ASL_MATCH_DIRECTION_REVERSE -1 /*! @/defineblock */ #pragma mark - /*! @defineblock Filter Masks * Used in client-side filtering, which determines which * messages are sent by the client to the syslogd server. */ #define ASL_FILTER_MASK_EMERG 0x01 #define ASL_FILTER_MASK_ALERT 0x02 #define ASL_FILTER_MASK_CRIT 0x04 #define ASL_FILTER_MASK_ERR 0x08 #define ASL_FILTER_MASK_WARNING 0x10 #define ASL_FILTER_MASK_NOTICE 0x20 #define ASL_FILTER_MASK_INFO 0x40 #define ASL_FILTER_MASK_DEBUG 0x80 /*! @/defineblock */ #pragma mark - /*! @defineblock Filter Mask Macros * Macros to create bitmasks for filter settings - see asl_set_filter(). */ #define ASL_FILTER_MASK(level) (1 << (level)) #define ASL_FILTER_MASK_UPTO(level) ((1 << ((level) + 1)) - 1) /*! @/defineblock */ #pragma mark - /*! @defineblock Client Creation Options * Options for asl_open(). * Note that ASL_OPT_NO_DELAY no longer has any effect. */ #define ASL_OPT_STDERR 0x00000001 #define ASL_OPT_NO_DELAY 0x00000002 #define ASL_OPT_NO_REMOTE 0x00000004 /*! @/defineblock */ #pragma mark - /*! @defineblock File and Store Open Options * Options for asl_open_path(). */ #define ASL_OPT_OPEN_WRITE 0x00000001 #define ASL_OPT_CREATE_STORE 0x00000002 /*! @/defineblock */ #pragma mark - /*! @defineblock File Descriptor Types * Instructions on how to treat the file descriptor in asl_log_descriptor(). */ #define ASL_LOG_DESCRIPTOR_READ 1 #define ASL_LOG_DESCRIPTOR_WRITE 2 #pragma mark - /*! @defineblock Output file message and time formats. * These select internally defined formats for printed log messages for * asl_add_output_file(). Custom message and time formats may also be * used. These pre-defined formats and custom formats are described in detail * in the syslog(1) manual page. */ #define ASL_MSG_FMT_RAW "raw" #define ASL_MSG_FMT_STD "std" #define ASL_MSG_FMT_BSD "bsd" #define ASL_MSG_FMT_XML "xml" #define ASL_MSG_FMT_MSG "msg" #define ASL_TIME_FMT_SEC "sec" #define ASL_TIME_FMT_UTC "utc" #define ASL_TIME_FMT_LCL "lcl" #pragma mark - /*! @defineblock Text Encoding Types * These are used by the library when formatting messages to be written * to file descriptors associated with an ASL client handle with * asl_add_output_file(). The syslog(1) manual page describes text encoding * in detail. ASL_ENCODE_ASL corresponds to the "vis" encoding option * described in the syslog(1) manual. ASL_ENCODE_XML should be used in * combination with ASL_MSG_FMT_XML to ensure that special XML characters * are correctly encoded. */ #define ASL_ENCODE_NONE 0 #define ASL_ENCODE_SAFE 1 #define ASL_ENCODE_ASL 2 #define ASL_ENCODE_XML 3 #pragma mark - /*! * ASL_PREFILTER_LOG is a macro similar to asl_log(), but it first checks * if the message will simply be ignored due to local filter settings. * This prevents the variable argument list from being evaluated. * Note that the message may still be processed if it will be written * to a file or stderr. * * @param client * (input) An ASL_TYPE_CLIENT object. * @param msg * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). * @param level * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). * @param format * (input) A printf() - style format string followed by a list of arguments. */ #define ASL_PREFILTER_LOG(client, msg, level, format, ...) \ do { \ asl_object_t _client = (client); \ asl_object_t _msg = (msg); \ uint32_t _asl_eval = _asl_evaluate_send(_client, _msg, (level)); \ if (_asl_eval != 0) _asl_lib_log(_client, _asl_eval, _msg, (format), ## __VA_ARGS__); \ } while (0) #pragma mark - __BEGIN_DECLS /* ASL Library SPI - do not call directly */ int _asl_lib_log(asl_object_t client, uint32_t eval, asl_object_t msg, const char *format, ...) __printflike(4, 5); uint32_t _asl_evaluate_send(asl_object_t client, asl_object_t msg, int level); /*! * Initialize a connection to the ASL server. * * This call is optional in many cases. The library will perform any * necessary initializations on the fly. A call to asl_open() is required * if optional settings must be made before messages are sent to the server. * These include setting the client filter and managing additional output * file descriptors. Note that the default setting of the client filter is * ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE), so ASL_LEVEL_DEBUG and ASL_LEVEL_INFO * messages are not sent to the server by default. * A separate client connection is required for multiple threads or * dispatch queues. * * Options (defined above) may be set using the opts parameter. They are: * * ASL_OPT_STDERR - adds stderr as an output file descriptor * * ASL_OPT_NO_REMOTE - disables the remote-control mechanism for adjusting * filter levers for processes using e.g. syslog -c ... * * @param ident * (input) Sender name. * @param facility * (input) Facility name. * @param opts * (input) Options (see Client Creation Options). * @result Returns an ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). */ asl_object_t asl_open(const char *ident, const char *facility, uint32_t opts) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Open an ASL database or ASL data file for read or write access. * * Opens an ASL database if the path specifies a directory, or * an ASL data file if the path specifies a file. Opens the system * ASL database if path is NULL. * * If the ASL_OPT_OPEN_READ option is specified, the database or data file may be * searched with asl_search() or asl_match(). asl_next() and asl_prev() may be used * to iterate over the messages in the database or file. * * If the ASL_OPT_OPEN_WRITE option is specified, an existing file or database is * opened for writing. New messages may be added to the file or database using * asl_append(), asl_send(), asl_log(), or asl_vlog(). Existing messages in the * store or file may not be deleted or modified. * * If the path does not exist, asl_open_path() will create a new database if * ASL_OPT_CREATE_STORE is set in the options, or a new data file otherwise. * The file will be created with the user's effective UID and GID as owner and * group. The mode will be 0644. If a different mode, UID, or GID is desired, * an empty file or directory may be pre-created with the desired settings. * * @param path * (input) Location of the ASL database or ASL data file in the filesystem. * A value of NULL may be used to open the system's database. * @param opts * (input) Options (see File and Store Open Options). * @result Returns an ASL object of type ASL_TYPE_STORE or ASL_TYPE_FILE, or NULL on failure. */ asl_object_t asl_open_path(const char *path, uint32_t opts) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Shuts down a connection to the server. * This routine is identical to asl_release(). * * @param obj * (input) An ASL object. */ void asl_close(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Write log messages to the given file descriptor. * * Log messages will be written to this file as well as to the server. * This is equivalent to calling: * asl_add_output_file(asl, descriptor, ASL_MSG_FMT_STD, ASL_TIME_FMT_LCL, ASL_FILTER_MASK_UPTO(ASL_LEVEL_DEBUG), ASL_ENCODE_SAFE) * * @param client * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param descriptor * (input) A file descriptor. * @result Returns 0 on success, non-zero on failure. */ int asl_add_log_file(asl_object_t client, int descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Write log messages to the given file descriptor. * * Log messages will be written to this file as well as to the server. * This routine extends the basic interface offered by asl_add_log_file(), * allowing control of the format used to write log message written to the file. * control of the time zone used when printing time values, and allowing * individual filtering control for each log file. * * @param client * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param descriptor * (input) A file descriptor. * @param mfmt * (input) A character string specifying the message format. * @param tfmt * (input) A character string specifying the time format. * @param filter * (input) A filter value. * @param text_encoding * (input) A text encoding type. * @result Returns 0 on success, non-zero on failure. */ int asl_add_output_file(asl_object_t client, int fd, const char *mfmt, const char *tfmt, int filter, int text_encoding) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Write log messages to the given file descriptor. * * Sets or changes a filter value for filtering messages written to a file associated * with an ASL client handle using asl_add_output_file() or asl_add_log_file(). * * @param client * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param descriptor * (input) A file descriptor. * @param filter * (input) A filter value. * @result Returns the previous filter value. */ int asl_set_output_file_filter(asl_object_t client, int fd, int filter) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Stop writing log messages to the given file descriptor. * The file descripter is not closed by this routine. * * @param client * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param descriptor * (input) A file descriptor. * @result Returns 0 on success, non-zero on failure. */ int asl_remove_log_file(asl_object_t client, int descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Set a filter for messages being sent to the server. * The filter is a bitmask representing priorities. The ASL_FILTER_MASK * macro may be used to convert a priority level into a bitmask for that * level. The ASL_FILTER_MASK_UPTO macro creates a bitmask for all * priorities up to and including a given priority. * Messages with priority levels that do not have a corresponding bit * set in the filter are not sent to the server, although they will be * sent to any file descripters added with asl_add_log_file(). * The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE). * Returns the previous filter value. * * @param client * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param f * (input) A filter value. * @result Returns the previous filter value. */ int asl_set_filter(asl_object_t client, int f) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /* * Examine attribute keys. * * @param msg * (input) An ASL message or query (asl_object_t of type ASL_TYPE_MSG or ASL_TYPE_QUERY). * @param n * (input) An index value. * @result Returns the key of the nth attribute in a message (beginning at zero), * or NULL if n is greater than the largest message index. */ const char *asl_key(asl_object_t msg, uint32_t n) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /* * Examine attribute keys. * * @param msg * (input) An ASL message or query (asl_object_t of type ASL_TYPE_MSG or ASL_TYPE_QUERY). * @param key * (output) key at the given index. May be NULL. * @param val * (output) val at the given index. May be NULL. * @param op * (output) op at the given index. May be NULL. * @param n * (input) An index value. * @result returns 0 for success, non-zero for failure. */ int asl_fetch_key_val_op(asl_object_t msg, uint32_t n, const char **key, const char **val, uint32_t *op) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Create a new log message, query message, message list, or a connection to the system database. * * @param type * (input) ASL_TYPE_MSG, ASL_TYPE_QUERY, ASL_TYPE_LIST, or ASL_TYPE_CLIENT. * @result Returns a newly allocated asl_object_t of the specified type. * * @discussion * New objects of type ASL_TYPE_CLIENT will be created with default settings for * a client connection, equivalent to asl_open(NULL, NULL, 0). * The Sender and Facility values associated with an ASL_TYPE_CLIENT may * be reset using asl_set(). */ asl_object_t asl_new(uint32_t type) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Set or re-set a message or query attribute. * May also be used to set values associated with an ASL_TYPE_CLIENT object, * such as Sender and Facility. * * @param obj * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. * @param key * (input) Attribute key. * @param value * (input) Attribute value. * @result returns 0 for success, non-zero for failure. */ int asl_set(asl_object_t obj, const char *key, const char *value) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Remove a key/value attribute. * * @param obj * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. * @param key * (input) Attribute key. * returns 0 for success, non-zero for failure. */ int asl_unset(asl_object_t obj, const char *key) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Get the value associated with an attribute key. * * @param obj * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. * @param key * (input) Attribute key. * @result Returns the attribute value, or NULL if the object does not contain the key. */ const char *asl_get(asl_object_t msg, const char *key) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Log a message with a particular log level. * * @param obj * (input) An asl_object_t or NULL. * @param msg * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). * @param level * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). * @param format * (input) A printf() - style format string followed by a list of arguments. * @result Returns 0 for success, non-zero for failure. * * @discussion * The input object may be of any type. * In typical usage, obj is of type ASL_TYPE_CLIENT or obj is NULL. * NULL causes the library to use the default ASL client handle. * This routine prepares a message for tranmission to the ASL server daemon (syslogd), * The message is sent to the server subject to filter settings. The message may also * be formatted and printed to various output files. * * For ASL_TYPE_MSG, this routine will set all key/value pairs in the input object as * they would appear if the message were being sent to the server. This includes * setting alues for ASL_KEY_TIME, ASL_KEY_TIME_NSEC, ASL_KEY_HOST, and so on. * * If the object is of type ASL_TYPE_STORE or ASL_TYPE_FILE, a message will be * constructed (as above) and saved in the file or data store. No filtering is done. * * If obj is of type ASL_TYPE_LIST, a message is created and appended to the list. * * The object type ASL_TYPE_QUERY is supported, but the key/value pairs set in the * object will have an operator value of zero. */ int asl_log(asl_object_t client, asl_object_t msg, int level, const char *format, ...) __printflike(4, 5) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Log a message with a particular log level. * * This API is a simplified version of asl_log(). It uses the default (NULL) ASL client handle, * and does not have a msg parameter to supply additonal key/value pairs to be attached to the * message sent to the syslogd server. * * @param level * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). * @param format * (input) A printf() - style format string followed by a list of arguments. * @result Returns 0 for success, non-zero for failure. */ int asl_log_message(int level, const char *format, ...) __printflike(2, 3) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Log a message with a particular log level. * Similar to asl_log, but takes a va_list argument. * * @param asl * (input) An ASL object or NULL. * @param msg * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). * @param level * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). * @param format * (input) A printf() - style format string followed by a list of arguments. * @param ap * (input) A va_list containing the values for the format string. * @result Returns 0 for success, non-zero for failure. * @discussion * See the discussion for asl_log() for a description of how this routine treats different * types of input object. * */ int asl_vlog(asl_object_t obj, asl_object_t msg, int level, const char *format, va_list ap) __printflike(4, 0) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Log a message. * * This routine may be used instead of asl_log() or asl_vlog() if asl_set() * has been used to set all of a message's attributes. * * @param asl * (input) An ASL object or NULL. * @param msg * (input) An asl_object_t of type ASL_TYPE_MSG. * @result Returns 0 for success, non-zero for failure. * @discussion * See the discussion for asl_log() for a description of how this routine treats different * types of input object. */ int asl_send(asl_object_t obj, asl_object_t msg) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * DEPRECATED: Free an ASL object and all internal resources associated with it. * This routine is identical to asl_release(), which should be used instead. * Note that we don't issue a deprecation warning - yet. * * @param obj * (input) An ASL object to free. */ void asl_free(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Increment the internal reference count of an ASL object. * * @param obj * (input) An ASL object to retain. * @result Returns the object. */ asl_object_t asl_retain(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Decrement the internal reference count of an ASL object. * Frees the object when the reference count becomes zero. * * @param obj * (input) An ASL object to release. */ void asl_release(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Get the internal type of an ASL object. * * @param obj * (input) An ASL object. * @result Returns the object type. */ uint32_t asl_get_type(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Set arbitrary parameters of a query. * This is similar to asl_set, but allows richer query operations. * See ASL_QUERY_OP_* above. * * @param msg * (input) An ASL object of type ASL_TYPE_QUERY. * @param key * (input) Attribute key * @param value * (input) Attribute value * @param op * (input) An operation (ASL_QUERY_OP_*) * @result Returns 0 for success, non-zero for failure */ int asl_set_query(asl_object_t msg, const char *key, const char *value, uint32_t op) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * Search for messages matching the criteria described by an query object. * The caller should set the attributes to match using asl_set_query() or asl_set(). * The operation ASL_QUERY_OP_EQUAL is used for attributes set with asl_set(). * * @param obj * (input) An ASL object to search. * @param query * (input) An asl_object_t of type ASL_TYPE_QUERY or ASL_TYPE_MSG. * query may be NULL, which matches anything. * @result Returns an ASL object containing messages matching the query, or NULL if there are no matches. * * @discussion * The object to search may be of any type. * ASL_TYPE_CLIENT searches the main ASL database. * ASL_TYPE_STORE searches an ASL database in the filesystem. * ASL_TYPE_FILE searches an ASL data file in the filesystem. * ASL_TYPE_LIST searches for matches in a list of messages. * * A NULL query matches anything. * * If obj is of type ASL_TYPE_MSG and query is of type ASL_TYPE_QUERY, obj is matched against the query, * and a list containing the "obj" object is returned if the match succeeds. * * If both obj and query are objects of type ASL_TYPE_MSG or both are of type ASL_TYPE_QUERY, * they are tested for exact match. A list containing the "obj" object is returned if the match is exact. * * If obj is of type ASL_TYPE_QUERY and query is of type ASL_TYPE_MSG, the routine returns NULL. * */ asl_object_t asl_search(asl_object_t obj, asl_object_t query) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); /*! * DEPRECATED: Iterate over messages in an asl_object_t (same as an aslresponse). * This routine is identical to asl_next(). * * @param list * (input) An asl_object_t (aslresponse). * @result Returns the next message contained in an ASL object, or NULL when there are no more messages. * * @discussion * This routine is deprecated in favor of asl_next(). */ asl_object_t aslresponse_next(asl_object_t obj) __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_4,__MAC_10_10,__IPHONE_2_0,__IPHONE_7_0, "Use asl_next instead"); /*! * DEPRECATED: Free an asl_object_t. * This routine is identical to asl_release(). * * @param list * (input) An asl_object_t (aslresponse). * * @discussion * This routine is deprecated in favor of asl_release(). */ void aslresponse_free(asl_object_t obj) __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_4,__MAC_10_10,__IPHONE_2_0,__IPHONE_7_0, "Use asl_release instead"); /*! * Append messages to an object of type ASL_TYPE_LIST. The input "obj" * parameter may be of type ASL_TYPE_MSG or ASL_TYPE_QUERY, in which case * the object is appended to the list, or "obj" may be of type ASL_TYPE_LIST, * in which case each object in that list is appended to the "list" object. * Does nothing if either list or obj are NULL. * * @param obj * (input) An object of type ASLTYPE_CLIENT or ASL_TYPE_LIST, or an object of type * ASL_TYPE_FILE or ASL_TYPE_STORE that is open for write operations. * @param obj_to_add * (input) An object of type ASL_TYPE_MSG, ASL_TYPE_QUERY or type ASL_TYPE_LIST. */ void asl_append(asl_object_t obj, asl_object_t obj_to_add) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Prepend messages to an object of type ASL_TYPE_LIST. The input "obj" * parameter may be of type ASL_TYPE_MSG or ASL_TYPE_QUERY, in which case * the object is prepended to the list, or "obj" may be of type ASL_TYPE_LIST, * in which case each object in that list is prepended to the "list" object. * Does nothing if either list or obj are NULL. * * @param obj * (input) An object of type ASL_TYPE_LIST. * @param obj_to_add * (input) An object of type ASL_TYPE_MSG, ASL_TYPE_QUERY or type ASL_TYPE_LIST. */ void asl_prepend(asl_object_t obj, asl_object_t obj_to_add) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Get the number of key/value pairs in an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY, * or the number of components in an object of type ASL_TYPE_LIST. * * @param obj * (input) An asl_object_t of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_LIST. * @result The number of components in the object. * Returns zero if object is empty or NULL, or if the type is not * ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_LIST. */ size_t asl_count(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Retreive a message from an object of type ASL_TYPE_LIST. * * @param obj * (input) An asl_object_t of type ASL_TYPE_LIST * @result Returns the message (an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY) at the specified index. * Returns NULL if the index is out of range or if list is not an object of type ASL_TYPE_LIST. */ asl_object_t asl_get_index(asl_object_t list, size_t index) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Remove the message at a specified index from an object of type ASL_TYPE_LIST. * * @param list * (input) An object of type ASL_TYPE_LIST. */ void asl_remove_index(asl_object_t list, size_t index) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Creates an auxiliary file that may be used to save arbitrary data. The ASL message msg * will be saved at the time that the auxiliary file is closed with asl_close_auxiliary_file(). * The log entry will include any keys and values found in msg, and it will include the title * and Uniform Type Identifier specified. If NULL is supplied as a value for the uti parameter, * the type "public.data" is used. Console.app will display a hyperlink to the file. * Output parameter out_descriptor will contain a readable and writable file descriptor for the new * auxiliary file. * * By default, the file will be world-readable. If the message contains a ReadUID and/or a * ReadGID key, then the values for those keys will determine read access to the file. * * The file will be deleted at the same time that the message expires from the ASL data store. * The aslmanager utility manages message expiry. If msg contains a value for ASLExpireTime, * then the message and the file will not be deleted before that time. The value may be in * seconds after the Epoch, or it may be ctime() format, e.g "Thu Jun 24 18:22:48 2010". * * @param msg * (input) An object of type ASL_TYPE_MSG. * @param tite * (input) A title string for the file. * @param uti * (input) Uniform Type Identifier for the file. * @param out_descriptor * (output) A writable file descriptor. * @result Returns 0 for success, non-zero for failure */ int asl_create_auxiliary_file(asl_object_t msg, const char *title, const char *uti, int *out_descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); /*! * Close an auxiliary file opened by asl_create_auxiliary_file() when writing is complete. * syslogd will log the message provided to asl_create_auxiliary_file() when this routine * is called. * * @param descriptor * (input) The file descriptor * @result Returns 0 for success, non-zero for failure */ int asl_close_auxiliary_file(int descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); /*! * Sends an ASL message to syslogd along with a title string, Uniform Resource Locator, * and Uniform Type Identifier specified. Console.app will hyperlink the title string to * the specified URL. If NULL is supplied as a value for the uti parameter, the default * type "public.data" is used. * * @param msg * (input) An object of type ASL_TYPE_MSG. * @param title * (input) A title string for the file * @param uti * (input) Uniform Type Identifier for the file * @param url * (input) Uniform Type Locator * @result Returns 0 for success, non-zero for failure */ int asl_log_auxiliary_location(asl_object_t msg, const char *title, const char *uti, const char *url) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); /*! * Creates an object of type ASL_TYPE_CLIENT for logging to a file descriptor. * The file must be opened for read and write access. This routine may be used in conjunction * with asl_create_auxiliary_file() to save ASL format log messages to an auxiliary file. * * When logging to the file is complete, the returned object should be released with asl_release(). * The file descriptor should be closed using asl_close_auxiliary_file() if it was returned by * asl_create_auxiliary_file(), or close() otherwise. * * The returned client object is thread-safe. It contains a lock that is aquired by * the calling thread. Note that this may cause unexpected syncronization behavior * if multiple threads log to the returned object, or in applications that use the * object in multiple dispatch queues. * * Note that per-message read access controls (ReadUID and ReadGID) and message expire * times (ASLExpireTime) keys have no effect for messages written to this file. * * Also note that files are NOT truncated. This is a change in OS X 10.9 and iOS 7.0. * Previous versions of this routine truncated the file before writing. Callers * may use ftruncate() to truncate the file if desired. If an existing non-empty * file is used, it must be an ASL format data file. * * @param descriptor * (input) A file descriptor * @param ident * (input) Sender name * @param facility * (input) Facility name * @result An object of type ASL_TYPE_CLIENT. */ asl_object_t asl_open_from_file(int descriptor, const char *ident, const char *facility) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); /*! * This API provides functionality to use file descriptors to send logging * data to ASL. * * asl is retained by ASL and must still be closed by the caller by calling * asl_close() if the caller loses reference to it. msg is copied by ASL and * similarly must still be freed by the caller by calling asl_free() if the * caller loses reference to it. Any changes made to it after calling * asl_log_descriptor() are not applicable to the message used. descriptor * is treated differentlty based on the value of fd_type. * * If fd_type is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read * access. ASL uses GCD to read from the descriptor as data becomes available. * These data are line buffered and passed to asl_log. When EOF is read, the * descriptor is closed. * * Example: * asl_log_descriptor(c, m, ASL_LEVEL_NOTICE, STDIN_FILENO, ASL_LOG_DESCRIPTOR_READ); * * If fd_type is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new * writable descriptor is created with the same fileno. Any data written to * this new descriptor are line buffered and passed to asl_log. When EOF is * sent, no further data are read. The caller is responsible for closing the * new descriptor. One common use for this API is to redirect writes to stdout * or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as descriptor. * * Example: * asl_log_descriptor(c, m, ASL_LEVEL_NOTICE, STDOUT_FILENO, ASL_LOG_DESCRIPTOR_WRITE); * asl_log_descriptor(c, m, ASL_LEVEL_ERR, STDERR_FILENO, ASL_LOG_DESCRIPTOR_WRITE); * * @param client * (input) An ASL object of type ASL_TYPE_CLIENT. * @param msg * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). * @param level * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG) * @param descriptor * (input) An open file descriptor to read from * @param fd_type * (input) Either ASL_LOG_DESCRIPTOR_READ or ASL_LOG_DESCRIPTOR_WRITE * @result Returns 0 for success, non-zero for failure */ int asl_log_descriptor(asl_object_t asl, asl_object_t msg, int level, int descriptor, uint32_t fd_type) __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_5_1); #pragma mark - /*! * Creates a string representation of an ASL message. * * This utility creates a character string suitable for printing an ASL message. * The returned string ends with a newline character. The caller is responsible * for freeing the returned string. * The message is formatted according to the specified format string. Timestamps * are formatted accoring to the specified time format string. Special characters * are enoded as specified by the text_encoding parameter. * * @param msg * (input) An asl_object_t of type ASL_TYPE_MSG. * @param fmt * (input) A format specification string. See "Output file message and time formats" * for standard formats. See the syslog(1) man page for more discussion on formats. * @param fmt * (input) A time format specification string. See "Output file message and time formats" * for standard formats. See the syslog(1) man page for more discussion on time formats. * @param text_encoding * (input) Text encoding control (for special characters). See "Text Encoding Types". * @result Returns a character string, or NULL in case of a failure. */ char *asl_format(asl_object_t msg, const char *msg_fmt, const char *time_fmt, uint32_t text_encoding) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Encodes a buffer with embedded nul characters into a nul terminated C string. * The result must be freed by the caller. * * This utility is used to encode the value associated with ASL_KEY_AUX_DATA * in an ASL_TYPE_MSG object. An ASL_KEY_AUX_DATA key/value pair is used to hold the * data written to a file descriptor created by asl_create_auxiliary_file on iOS * systems, where the ASL database is stored in memory. * * @param buf * (input) Pointer to a data buffer. * @param len * (input) Length (in octets) of data buffer. * @result Returns an encoded character string. */ char *asl_encode_buffer(const char *buf, size_t len) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Decodes a C string previously created by asl_encode_buffer back into a buffer, * possibly containing embedded nul characters. Allocates memory for the buffer * and returns a pointer in an output parameter "buf". * The caller is responsible for freeing the buffer. * * This routine should be used to decode the value associated with an * ASL_KEY_AUX_DATA key in an ASL_TYPE_MSG object. * * @param in * (input) Pointer to nul-terminated string created by asl_encode_buffer. * @param buf * (output) Pointer to a newly allocated data buffer. * @param len * (input) Length (in octets) of data buffer. * @result Returns 0 on success, non-zero on failure. */ int asl_decode_buffer(const char *in, char **buf, size_t *len) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Iterate forward through messages in an asl_object_t. * The asl_object_t object maintains an internal position index for the underlying * collection of ASL messages, whether the asl_object_t represents a list, a * data file, or an ASL database. The position index is moved forward and the * "next" message is returned. * * @param obj * (input) An asl_object_t. * @result Returns the next message (an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY) from the object, * which should be of type ASL_TYPE_CLIENT, ASL_TYPE_LIST, ASL_TYPE_STORE, or ASL_TYPE_FILE. * Returns NULL when there are no more messages or if obj is not a type that holds messages. */ asl_object_t asl_next(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Iterate backwards through messages in an asl_object_t. * The asl_object_t object maintains an internal position index for the underlying * collection of ASL messages, whether the asl_object_t represents a list, a * data file, or an ASL database. The position index is moved backward and the * "previous" message is returned. * * @param data * (input) An asl_object_t. * @result Returns the previous message (an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY) from the object, * which should be of type ASL_TYPE_CLIENT, ASL_TYPE_LIST, ASL_TYPE_STORE, or ASL_TYPE_FILE. * Returns NULL when there are no more messages or if obj is not a type that holds messages. */ asl_object_t asl_prev(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Reset internal interation index in an asl_object_t. * * @param obj * (input) An object of type ASL_TYPE_CLIENT, ASL_TYPE_LIST, ASL_TYPE_STORE, or ASL_TYPE_FILE. * @param position * (input) Use 0 to position the internal interation index at the beginning of the asl_object_t object, * and SIZE_MAX to position it at the end. Other values of position may cause unpredictable behavior. */ void asl_reset_iteration(asl_object_t obj, size_t position) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); /*! * Searches an asl_object_t. * The search is controlled by a list of queries, and returns a list with matching messages. * A message is returned if it matches any of the queries in the query list. * A NULL querylist matches anything. * * The caller may provide a starting ASL message ID, a direction, and a count. * A start ID value of 0 means that matching should commence at the beginning of the target obj. * A value of SIZE_MAX indicates that matching should commence at the end (most recent message) * in the target. If a non-zero count value is supplied, the routine will return when it has * found that many messages, or it has checked all messages. If a non-zero duration is supplied, * the routine will return after the specified time (in microseconds). * If both count and duration are non-zero, the routine will return when the desired number of * items has been matched or when the specified duration has been exceeded, whichever occurs first. * The search direction may be ASL_MATCH_DIRECTION_FORWARD or ASL_MATCH_DIRECTION_REVERSE. * The routine sets the value of the out parameter last to be an index of the last message * checked while matching. To fetch matching messages in batches (using a small count or * duration value), the start value for each iteration should be set to (last + 1) if searching * forward, or (last - 1)for reverse search. * * @param data * (input) An asl_object_t object. * @param querylist * (input) An asl_object_t object containing zero or more queries. * @param last * (output) An internal position index of the last message checked while matching in the asl_object_t object. * @param start * (input) A position index specifying where matching should commence. * @param count * (input) The maximum number of messages to be returned in the res output list (zero indicates no limit). * @param duration * (input) A limit (in microseconds) on the time to be spent searching for results. Zero indicates no time limit. * @param direction * (input) ASL_MATCH_DIRECTION_FORWARD or ASL_MATCH_DIRECTION_REVERSE. * @result Returns an ASL object containing messages matching the querylist, or NULL if there are no matches. */ asl_object_t asl_match(asl_object_t data, asl_object_t querylist, size_t *last, size_t start, size_t count, uint32_t duration, int32_t direction) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); __END_DECLS #endif /* __ASL_H__ */