Loading...
--- Libc/Libc-763.13/include/asl.h
+++ /dev/null
@@ -1,510 +0,0 @@
-/*
- * Copyright (c) 2004-2010 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 <stdint.h>
-#include <stdarg.h>
-#include <sys/cdefs.h>
-#include <Availability.h>
-
-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.
- */
-
-/*
- * 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
-#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 */
-
-/*! @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 */
-
-/*! @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 */
-
-/*! @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. */
-/*! @/defineblock */
-
-/*! @defineblock aslmsg Types
- * Message type argument passed to asl_new().
- */
-#define ASL_TYPE_MSG 0
-#define ASL_TYPE_QUERY 1
-/*! @/defineblock */
-
-/*! @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 */
-
-/*! @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
-
-/*!
- * 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.
- * 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.
- *
- * 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 a connection to the server.
- *
- * @param asl
- * (input) An ASL client handle
- */
-void asl_close(aslclient asl);
-
-/*!
- * 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);
-
-/*!
- * 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.
- * 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 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);
-
-/*
- * 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);
-
-/*!
- * 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);
-
-/*!
- * 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);
-
-/*!
- * 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);
-
-/*!
- * 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);
-
-/*!
- * 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_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, ...) __printflike(4, 5);
-#endif
-
-/*!
- * 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_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) __printflike(4, 0);
-#endif
-
-/*!
- * 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 client handle
- * @param msg
- * (input) An aslmsg
- * @result Returns 0 for success, non-zero for failure
- */
-int asl_send(aslclient asl, aslmsg msg);
-
-/*!
- * Free a message. Frees all the attribute keys and values.
- *
- * @param msg
- * (input) An aslmsg to free
- */
-void asl_free(aslmsg msg);
-
-/*!
- * 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 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);
-
-/*!
- * 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);
-
-/*!
- * 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);
-
-/*!
- * Free a response returned from asl_search().
- * @param r
- * (input) An aslresponse returned by asl_search()
- */
-void aslresponse_free(aslresponse r);
-
-/*!
- * 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_fd 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 aslmsg
- * @param tite
- * (input) A title string for the file
- * @param uti
- * (input) Uniform Type Identifier for the file
- * @param out_fd
- * (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_fd)
-__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 fd
- * (input) The file descriptor
- * @result Returns 0 for success, non-zero for failure
- */
-int asl_close_auxiliary_file(int fd)
-__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 aslmsg
- * @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(aslmsg msg, const char *title, const char *uti, const char *url)
-__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_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.
- *
- * 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.
- *
- * The returned aslclient is thread-safe.
- *
- * 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.
- *
- * @param fd
- * (input) A file descriptor
- * @param ident
- * (input) Sender name
- * @param facility
- * (input) Facility name
- * @result An aslclient
- */
-aslclient asl_open_from_file(int fd, const char *ident, const char *facility)
-__OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0);
-
-__END_DECLS
-
-#endif /* __ASL_H__ */