[apple/libc.git] / include / asl.h

/*
 * Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * "Portions Copyright (c) 2004 Apple Computer, Inc.  All Rights
 * Reserved.  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 1.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.apple.com/publicsource 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 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>

typedef struct __aslclient *aslclient;
typedef struct __aslmsg *aslmsg;
typedef struct __aslresponse *aslresponse;

/*
 * 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

/*
 * Corresponding level strings
 */
#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"

/*
 * 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

/* 
 * 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.
 */
#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_TYPE_MSG    0
#define ASL_TYPE_QUERY  1

/* 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 */
#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

/* Options to asl_open */
#define ASL_OPT_STDERR		0x00000001
#define ASL_OPT_NO_DELAY    0x00000002
#define ASL_OPT_NO_REMOTE   0x00000004

__BEGIN_DECLS

/*
 * asl_open: initialize a syslog connection
 * 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 ...
 */
aslclient asl_open(const char *ident, const char *facility, uint32_t opts);

/*
 * Shuts down the current connection to the server.
 */
void asl_close(aslclient asl);

/*
 * asl_add_file: write log messages to the given file descriptor
 * Log messages will be written to this file as well as to the server.
 */
int asl_add_log_file(aslclient asl, int fd);

/*
 * asl_remove_file: stop writing log messages to the given file descriptor
 * The file descripter is not closed by this routine.
 */
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).
 */
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
 */
const char *asl_key(aslmsg msg, uint32_t n);

/*
 * asl_new: create a new log message.
 */
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
 */
int asl_set(aslmsg msg, const char *key, const char *value);

/*
 * asl_unset: remove attributes of a message 
 * msg:  an aslmsg
 * key:  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
 */
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
 */
#ifdef __DARWIN_LDBL_COMPAT2
int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __DARWIN_LDBL_COMPAT2(asl_log);
#else
int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...);
#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
 */
#ifdef __DARWIN_LDBL_COMPAT2
int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __DARWIN_LDBL_COMPAT2(asl_vlog);
#else
int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap);
#endif

/*
 * asl_send: send 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
 */
int asl_send(aslclient asl, aslmsg msg);

/*
 * asl_free: free a message 
 * msg:  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.
 * 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
 */
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.
 */
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
 */
aslmsg aslresponse_next(aslresponse r);

/*
 * aslresponse_free: Free a response returned from asl_search() 
 * a: a response returned from asl_search()
 */
void aslresponse_free(aslresponse a);

__END_DECLS

#endif /* __ASL_H__ */
Commit	Line	Data
3d9156a7 A	1	/*
	2	* Copyright (c) 2004 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* "Portions Copyright (c) 2004 Apple Computer, Inc. All Rights
	7	* Reserved. This file contains Original Code and/or Modifications of
	8	* Original Code as defined in and that are subject to the Apple Public
	9	* Source License Version 1.0 (the 'License'). You may not use this file
	10	* except in compliance with the License. Please obtain a copy of the
	11	* License at http://www.apple.com/publicsource and read it before using
	12	* this file.
	13	*
	14	* The Original Code and all software distributed under the License are
	15	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	16	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	17	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	18	* FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
	19	* License for the specific language governing rights and limitations
	20	* under the License."
	21	*
	22	* @APPLE_LICENSE_HEADER_END@
	23	*/
	24
	25	#ifndef __ASL_H__
	26	#define __ASL_H__
	27
	28	#include <stdint.h>
	29	#include <stdarg.h>
	30	#include <sys/cdefs.h>
	31
	32	typedef struct __aslclient *aslclient;
	33	typedef struct __aslmsg *aslmsg;
	34	typedef struct __aslresponse *aslresponse;
	35
	36	/*
	37	* Log levels of the message
	38	*/
	39	#define ASL_LEVEL_EMERG 0
	40	#define ASL_LEVEL_ALERT 1
	41	#define ASL_LEVEL_CRIT 2
	42	#define ASL_LEVEL_ERR 3
	43	#define ASL_LEVEL_WARNING 4
	44	#define ASL_LEVEL_NOTICE 5
	45	#define ASL_LEVEL_INFO 6
	46	#define ASL_LEVEL_DEBUG 7
	47
	48	/*
	49	* Corresponding level strings
	50	*/
	51	#define ASL_STRING_EMERG "Emergency"
	52	#define ASL_STRING_ALERT "Alert"
	53	#define ASL_STRING_CRIT "Critical"
	54	#define ASL_STRING_ERR "Error"
	55	#define ASL_STRING_WARNING "Warning"
	56	#define ASL_STRING_NOTICE "Notice"
	57	#define ASL_STRING_INFO "Info"
	58	#define ASL_STRING_DEBUG "Debug"
	59
	60	/*
	61	* Attribute value comparison operations
	62	*/
	63	#define ASL_QUERY_OP_CASEFOLD 0x0010
	64	#define ASL_QUERY_OP_PREFIX 0x0020
