X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/3d9156a7a519a5e3aa1b92e9d9d4b991f1aed7ff..fbd86d4cc20b02a10edcca92fb7ae0a143e63cc4:/include/asl.h diff --git a/include/asl.h b/include/asl.h index 3eb751d..3d9c63f 100644 --- a/include/asl.h +++ b/include/asl.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2004 Apple Computer, Inc. All rights reserved. + * Copyright (c) 2004 - 2007 Apple Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * @@ -33,8 +33,33 @@ typedef struct __aslclient *aslclient; typedef struct __aslmsg *aslmsg; typedef struct __aslresponse *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. + */ + /* - * Log levels of the message + * 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 __DARWIN_LDBL_COMPAT2 +/*! @parseOnly */ +#define __DARWIN_LDBL_COMPAT2(a) +#endif +#ifndef __printflike +/*! @parseOnly */ +#define __printflike(a,b) +#endif + +/*! @defineblock Log Message Priority Levels + * Log levels of the message. */ #define ASL_LEVEL_EMERG 0 #define ASL_LEVEL_ALERT 1 @@ -44,9 +69,10 @@ typedef struct __aslresponse *aslresponse; #define ASL_LEVEL_NOTICE 5 #define ASL_LEVEL_INFO 6 #define ASL_LEVEL_DEBUG 7 +/*! @/defineblock */ -/* - * Corresponding level strings +/*! @defineblock Log Message Priority Level Strings + * Strings corresponding to log levels. */ #define ASL_STRING_EMERG "Emergency" #define ASL_STRING_ALERT "Alert" @@ -56,9 +82,10 @@ typedef struct __aslresponse *aslresponse; #define ASL_STRING_NOTICE "Notice" #define ASL_STRING_INFO "Info" #define ASL_STRING_DEBUG "Debug" +/*! @/defineblock */ -/* - * Attribute value comparison operations +/*! @defineblock Attribute Matching + * Attribute value comparison operations. */ #define ASL_QUERY_OP_CASEFOLD 0x0010 #define ASL_QUERY_OP_PREFIX 0x0020 @@ -74,34 +101,44 @@ typedef struct __aslresponse *aslresponse; #define ASL_QUERY_OP_LESS_EQUAL 0x0005 #define ASL_QUERY_OP_NOT_EQUAL 0x0006 #define ASL_QUERY_OP_TRUE 0x0007 +/*! @/defineblock */ -/* - * Attributes of all messages. - * The following attributes are attached to log messages, - * and are preserved in the order listed. - * Additional attributes may be added as desired, and are - * appended in the order that they are defined. +/*! @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 (see ctime(3)). Set automatically */ -#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_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" /* Actual message that will be logged */ - -/* - * Message Types +#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 group). */ +#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 */ +/*! @/defineblock */ + +/*! @defineblock aslmsg Types + * Message type argument passed to asl_new(). */ #define ASL_TYPE_MSG 0 #define ASL_TYPE_QUERY 1 +/*! @/defineblock */ -/* 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) - -/* Individual filter masks */ +/*! @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 @@ -110,16 +147,28 @@ typedef struct __aslresponse *aslresponse; #define ASL_FILTER_MASK_NOTICE 0x20 #define ASL_FILTER_MASK_INFO 0x40 #define ASL_FILTER_MASK_DEBUG 0x80 +/*! @/defineblock */ -/* Options to asl_open */ +/*! @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 */ + +/*! @defineblock Client Creation Options + * Options for asl_open(). + */ #define ASL_OPT_STDERR 0x00000001 #define ASL_OPT_NO_DELAY 0x00000002 #define ASL_OPT_NO_REMOTE 0x00000004 +/*! @/defineblock */ __BEGIN_DECLS -/* - * asl_open: initialize a syslog connection +/*! + * Initialize a connection to the ASL server. + * * This call is optional in most 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. @@ -129,32 +178,59 @@ __BEGIN_DECLS * messages are not sent to the server by default. * * 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 + * @param facility + * (input) Facility name + * @param opts + * (input) Options (see asl_open Options) + * @result Returns an ASL client handle */ aslclient asl_open(const char *ident, const char *facility, uint32_t opts); -/* - * Shuts down the current connection to the server. +/*! + * Shuts down a connection to the server. + * + * @param asl + * (input) An ASL client handle */ void asl_close(aslclient asl); -/* - * asl_add_file: write log messages to the given file descriptor +/*! + * Write log messages to the given file descriptor. + * * Log messages will be written to this file as well as to the server. - */ + * + * @param asl + * (input) An ASL client handle + * @param fd + * (input) A file descriptor + * @result Returns 0 on success, non-zero on failure +*/ int asl_add_log_file(aslclient asl, int fd); -/* - * asl_remove_file: stop writing log messages to the given file descriptor +/*! + * Stop writing log messages to the given file descriptor. * The file descripter is not closed by this routine. + * + * @param asl + * (input) An ASL client handle + * @param fd + * (input) A file descriptor + * @result Returns 0 on success, non-zero on failure */ int asl_remove_log_file(aslclient asl, int fd); -/* - * Set a filter for messages being sent to the server +/*! + * 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 @@ -163,128 +239,178 @@ int asl_remove_log_file(aslclient asl, int fd); * 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 asl + * (input) An ASL client handle + * @param f + * (input) A filter value + * @result Returns the previous filter value */ int asl_set_filter(aslclient asl, int f); /* - * asl_key: examine attribute keys - * returns the key of the nth attribute in a message (beginning at zero) - * returns NULL if the message has fewer attributes + * Examine attribute keys. + * + * @param msg + * (input) An ASL message + * @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(aslmsg msg, uint32_t n); -/* - * asl_new: create a new log message. +/*! + * Create a new log message or query message. + * + * @param type + * (input) Message type (see aslmsg Types) + * @result Returns a newly allocated asmsg of the specified type */ aslmsg asl_new(uint32_t type); -/* - * asl_set: set attributes of a message - * msg: an aslmsg - * key: attribute key - * value: attribute value - * returns 0 for success, non-zero for failure +/*! + * Set or re-set a message attribute. + * + * @param msg + * (input) An aslmsg + * @param key + * (input) Attribute key + * @param value + * (input) Attribute value + * @result returns 0 for success, non-zero for failure */ int asl_set(aslmsg msg, const char *key, const char *value); -/* - * asl_unset: remove attributes of a message - * msg: an aslmsg - * key: attribute key +/*! + * Remove a message attribute. + * + * @param msg + * (input) An aslmsg + * @param key + * (input) Attribute key * returns 0 for success, non-zero for failure */ int asl_unset(aslmsg msg, const char *key); -/* - * asl_get: get attribute values from a message - * msg: an aslmsg - * key: attribute key - * returns the attribute value - * returns NULL if the message does not contain the key +/*! + * Get the value of a message attribute. + * + * @param msg + * (input) An aslmsg + * @param key + * (input) Attribute key + * @result Returns the attribute value, or NULL if the message does not contain the key */ const char *asl_get(aslmsg msg, const char *key); -/* - * asl_log: log a message with a particular log level - * msg: an aslmsg - * msg may be NULL, in which case a new message will be - * created and sent using default attributes. - * level: the log level - * format: A formating string followed by a list of arguments, like printf() - * returns 0 for success, non-zero for failure +/*! + * Log a message with a particular log level. + * + * @param asl + * (input) An ASL client handle + * @param msg + * (input) An aslmsg (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 */ -#ifdef __DARWIN_LDBL_COMPAT -int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __DARWIN_LDBL_COMPAT(asl_log); +#ifdef __DARWIN_LDBL_COMPAT2 +int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __DARWIN_LDBL_COMPAT2(asl_log) __printflike(4, 5); #else -int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...); +int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __printflike(4, 5); #endif -/* - * asl_vlog: Similar to asl_log, but taking a va_list instead of a list of - * arguments. - * msg: an aslmsg - * msg may be NULL, in which case a new message will be - * created and sent using default attributes. - * level: the log level of the associated message - * format: A formating string followed by a list of arguments, like vprintf() - * returns 0 for success, non-zero for failure +/*! + * 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 + * @param msg + * (input) An aslmsg (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 */ -#ifdef __DARWIN_LDBL_COMPAT -int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __DARWIN_LDBL_COMPAT(asl_vlog); +#ifdef __DARWIN_LDBL_COMPAT2 +int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __DARWIN_LDBL_COMPAT2(asl_vlog) __printflike(4, 0); #else -int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap); +int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __printflike(4, 0); #endif -/* - * asl_send: send a message +/*! + * 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. - * msg: an aslmsg - * returns 0 for success, non-zero for failure + * + * @param asl + * (input) An ASL client handle + * @param msg + * (input) An aslmsg + * @result Returns 0 for success, non-zero for failure */ int asl_send(aslclient asl, aslmsg msg); -/* - * asl_free: free a message - * msg: an aslmsg to free +/*! + * Free a message. Frees all the attribute keys and values. + * + * @param msg + * (input) An aslmsg to free */ void asl_free(aslmsg msg); -/* - * asl_set_query: set arbitrary parameters of a query - * Similar to als_set, but allows richer query operations. +/*! + * Set arbitrary parameters of a query. + * This is similar to asl_set, but allows richer query operations. * See ASL_QUERY_OP_* above. - * msg: an aslmsg - * key: attribute key - * value: attribute value - * op: an operation from the set above. - * returns 0 for success, non-zero for failure + * + * @param msg + * (input) An aslmsg + * @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(aslmsg msg, const char *key, const char *value, uint32_t op); -/* - * asl_search: Search for messages matching the criteria described - * by the aslmsg . 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(). - * a: an aslmsg - * returns: a set of messages that can be iterated over using aslresp_next(), - * and the values can be retrieved using aslresp_get. +/*! + * Search for messages matching the criteria described by the aslmsg. + * 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(). + * + * @param msg + * (input) An aslmsg to match + * @result Returns a set of messages accessable using aslresponse_next(), */ aslresponse asl_search(aslclient asl, aslmsg msg); -/* - * aslresponse_next: Iterate over responses returned from asl_search() - * a: a response returned from asl_search(); - * returns: The next log message (an aslmsg) or NULL on failure +/*! + * Iterate over responses returned from asl_search(). + * + * @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 */ aslmsg aslresponse_next(aslresponse r); -/* - * aslresponse_free: Free a response returned from asl_search() - * a: a response returned from asl_search() +/*! + * Free a response returned from asl_search(). + * @param r + * (input) An aslresponse returned by asl_search() */ -void aslresponse_free(aslresponse a); +void aslresponse_free(aslresponse r); __END_DECLS