X-Git-Url: https://git.saurik.com/apple/syslog.git/blobdiff_plain/8158235332f5a3f4f20cebe26bf739b481ca2df5..af7d442cca5b798617acaab11b1772e9df60729b:/libsystem_asl.tproj/include/asl.h diff --git a/libsystem_asl.tproj/include/asl.h b/libsystem_asl.tproj/include/asl.h index 1ae909c..3fb8778 100644 --- a/libsystem_asl.tproj/include/asl.h +++ b/libsystem_asl.tproj/include/asl.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2004-2012 Apple Inc. All rights reserved. + * Copyright (c) 2004-2015 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * @@ -25,15 +25,26 @@ #define __ASL_H__ #include +#include #include #include #include -typedef struct __aslclient *aslclient; -typedef struct __aslmsg *aslmsg; -typedef struct __aslresponse *aslresponse; +/* Version number encodes the date YYYYMMDD */ +#define ASL_API_VERSION 20150225 + +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 are deprecated and replaced by os_log(3). On OS versions + * with os_log(3), the ASL routines for emitting log messages are shimmed into + * the equivalent os_log functionality. Functions whose deprecation messages + * indicate they are unsupported will have no effect on OS versions with + * os_log(3) support. + * * 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 @@ -54,6 +65,8 @@ typedef struct __aslresponse *aslresponse; #define __printflike(a,b) #endif +#pragma mark - + /*! @defineblock Log Message Priority Levels * Log levels of the message. */ @@ -67,6 +80,8 @@ typedef struct __aslresponse *aslresponse; #define ASL_LEVEL_DEBUG 7 /*! @/defineblock */ +#pragma mark - + /*! @defineblock Log Message Priority Level Strings * Strings corresponding to log levels. */ @@ -80,6 +95,8 @@ typedef struct __aslresponse *aslresponse; #define ASL_STRING_DEBUG "Debug" /*! @/defineblock */ +#pragma mark - + /*! @defineblock Attribute Matching * Attribute value comparison operations. */ @@ -99,44 +116,82 @@ typedef struct __aslresponse *aslresponse; #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_SENDER_INSTANCE "SenderInstance" /* Sender instance UUID. */ +#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 */ -/*! @defineblock aslmsg Types - * Message type argument passed to asl_new(). +#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. @@ -151,6 +206,8 @@ typedef struct __aslresponse *aslresponse; #define ASL_FILTER_MASK_DEBUG 0x80 /*! @/defineblock */ +#pragma mark - + /*! @defineblock Filter Mask Macros * Macros to create bitmasks for filter settings - see asl_set_filter(). */ @@ -158,20 +215,36 @@ typedef struct __aslresponse *aslresponse; #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 @@ -188,6 +261,8 @@ typedef struct __aslresponse *aslresponse; #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 @@ -202,6 +277,8 @@ typedef struct __aslresponse *aslresponse; #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. @@ -209,67 +286,100 @@ typedef struct __aslresponse *aslresponse; * Note that the message may still be processed if it will be written * to a file or stderr. * - * @param asl - * (input) An ASL client handle + * @param client + * (input) An ASL_TYPE_CLIENT object. * @param msg - * (input) An aslmsg (default attributes will be supplied if msg is NULL) + * (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) + * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). * @param format - * (input) A printf() - style format string followed by a list of arguments + * (input) A printf() - style format string followed by a list of arguments. */ -#define ASL_PREFILTER_LOG(asl, msg, level, format, ...) \ +#define ASL_PREFILTER_LOG(client, msg, level, format, ...) \ do { \ - aslclient _asl = (asl); \ - aslmsg _msg = (msg); \ - uint32_t _asl_eval = _asl_evaluate_send(_asl, _msg, (level)); \ - if (_asl_eval != 0) _asl_lib_log(_asl, _asl_eval, _msg, (format), ## __VA_ARGS__); \ + 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(aslclient asl, uint32_t eval, aslmsg msg, const char *format, ...) __printflike(4, 5); - -uint32_t _asl_evaluate_send(aslclient asl, aslmsg msg, int level); +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 most cases. The library will perform any + * 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_DELAY - connects to the server immediately - * * 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 + * (input) Sender name. * @param facility - * (input) Facility name + * (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) __API_DEPRECATED("os_log(3) has replaced asl(3); see os_log_create(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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 asl_open Options) - * @result Returns an ASL client handle + * (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. */ -aslclient asl_open(const char *ident, const char *facility, uint32_t opts); +asl_object_t asl_open_path(const char *path, uint32_t opts) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Shuts down a connection to the server. + * This routine is identical to asl_release(). * - * @param asl - * (input) An ASL client handle + * @param obj + * (input) An ASL object. */ -void asl_close(aslclient asl); +void asl_close(asl_object_t obj) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Write log messages to the given file descriptor. @@ -278,13 +388,13 @@ void asl_close(aslclient asl); * 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 asl - * (input) An ASL client handle + * @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 + * (input) A file descriptor. + * @result Returns 0 on success, non-zero on failure. */ -int asl_add_log_file(aslclient asl, int descriptor); +int asl_add_log_file(asl_object_t client, int descriptor) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Write log messages to the given file descriptor. @@ -295,21 +405,21 @@ int asl_add_log_file(aslclient asl, int descriptor); * control of the time zone used when printing time values, and allowing * individual filtering control for each log file. * - * @param asl - * (input) An ASL client handle + * @param client + * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param descriptor - * (input) A file descriptor + * (input) A file descriptor. * @param mfmt - * (input) A character string specifying the message format + * (input) A character string specifying the message format. * @param tfmt - * (input) A character string specifying the time format + * (input) A character string specifying the time format. * @param filter - * (input) A filter value + * (input) A filter value. * @param text_encoding - * (input) A text encoding type - * @result Returns 0 on success, non-zero on failure + * (input) A text encoding type. + * @result Returns 0 on success, non-zero on failure. */ -int asl_add_output_file(aslclient asl, int descriptor, const char *mfmt, const char *tfmt, int filter, int text_encoding) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); +int asl_add_output_file(asl_object_t client, int fd, const char *mfmt, const char *tfmt, int filter, int text_encoding) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.10,10.12), ios(7.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Write log messages to the given file descriptor. @@ -317,27 +427,27 @@ int asl_add_output_file(aslclient asl, int descriptor, const char *mfmt, const c * 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 asl - * (input) An ASL client handle + * @param client + * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). * @param descriptor - * (input) A file descriptor + * (input) A file descriptor. * @param filter - * (input) A filter value - * @result Returns the previous filter value + * (input) A filter value. + * @result Returns the previous filter value. */ -int asl_set_output_file_filter(aslclient ac, int fd, int filter) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); +int asl_set_output_file_filter(asl_object_t client, int fd, int filter) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.10,10.12), ios(7.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Stop writing log messages to the given file descriptor. - * The file descripter is not closed by this routine. + * The file descriptor is not closed by this routine. * - * @param asl - * (input) An ASL client handle + * @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 + * (input) A file descriptor. + * @result Returns 0 on success, non-zero on failure. */ -int asl_remove_log_file(aslclient asl, int descriptor); +int asl_remove_log_file(asl_object_t client, int descriptor) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Set a filter for messages being sent to the server. @@ -351,102 +461,166 @@ int asl_remove_log_file(aslclient asl, int descriptor); * The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE). * Returns the previous filter value. * - * @param asl - * (input) An ASL client handle + * @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 + * (input) A filter value. + * @result Returns the previous filter value. */ -int asl_set_filter(aslclient asl, int f); +int asl_set_filter(asl_object_t client, int f) __API_DEPRECATED("os_log(3) has replaced asl(3); see log(1)'s config command", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /* * Examine attribute keys. * * @param msg - * (input) An ASL message + * (input) An ASL message or query (asl_object_t of type ASL_TYPE_MSG or ASL_TYPE_QUERY). * @param n - * (input) An index value + * (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(aslmsg msg, uint32_t n); +const char *asl_key(asl_object_t msg, uint32_t n) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Create a new log message or query message. + * Create a new log message, query message, message list, or a connection to the system database. * * @param type - * (input) Message type (see aslmsg Types) - * @result Returns a newly allocated asmsg of the specified 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(). */ -aslmsg asl_new(uint32_t type); +asl_object_t asl_new(uint32_t type) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Set or re-set a message attribute. + * 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 msg - * (input) An aslmsg + * @param obj + * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. * @param key - * (input) Attribute key + * (input) Attribute key. * @param value - * (input) Attribute value - * @result returns 0 for success, non-zero for failure + * (input) Attribute value. + * @result returns 0 for success, non-zero for failure. */ -int asl_set(aslmsg msg, const char *key, const char *value); +int asl_set(asl_object_t obj, const char *key, const char *value) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Remove a message attribute. + * Remove a key/value attribute. * - * @param msg - * (input) An aslmsg + * @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 + * (input) Attribute key. + * returns 0 for success, non-zero for failure. */ -int asl_unset(aslmsg msg, const char *key); +int asl_unset(asl_object_t obj, const char *key) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Get the value of a message attribute. + * Get the value associated with an attribute key. * - * @param msg - * (input) An aslmsg + * @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 message does not contain the key + * (input) Attribute key. + * @result Returns the attribute value, or NULL if the object does not contain the key. */ -const char *asl_get(aslmsg msg, const char *key); +const char *asl_get(asl_object_t msg, const char *key) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Log a message with a particular log level. * - * @param asl - * (input) An ASL client handle + * @param obj + * (input) An asl_object_t or NULL. * @param msg - * (input) An aslmsg (default attributes will be supplied if msg is NULL) + * (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) + * (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 + * (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) __not_tail_called __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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(aslclient asl, aslmsg msg, int level, const char *format, ...) __printflike(4, 5); +int asl_log_message(int level, const char *format, ...) __printflike(2, 3) __not_tail_called __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Log a message with a particular log level. * Similar to asl_log, but takes a va_list argument. * * @param asl - * (input) An ASL client handle + * (input) An ASL object or NULL. * @param msg - * (input) An aslmsg (default attributes will be supplied if msg is NULL) + * (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) + * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). * @param format - * (input) A printf() - style format string followed by a list of arguments + * (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 + * (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(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __printflike(4, 0); +int asl_vlog(asl_object_t obj, asl_object_t msg, int level, const char *format, va_list ap) __printflike(4, 0) __not_tail_called __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Log a message. @@ -455,20 +629,52 @@ int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list a * has been used to set all of a message's attributes. * * @param asl - * (input) An ASL client handle + * (input) An ASL object or NULL. * @param msg - * (input) An aslmsg - * @result Returns 0 for success, non-zero for failure + * (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(aslclient asl, aslmsg msg); +int asl_send(asl_object_t obj, asl_object_t msg) __not_tail_called __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Free a message. Frees all the attribute keys and values. + * 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 msg - * (input) An aslmsg to free + * @param obj + * (input) An ASL object to free. + */ +void asl_free(asl_object_t obj) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); + +/*! + * Get the internal type of an ASL object. + * + * @param obj + * (input) An ASL object. + * @result Returns the object type. */ -void asl_free(aslmsg msg); +uint32_t asl_get_type(asl_object_t obj) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Set arbitrary parameters of a query. @@ -476,7 +682,7 @@ void asl_free(aslmsg msg); * See ASL_QUERY_OP_* above. * * @param msg - * (input) An aslmsg + * (input) An ASL object of type ASL_TYPE_QUERY. * @param key * (input) Attribute key * @param value @@ -485,34 +691,123 @@ void asl_free(aslmsg msg); * (input) An operation (ASL_QUERY_OP_*) * @result Returns 0 for success, non-zero for failure */ -int asl_set_query(aslmsg msg, const char *key, const char *value, uint32_t op); +int asl_set_query(asl_object_t msg, const char *key, const char *value, uint32_t op) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Search for messages matching the criteria described by the aslmsg. + * 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 operatoin ASL_QUERY_OP_EQUAL is used for attributes set with asl_set(). + * The operation ASL_QUERY_OP_EQUAL is used for attributes set with asl_set(). * - * @param msg - * (input) An aslmsg to match - * @result Returns a set of messages accessable using aslresponse_next(), + * @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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.4,10.12), ios(2.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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. */ -aslresponse asl_search(aslclient asl, aslmsg msg); +void asl_append(asl_object_t obj, asl_object_t obj_to_add) __not_tail_called __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Iterate over responses returned from asl_search(). + * 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 r - * (input) An aslresponse returned by asl_search() - * @result Returns the next message (an aslmsg) in the response, or NULL when there are no more messages + * @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. */ -aslmsg aslresponse_next(aslresponse r); +void asl_prepend(asl_object_t obj, asl_object_t obj_to_add) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Free a response returned from asl_search(). - * @param r - * (input) An aslresponse returned by asl_search() + * 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. */ -void aslresponse_free(aslresponse r); +size_t asl_count(asl_object_t obj) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Creates an auxiliary file that may be used to save arbitrary data. The ASL message msg @@ -532,17 +827,16 @@ void aslresponse_free(aslresponse r); * seconds after the Epoch, or it may be ctime() format, e.g "Thu Jun 24 18:22:48 2010". * * @param msg - * (input) An aslmsg + * (input) An object of type ASL_TYPE_MSG. * @param tite - * (input) A title string for the file + * (input) A title string for the file. * @param uti - * (input) Uniform Type Identifier for the file + * (input) Uniform Type Identifier for the file. * @param out_descriptor - * (output) A writable file descriptor + * (output) A writable file descriptor. * @result Returns 0 for success, non-zero for failure */ -int asl_create_auxiliary_file(aslmsg msg, const char *title, const char *uti, int *out_descriptor) -__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); +int asl_create_auxiliary_file(asl_object_t msg, const char *title, const char *uti, int *out_descriptor) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.7,10.12), ios(5.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Close an auxiliary file opened by asl_create_auxiliary_file() when writing is complete. @@ -553,8 +847,7 @@ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); * (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); +int asl_close_auxiliary_file(int descriptor) __API_DEPRECATED("os_log(3) has replaced asl(3); this functionality is no longer supported", macosx(10.7,10.12), ios(5.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * Sends an ASL message to syslogd along with a title string, Uniform Resource Locator, @@ -563,7 +856,7 @@ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); * type "public.data" is used. * * @param msg - * (input) An aslmsg + * (input) An object of type ASL_TYPE_MSG. * @param title * (input) A title string for the file * @param uti @@ -572,34 +865,39 @@ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); * (input) Uniform Type Locator * @result Returns 0 for success, non-zero for failure */ -int asl_log_auxiliary_location(aslmsg msg, const char *title, const char *uti, const char *url) -__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); +int asl_log_auxiliary_location(asl_object_t msg, const char *title, const char *uti, const char *url) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.7,10.12), ios(5.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! - * Creates an aslclient 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. + * 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. * - * The file will be truncated if it is not empty. When logging to the auxiliary file is complete, - * aslclient should be closed using asl_close(). The file should be closed using - * asl_close_auxiliary_file() if it was returned by asl_create_auxiliary_file(), or close() - * otherwise. + * 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 aslclient is thread-safe. + * 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 aslclient + * @result An object of type ASL_TYPE_CLIENT. */ -aslclient asl_open_from_file(int descriptor, const char *ident, const char *facility) -__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); +asl_object_t asl_open_from_file(int descriptor, const char *ident, const char *facility) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.7,10.12), ios(5.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); /*! * This API provides functionality to use file descriptors to send logging @@ -610,7 +908,7 @@ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); * 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. + * is treated differently 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. @@ -631,10 +929,10 @@ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); * 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 asl - * (input) An ASL client handle + * @param client + * (input) An ASL object of type ASL_TYPE_CLIENT. * @param msg - * (input) An aslmsg (default attributes will be supplied if msg is NULL) + * (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 @@ -643,8 +941,149 @@ __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); * (input) Either ASL_LOG_DESCRIPTOR_READ or ASL_LOG_DESCRIPTOR_WRITE * @result Returns 0 for success, non-zero for failure */ -int asl_log_descriptor(aslclient asl, aslmsg msg, int level, int descriptor, uint32_t fd_type) -__OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_5_1); +int asl_log_descriptor(asl_object_t asl, asl_object_t msg, int level, int descriptor, uint32_t fd_type) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.8,10.12), ios(5.1,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); + +#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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.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) __API_DEPRECATED("os_log(3) has replaced asl(3)", macosx(10.10,10.12), ios(8.0,10.0), watchos(2.0,3.0), tvos(9.0,10.0)); __END_DECLS