65	#define ASL_QUERY_OP_SUFFIX 0x0040
66	#define ASL_QUERY_OP_SUBSTRING 0x0060
67	#define ASL_QUERY_OP_NUMERIC 0x0080
68	#define ASL_QUERY_OP_REGEX 0x0100
69
70	#define ASL_QUERY_OP_EQUAL 0x0001
71	#define ASL_QUERY_OP_GREATER 0x0002
72	#define ASL_QUERY_OP_GREATER_EQUAL 0x0003
73	#define ASL_QUERY_OP_LESS 0x0004
74	#define ASL_QUERY_OP_LESS_EQUAL 0x0005
75	#define ASL_QUERY_OP_NOT_EQUAL 0x0006
76	#define ASL_QUERY_OP_TRUE 0x0007
77
78	/*
79	* Attributes of all messages.
80	* The following attributes are attached to log messages,
81	* and are preserved in the order listed.
82	* Additional attributes may be added as desired, and are
83	* appended in the order that they are defined.
84	*/
85	#define ASL_KEY_TIME "Time" /* Timestamp (see ctime(3)). Set automatically */
86	#define ASL_KEY_HOST "Host" /* Sender's address (set by the server) */
87	#define ASL_KEY_SENDER "Sender" /* Sender's identification string. Default is process name */
88	#define ASL_KEY_PID "PID" /* Sending process ID encoded as a string. Set automatically */
89	#define ASL_KEY_UID "UID" /* UID that sent the log message (set by the server) */
90	#define ASL_KEY_GID "GID" /* GID that sent the log message (set by the server) */
91	#define ASL_KEY_LEVEL "Level" /* Log level number encoded as a string. See levels above */
92	#define ASL_KEY_MSG "Message" /* Actual message that will be logged */
93
94	/*
95	* Message Types
96	*/
97	#define ASL_TYPE_MSG 0
98	#define ASL_TYPE_QUERY 1
99
100	/* Macros to create bitmasks for filter settings - see asl_set_filter */
101	#define ASL_FILTER_MASK(level) (1 << (level))
102	#define ASL_FILTER_MASK_UPTO(level) ((1 << ((level) + 1)) - 1)
103
104	/* Individual filter masks */
105	#define ASL_FILTER_MASK_EMERG 0x01
106	#define ASL_FILTER_MASK_ALERT 0x02
107	#define ASL_FILTER_MASK_CRIT 0x04
108	#define ASL_FILTER_MASK_ERR 0x08
109	#define ASL_FILTER_MASK_WARNING 0x10
110	#define ASL_FILTER_MASK_NOTICE 0x20
111	#define ASL_FILTER_MASK_INFO 0x40
112	#define ASL_FILTER_MASK_DEBUG 0x80
113
114	/* Options to asl_open */
115	#define ASL_OPT_STDERR 0x00000001
116	#define ASL_OPT_NO_DELAY 0x00000002
117	#define ASL_OPT_NO_REMOTE 0x00000004
118
119	__BEGIN_DECLS
120
121	/*
122	* asl_open: initialize a syslog connection
123	* This call is optional in most cases. The library will perform any
124	* necessary initializations on the fly. A call to asl_open() is required
125	* if optional settings must be made before messages are sent to the server.
126	* These include setting the client filter and managing additional output
127	* file descriptors. Note that the default setting of the client filter is
128	* ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE), so ASL_LEVEL_DEBUG and ASL_LEVEL_INFO
129	* messages are not sent to the server by default.
130	*
131	* Options (defined above) may be set using the opts parameter. They are:
132	* ASL_OPT_STDERR - adds stderr as an output file descriptor
133	* ASL_OPT_NO_DELAY - connects to the server immediately
134	* ASL_OPT_NO_REMOTE - disables the remote-control mechanism for adjusting
135	* filter levers for processes using e.g. syslog -c ...
136	*/
137	aslclient asl_open(const char ident, const char facility, uint32_t opts);
138
139	/*
140	* Shuts down the current connection to the server.
141	*/
142	void asl_close(aslclient asl);
143
144	/*
145	* asl_add_file: write log messages to the given file descriptor
146	* Log messages will be written to this file as well as to the server.
147	*/
148	int asl_add_log_file(aslclient asl, int fd);
149
150	/*
151	* asl_remove_file: stop writing log messages to the given file descriptor
152	* The file descripter is not closed by this routine.
153	*/
154	int asl_remove_log_file(aslclient asl, int fd);
155
156	/*
157	* Set a filter for messages being sent to the server
158	* The filter is a bitmask representing priorities. The ASL_FILTER_MASK
159	* macro may be used to convert a priority level into a bitmask for that
160	* level. The ASL_FILTER_MASK_UPTO macro creates a bitmask for all
161	* priorities up to and including a given priority.
162	* Messages with priority levels that do not have a corresponding bit
163	* set in the filter are not sent to the server, although they will be
164	* sent to any file descripters added with asl_add_log_file().
165	* The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
166	*/
167	int asl_set_filter(aslclient asl, int f);
168
169	/*
170	* asl_key: examine attribute keys
171	* returns the key of the nth attribute in a message (beginning at zero)
172	* returns NULL if the message has fewer attributes
173	*/
174	const char *asl_key(aslmsg msg, uint32_t n);
175
176	/*
177	* asl_new: create a new log message.
178	*/
179	aslmsg asl_new(uint32_t type);
180
181	/*
182	* asl_set: set attributes of a message
183	* msg: an aslmsg
184	* key: attribute key
185	* value: attribute value
186	* returns 0 for success, non-zero for failure
187	*/
188	int asl_set(aslmsg msg, const char key, const char value);
189
190	/*
191	* asl_unset: remove attributes of a message
192	* msg: an aslmsg
193	* key: attribute key
194	* returns 0 for success, non-zero for failure
195	*/
196	int asl_unset(aslmsg msg, const char *key);
197
198	/*
199	* asl_get: get attribute values from a message
200	* msg: an aslmsg
201	* key: attribute key
202	* returns the attribute value
203	* returns NULL if the message does not contain the key
204	*/
205	const char asl_get(aslmsg msg, const char key);
206
207	/*
208	* asl_log: log a message with a particular log level
209	* msg: an aslmsg
210	* msg may be NULL, in which case a new message will be
211	* created and sent using default attributes.
212	* level: the log level
213	* format: A formating string followed by a list of arguments, like printf()
214	* returns 0 for success, non-zero for failure
215	*/
7c78c529 A	216	#ifdef __DARWIN_LDBL_COMPAT2
7c78c529 A	217	int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __DARWIN_LDBL_COMPAT2(asl_log);
3d9156a7 A	218	#else
	219	int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...);
	220	#endif
	221
	222	/*
	223	* asl_vlog: Similar to asl_log, but taking a va_list instead of a list of
	224	* arguments.
	225	* msg: an aslmsg
	226	* msg may be NULL, in which case a new message will be
	227	* created and sent using default attributes.
	228	* level: the log level of the associated message
	229	* format: A formating string followed by a list of arguments, like vprintf()
	230	* returns 0 for success, non-zero for failure
	231	*/
