include/asl.h

   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_FACILITY  "Facility" /* Sender's facility.  Default is "user". */
  89 #define ASL_KEY_PID       "PID"      /* Sending process ID encoded as a string.  Set automatically */
  90 #define ASL_KEY_UID       "UID"      /* UID that sent the log message (set by the server) */
  91 #define ASL_KEY_GID       "GID"      /* GID that sent the log message (set by the server) */
  92 #define ASL_KEY_LEVEL     "Level"    /* Log level number encoded as a string.  See levels above */
  93 #define ASL_KEY_MSG       "Message"  /* Actual message that will be logged */
  94
  95 /*
  96  * Message Types
  97  */
  98 #define ASL_TYPE_MSG    0
  99 #define ASL_TYPE_QUERY  1
 100
 101 /* Macros to create bitmasks for filter settings - see asl_set_filter */
 102 #define ASL_FILTER_MASK(level) (1 << (level))
 103 #define ASL_FILTER_MASK_UPTO(level) ((1 << ((level) + 1)) - 1)
 104
 105 /* Individual filter masks */
 106 #define ASL_FILTER_MASK_EMERG   0x01
 107 #define ASL_FILTER_MASK_ALERT   0x02
 108 #define ASL_FILTER_MASK_CRIT    0x04
 109 #define ASL_FILTER_MASK_ERR     0x08
 110 #define ASL_FILTER_MASK_WARNING 0x10
 111 #define ASL_FILTER_MASK_NOTICE  0x20
 112 #define ASL_FILTER_MASK_INFO    0x40
 113 #define ASL_FILTER_MASK_DEBUG   0x80
 114
 115 /* Options to asl_open */
 116 #define ASL_OPT_STDERR          0x00000001
 117 #define ASL_OPT_NO_DELAY    0x00000002
 118 #define ASL_OPT_NO_REMOTE   0x00000004
 119
 120 __BEGIN_DECLS
 121
 122 /*
 123  * asl_open: initialize a syslog connection
 124  * This call is optional in most cases.  The library will perform any
 125  * necessary initializations on the fly.  A call to asl_open() is required
 126  * if optional settings must be made before messages are sent to the server.
 127  * These include setting the client filter and managing additional output
 128  * file descriptors.  Note that the default setting of the client filter is
 129  * ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE), so ASL_LEVEL_DEBUG and ASL_LEVEL_INFO
 130  * messages are not sent to the server by default.
 131  *
 132  * Options (defined above) may be set using the opts parameter. They are:
 133  *   ASL_OPT_STDERR    - adds stderr as an output file descriptor
 134  *   ASL_OPT_NO_DELAY  - connects to the server immediately
 135  *   ASL_OPT_NO_REMOTE - disables the remote-control mechanism for adjusting
 136  *                       filter levers for processes using e.g. syslog -c ...
 137  */
 138 aslclient asl_open(const char *ident, const char *facility, uint32_t opts);
 139
 140 /*
 141  * Shuts down the current connection to the server.
 142  */
 143 void asl_close(aslclient asl);
 144
 145 /*
 146  * asl_add_file: write log messages to the given file descriptor
 147  * Log messages will be written to this file as well as to the server.
 148  */
 149 int asl_add_log_file(aslclient asl, int fd);
 150
 151 /*
 152  * asl_remove_file: stop writing log messages to the given file descriptor
 153  * The file descripter is not closed by this routine.
 154  */
 155 int asl_remove_log_file(aslclient asl, int fd);
 156
 157 /*
 158  * Set a filter for messages being sent to the server
 159  * The filter is a bitmask representing priorities.  The ASL_FILTER_MASK
 160  * macro may be used to convert a priority level into a bitmask for that
 161  * level.  The ASL_FILTER_MASK_UPTO macro creates a bitmask for all
 162  * priorities up to and including a given priority.
 163  * Messages with priority levels that do not have a corresponding bit
 164  * set in the filter are not sent to the server, although they will be
 165  * sent to any file descripters added with asl_add_log_file().
 166  * The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
 167  * Returns the previous filter value.
 168  */
 169 int asl_set_filter(aslclient asl, int f);
 170
 171 /*
 172  * asl_key: examine attribute keys
 173  * returns the key of the nth attribute in a message (beginning at zero)
 174  * returns NULL if the message has fewer attributes
 175  */
 176 const char *asl_key(aslmsg msg, uint32_t n);
 177
 178 /*
 179  * asl_new: create a new log message.
 180  */
 181 aslmsg asl_new(uint32_t type);
 182
 183 /*
 184  * asl_set: set attributes of a message
 185  * msg:  an aslmsg
 186  * key:  attribute key
 187  * value:  attribute value
 188  * returns 0 for success, non-zero for failure
 189  */
 190 int asl_set(aslmsg msg, const char *key, const char *value);
 191
 192 /*
 193  * asl_unset: remove attributes of a message
 194  * msg:  an aslmsg
 195  * key:  attribute key
 196  * returns 0 for success, non-zero for failure
 197  */
 198 int asl_unset(aslmsg msg, const char *key);
 199
 200 /*
 201  * asl_get: get attribute values from a message
 202  * msg:  an aslmsg
 203  * key:  attribute key
 204  * returns the attribute value
 205  * returns NULL if the message does not contain the key
 206  */
 207 const char *asl_get(aslmsg msg, const char *key);
 208
 209 /*
 210  * asl_log: log a message with a particular log level
 211  * msg:  an aslmsg
 212  *       msg may be NULL, in which case a new message will be
 213  *       created and sent using default attributes.
 214  * level: the log level
 215  * format: A formating string followed by a list of arguments, like printf()
 216  * returns 0 for success, non-zero for failure
 217  */
 218 #ifdef __DARWIN_LDBL_COMPAT2
 219 int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __DARWIN_LDBL_COMPAT2(asl_log) __printflike(4, 5);
 220 #else
 221 int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __printflike(4, 5);
 222 #endif
 223
 224 /*
 225  * asl_vlog: Similar to asl_log, but taking a va_list instead of a list of
 226  * arguments.
 227  * msg:  an aslmsg
 228  *       msg may be NULL, in which case a new message will be
 229  *       created and sent using default attributes.
 230  * level: the log level of the associated message
 231  * format: A formating string followed by a list of arguments, like vprintf()
 232  * returns 0 for success, non-zero for failure
 233  */
 234 #ifdef __DARWIN_LDBL_COMPAT2
 235 int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __DARWIN_LDBL_COMPAT2(asl_vlog) __printflike(4, 0);
 236 #else
 237 int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __printflike(4, 0);
 238 #endif
 239
 240 /*
 241  * asl_send: send a message
 242  * This routine may be used instead of asl_log() or asl_vlog() if asl_set()
 243  * has been used to set all of a message's attributes.
 244  * msg:  an aslmsg
 245  * returns 0 for success, non-zero for failure
 246  */
 247 int asl_send(aslclient asl, aslmsg msg);
 248
 249 /*
 250  * asl_free: free a message
 251  * msg:  an aslmsg to free
 252  */
 253 void asl_free(aslmsg msg);
 254
 255 /*
 256  * asl_set_query: set arbitrary parameters of a query
 257  * Similar to als_set, but allows richer query operations.
 258  * See ASL_QUERY_OP_* above.
 259  * msg:  an aslmsg
 260  * key:  attribute key
 261  * value:  attribute value
 262  * op:  an operation from the set above.
 263  * returns 0 for success, non-zero for failure
 264  */
 265 int asl_set_query(aslmsg msg, const char *key, const char *value, uint32_t op);
 266
 267 /*
 268  * asl_search: Search for messages matching the criteria described
 269  * by the aslmsg .  The caller should set the attributes to match using
 270  * asl_set_query() or asl_set().  The operatoin ASL_QUERY_OP_EQUAL is
 271  * used for attributes set with asl_set().
 272  * a:  an aslmsg
 273  * returns: a set of messages that can be iterated over using aslresp_next(),
 274  * and the values can be retrieved using aslresp_get.
 275  */
 276 aslresponse asl_search(aslclient asl, aslmsg msg);
 277
 278 /*
 279  * aslresponse_next: Iterate over responses returned from asl_search()
 280  * a: a response returned from asl_search();
 281  * returns: The next log message (an aslmsg) or NULL on failure
 282  */
 283 aslmsg aslresponse_next(aslresponse r);
 284
 285 /*
 286  * aslresponse_free: Free a response returned from asl_search()
 287  * a: a response returned from asl_search()
 288  */
 289 void aslresponse_free(aslresponse a);
 290
 291 __END_DECLS
 292
 293 #endif /* __ASL_H__ */