include/asl.h

   1 /*
   2  * Copyright (c) 2004 - 2007 Apple 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 /*! @header
  37  * These routines provide an interface to the Apple System Log facility.
  38  * The API allows client applications to create flexible, structured messages
  39  * and send them to the syslogd server.  Messages received by the server are
  40  * saved in a data store, subject to input filtering constraints.
  41  * This API also permits clients to create queries and search the message
  42  * data store for matching messages.
  43  */
  44
  45 /*
  46  * NOTE FOR HeaderDoc
  47  *
  48  * These are added to allow headerdoc2html to process
  49  * the prototypes of asl_log and asl_vlog correctly.
  50  * The "-p" option to headerdoc2html is required.
  51  */
  52 #ifndef __DARWIN_LDBL_COMPAT2
  53 /*! @parseOnly */
  54 #define __DARWIN_LDBL_COMPAT2(a)
  55 #endif
  56 #ifndef __printflike
  57 /*! @parseOnly */
  58 #define __printflike(a,b)
  59 #endif
  60
  61 /*! @defineblock Log Message Priority Levels
  62  * Log levels of the message.
  63  */
  64 #define ASL_LEVEL_EMERG   0
  65 #define ASL_LEVEL_ALERT   1
  66 #define ASL_LEVEL_CRIT    2
  67 #define ASL_LEVEL_ERR     3
  68 #define ASL_LEVEL_WARNING 4
  69 #define ASL_LEVEL_NOTICE  5
  70 #define ASL_LEVEL_INFO    6
  71 #define ASL_LEVEL_DEBUG   7
  72 /*! @/defineblock */
  73
  74 /*! @defineblock Log Message Priority Level Strings
  75  * Strings corresponding to log levels.
  76  */
  77 #define ASL_STRING_EMERG        "Emergency"
  78 #define ASL_STRING_ALERT        "Alert"
  79 #define ASL_STRING_CRIT         "Critical"
  80 #define ASL_STRING_ERR          "Error"
  81 #define ASL_STRING_WARNING  "Warning"
  82 #define ASL_STRING_NOTICE   "Notice"
  83 #define ASL_STRING_INFO         "Info"
  84 #define ASL_STRING_DEBUG        "Debug"
  85 /*! @/defineblock */
  86
  87 /*! @defineblock Attribute Matching
  88  * Attribute value comparison operations.
  89  */
  90 #define ASL_QUERY_OP_CASEFOLD      0x0010
  91 #define ASL_QUERY_OP_PREFIX                0x0020
  92 #define ASL_QUERY_OP_SUFFIX                0x0040
  93 #define ASL_QUERY_OP_SUBSTRING     0x0060
  94 #define ASL_QUERY_OP_NUMERIC       0x0080
  95 #define ASL_QUERY_OP_REGEX         0x0100
  96
  97 #define ASL_QUERY_OP_EQUAL         0x0001
  98 #define ASL_QUERY_OP_GREATER       0x0002
  99 #define ASL_QUERY_OP_GREATER_EQUAL 0x0003
 100 #define ASL_QUERY_OP_LESS          0x0004
 101 #define ASL_QUERY_OP_LESS_EQUAL    0x0005
 102 #define ASL_QUERY_OP_NOT_EQUAL     0x0006
 103 #define ASL_QUERY_OP_TRUE          0x0007
 104 /*! @/defineblock */
 105
 106 /*! @defineblock Message Attributes
 107  *
 108  * These attributes are known by ASL, and are generally
 109  * associated with all log messages.
 110  * Additional attributes may be added as desired.
 111  */
 112 #define ASL_KEY_TIME        "Time"          /* Timestamp.  Set automatically */
 113 #define ASL_KEY_TIME_NSEC   "TimeNanoSec"   /* Nanosecond time. */
 114 #define ASL_KEY_HOST        "Host"          /* Sender's address (set by the server). */
 115 #define ASL_KEY_SENDER      "Sender"        /* Sender's identification string.  Default is process name. */
 116 #define ASL_KEY_FACILITY    "Facility"      /* Sender's facility.  Default is "user". */
 117 #define ASL_KEY_PID         "PID"           /* Sending process ID encoded as a string.  Set automatically. */
 118 #define ASL_KEY_UID         "UID"           /* UID that sent the log message (set by the server). */
 119 #define ASL_KEY_GID         "GID"           /* GID that sent the log message (set by the server). */
 120 #define ASL_KEY_LEVEL       "Level"         /* Log level number encoded as a string.  See levels above. */
 121 #define ASL_KEY_MSG         "Message"       /* Message text. */
 122 #define ASL_KEY_READ_UID    "ReadUID"       /* User read access (-1 is any group). */
 123 #define ASL_KEY_READ_GID    "ReadGID"       /* Group read access (-1 is any group). */
 124 #define ASL_KEY_EXPIRE_TIME "ASLExpireTime" /* Expiration time for messages with long TTL. */
 125 #define ASL_KEY_MSG_ID      "ASLMessageID"  /* 64-bit message ID number (set by the server). */
 126 #define ASL_KEY_SESSION     "Session"       /* Session (set by the launchd). */
 127 #define ASL_KEY_REF_PID     "RefPID"        /* Reference PID for messages proxied by launchd */
 128 #define ASL_KEY_REF_PROC    "RefProc"       /* Reference process for messages proxied by launchd */
 129 /*! @/defineblock */
 130
 131 /*! @defineblock aslmsg Types
 132  * Message type argument passed to asl_new().
 133  */
 134 #define ASL_TYPE_MSG    0
 135 #define ASL_TYPE_QUERY  1
 136 /*! @/defineblock */
 137
 138 /*! @defineblock Filter Masks
 139  * Used in client-side filtering, which determines which
 140  * messages are sent by the client to the syslogd server.
 141  */
 142 #define ASL_FILTER_MASK_EMERG   0x01
 143 #define ASL_FILTER_MASK_ALERT   0x02
 144 #define ASL_FILTER_MASK_CRIT    0x04
 145 #define ASL_FILTER_MASK_ERR     0x08
 146 #define ASL_FILTER_MASK_WARNING 0x10
 147 #define ASL_FILTER_MASK_NOTICE  0x20
 148 #define ASL_FILTER_MASK_INFO    0x40
 149 #define ASL_FILTER_MASK_DEBUG   0x80
 150 /*! @/defineblock */
 151
 152 /*! @defineblock Filter Mask Macros
 153  * Macros to create bitmasks for filter settings - see asl_set_filter().
 154  */
 155 #define ASL_FILTER_MASK(level) (1 << (level))
 156 #define ASL_FILTER_MASK_UPTO(level) ((1 << ((level) + 1)) - 1)
 157 /*! @/defineblock */
 158
 159 /*! @defineblock Client Creation Options
 160  * Options for asl_open().
 161  */
 162 #define ASL_OPT_STDERR          0x00000001
 163 #define ASL_OPT_NO_DELAY    0x00000002
 164 #define ASL_OPT_NO_REMOTE   0x00000004
 165 /*! @/defineblock */
 166
 167 __BEGIN_DECLS
 168
 169 /*!
 170  * Initialize a connection to the ASL server.
 171  *
 172  * This call is optional in most cases.  The library will perform any
 173  * necessary initializations on the fly.  A call to asl_open() is required
 174  * if optional settings must be made before messages are sent to the server.
 175  * These include setting the client filter and managing additional output
 176  * file descriptors.  Note that the default setting of the client filter is
 177  * ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE), so ASL_LEVEL_DEBUG and ASL_LEVEL_INFO
 178  * messages are not sent to the server by default.
 179  *
 180  * Options (defined above) may be set using the opts parameter. They are:
 181  *
 182  *   ASL_OPT_STDERR    - adds stderr as an output file descriptor
 183  *
 184  *   ASL_OPT_NO_DELAY  - connects to the server immediately
 185  *
 186  *   ASL_OPT_NO_REMOTE - disables the remote-control mechanism for adjusting
 187  *                       filter levers for processes using e.g. syslog -c ...
 188  *
 189  * @param ident
 190  *    (input) Sender name
 191  * @param facility
 192  *    (input) Facility name
 193  * @param opts
 194  *    (input) Options (see asl_open Options)
 195  * @result Returns an ASL client handle
 196  */
 197 aslclient asl_open(const char *ident, const char *facility, uint32_t opts);
 198
 199 /*!
 200  * Shuts down a connection to the server.
 201  *
 202  * @param asl
 203  *    (input) An ASL client handle
 204  */
 205 void asl_close(aslclient asl);
 206
 207 /*!
 208  * Write log messages to the given file descriptor.
 209  *
 210  * Log messages will be written to this file as well as to the server.
 211  *
 212  * @param asl
 213  *    (input) An ASL client handle
 214  * @param fd
 215  *    (input) A file descriptor
 216  * @result Returns 0 on success, non-zero on failure
 217 */
 218 int asl_add_log_file(aslclient asl, int fd);
 219
 220 /*!
 221  * Stop writing log messages to the given file descriptor.
 222  * The file descripter is not closed by this routine.
 223  *
 224  * @param asl
 225  *    (input) An ASL client handle
 226  * @param fd
 227  *    (input) A file descriptor
 228  * @result Returns 0 on success, non-zero on failure
 229  */
 230 int asl_remove_log_file(aslclient asl, int fd);
 231
 232 /*!
 233  * Set a filter for messages being sent to the server.
 234  * The filter is a bitmask representing priorities.  The ASL_FILTER_MASK
 235  * macro may be used to convert a priority level into a bitmask for that
 236  * level.  The ASL_FILTER_MASK_UPTO macro creates a bitmask for all
 237  * priorities up to and including a given priority.
 238  * Messages with priority levels that do not have a corresponding bit
 239  * set in the filter are not sent to the server, although they will be
 240  * sent to any file descripters added with asl_add_log_file().
 241  * The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
 242  * Returns the previous filter value.
 243  *
 244  * @param asl
 245  *    (input) An ASL client handle
 246  * @param f
 247  *    (input) A filter value
 248  * @result Returns the previous filter value
 249  */
 250 int asl_set_filter(aslclient asl, int f);
 251
 252 /*
 253  * Examine attribute keys.
 254  *
 255  * @param msg
 256  *    (input) An ASL message
 257  * @param n
 258  *    (input) An index value
 259  * @result Returns the key of the nth attribute in a message (beginning at zero),
 260  * or NULL if n is greater than the largest message index.
 261  */
 262 const char *asl_key(aslmsg msg, uint32_t n);
 263
 264 /*!
 265  * Create a new log message or query message.
 266  *
 267  * @param type
 268  *    (input) Message type (see aslmsg Types)
 269  * @result Returns a newly allocated asmsg of the specified type
 270  */
 271 aslmsg asl_new(uint32_t type);
 272
 273 /*!
 274  * Set or re-set a message attribute.
 275  *
 276  * @param msg
 277  *    (input) An aslmsg
 278  * @param key
 279  *    (input) Attribute key
 280  * @param value
 281  *    (input) Attribute value
 282  * @result returns 0 for success, non-zero for failure
 283  */
 284 int asl_set(aslmsg msg, const char *key, const char *value);
 285
 286 /*!
 287  * Remove a message attribute.
 288  *
 289  * @param msg
 290  *    (input) An aslmsg
 291  * @param key
 292  *    (input) Attribute key
 293  * returns 0 for success, non-zero for failure
 294  */
 295 int asl_unset(aslmsg msg, const char *key);
 296
 297 /*!
 298  * Get the value of a message attribute.
 299  *
 300  * @param msg
 301  *    (input) An aslmsg
 302  * @param key
 303  *    (input) Attribute key
 304  * @result Returns the attribute value, or NULL if the message does not contain the key
 305  */
 306 const char *asl_get(aslmsg msg, const char *key);
 307
 308 /*!
 309  * Log a message with a particular log level.
 310  *
 311  * @param asl
 312  *    (input) An ASL client handle
 313  * @param msg
 314  *    (input) An aslmsg (default attributes will be supplied if msg is NULL)
 315  * @param level
 316  *    (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG)
 317  * @param format
 318  *    (input) A printf() - style format string followed by a list of arguments
 319  * @result Returns 0 for success, non-zero for failure
 320  */
 321 #ifdef __DARWIN_LDBL_COMPAT2
 322 int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __DARWIN_LDBL_COMPAT2(asl_log) __printflike(4, 5);
 323 #else
 324 int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __printflike(4, 5);
 325 #endif
 326
 327 /*!
 328  * Log a message with a particular log level.
 329  * Similar to asl_log, but takes a va_list argument.
 330  *
 331  * @param asl
 332  *    (input) An ASL client handle
 333  * @param msg
 334  *    (input) An aslmsg (default attributes will be supplied if msg is NULL)
 335  * @param level
 336  *    (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG)
 337  * @param format
 338  *    (input) A printf() - style format string followed by a list of arguments
 339  * @param ap
 340  *    (input) A va_list containing the values for the format string
 341  * @result Returns 0 for success, non-zero for failure
 342  */
 343 #ifdef __DARWIN_LDBL_COMPAT2
 344 int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __DARWIN_LDBL_COMPAT2(asl_vlog) __printflike(4, 0);
 345 #else
 346 int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __printflike(4, 0);
 347 #endif
 348
 349 /*!
 350  * Log a message.
 351  *
 352  * This routine may be used instead of asl_log() or asl_vlog() if asl_set()
 353  * has been used to set all of a message's attributes.
 354  *
 355  * @param asl
 356  *    (input) An ASL client handle
 357  * @param msg
 358  *    (input) An aslmsg
 359  * @result Returns 0 for success, non-zero for failure
 360  */
 361 int asl_send(aslclient asl, aslmsg msg);
 362
 363 /*!
 364  * Free a message.  Frees all the attribute keys and values.
 365  *
 366  * @param msg
 367  *    (input) An aslmsg to free
 368  */
 369 void asl_free(aslmsg msg);
 370
 371 /*!
 372  * Set arbitrary parameters of a query.
 373  * This is similar to asl_set, but allows richer query operations.
 374  * See ASL_QUERY_OP_* above.
 375  *
 376  * @param msg
 377  *    (input) An aslmsg
 378  * @param key
 379  *    (input) Attribute key
 380  * @param value
 381  *    (input) Attribute value
 382  * @param op
 383  *    (input) An operation (ASL_QUERY_OP_*)
 384  * @result Returns 0 for success, non-zero for failure
 385  */
 386 int asl_set_query(aslmsg msg, const char *key, const char *value, uint32_t op);
 387
 388 /*!
 389  * Search for messages matching the criteria described by the aslmsg.
 390  * The caller should set the attributes to match using asl_set_query() or asl_set().
 391  * The operatoin ASL_QUERY_OP_EQUAL is used for attributes set with asl_set().
 392  *
 393  * @param msg
 394  *    (input) An aslmsg to match
 395  * @result Returns a set of messages accessable using aslresponse_next(),
 396  */
 397 aslresponse asl_search(aslclient asl, aslmsg msg);
 398
 399 /*!
 400  * Iterate over responses returned from asl_search().
 401  *
 402  * @param r
 403  *    (input) An aslresponse returned by asl_search()
 404  * @result Returns the next message (an aslmsg) in the response, or NULL when there are no more messages
 405  */
 406 aslmsg aslresponse_next(aslresponse r);
 407
 408 /*!
 409  * Free a response returned from asl_search().
 410  * @param r
 411  *    (input) An aslresponse returned by asl_search()
 412  */
 413 void aslresponse_free(aslresponse r);
 414
 415 __END_DECLS
 416
 417 #endif /* __ASL_H__ */