7c78c529 A	232	#ifdef __DARWIN_LDBL_COMPAT2
7c78c529 A	233	int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __DARWIN_LDBL_COMPAT2(asl_vlog);
3d9156a7 A	234	#else
	235	int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap);
	236	#endif
	237
	238	/*
	239	* asl_send: send a message
	240	* This routine may be used instead of asl_log() or asl_vlog() if asl_set()
	241	* has been used to set all of a message's attributes.
	242	* msg: an aslmsg
	243	* returns 0 for success, non-zero for failure
	244	*/
	245	int asl_send(aslclient asl, aslmsg msg);
	246
	247	/*
	248	* asl_free: free a message
	249	* msg: an aslmsg to free
	250	*/
	251	void asl_free(aslmsg msg);
	252
	253	/*
	254	* asl_set_query: set arbitrary parameters of a query
	255	* Similar to als_set, but allows richer query operations.
	256	* See ASL_QUERY_OP_* above.
	257	* msg: an aslmsg
	258	* key: attribute key
	259	* value: attribute value
	260	* op: an operation from the set above.
	261	* returns 0 for success, non-zero for failure
	262	*/
	263	int asl_set_query(aslmsg msg, const char key, const char value, uint32_t op);
	264
	265	/*
	266	* asl_search: Search for messages matching the criteria described
	267	* by the aslmsg . The caller should set the attributes to match using
	268	* asl_set_query() or asl_set(). The operatoin ASL_QUERY_OP_EQUAL is
	269	* used for attributes set with asl_set().
	270	* a: an aslmsg
	271	* returns: a set of messages that can be iterated over using aslresp_next(),
	272	* and the values can be retrieved using aslresp_get.
	273	*/
	274	aslresponse asl_search(aslclient asl, aslmsg msg);
	275
	276	/*
	277	* aslresponse_next: Iterate over responses returned from asl_search()
	278	* a: a response returned from asl_search();
	279	* returns: The next log message (an aslmsg) or NULL on failure
	280	*/
	281	aslmsg aslresponse_next(aslresponse r);
	282
	283	/*
	284	* aslresponse_free: Free a response returned from asl_search()
	285	* a: a response returned from asl_search()
	286	*/
	287	void aslresponse_free(aslresponse a);
	288
	289	__END_DECLS
	290
	291	#endif /* __ASL_H__ */