libsystem_asl.tproj/include/asl.h

   1 /*
   2  * Copyright (c) 2004-2012 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef __ASL_H__
  25 #define __ASL_H__
  26
  27 #include <stdint.h>
  28 #include <stdarg.h>
  29 #include <sys/cdefs.h>
  30 #include <Availability.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 __printflike
  53 /*! @parseOnly */
  54 #define __printflike(a,b)
  55 #endif
  56
  57 /*! @defineblock Log Message Priority Levels
  58  * Log levels of the message.
  59  */
  60 #define ASL_LEVEL_EMERG   0
  61 #define ASL_LEVEL_ALERT   1
  62 #define ASL_LEVEL_CRIT    2
  63 #define ASL_LEVEL_ERR     3
  64 #define ASL_LEVEL_WARNING 4
  65 #define ASL_LEVEL_NOTICE  5
  66 #define ASL_LEVEL_INFO    6
  67 #define ASL_LEVEL_DEBUG   7
  68 /*! @/defineblock */
  69
  70 /*! @defineblock Log Message Priority Level Strings
  71  * Strings corresponding to log levels.
  72  */
  73 #define ASL_STRING_EMERG        "Emergency"
  74 #define ASL_STRING_ALERT        "Alert"
  75 #define ASL_STRING_CRIT         "Critical"
  76 #define ASL_STRING_ERR          "Error"
  77 #define ASL_STRING_WARNING  "Warning"
  78 #define ASL_STRING_NOTICE   "Notice"
  79 #define ASL_STRING_INFO         "Info"
  80 #define ASL_STRING_DEBUG        "Debug"
  81 /*! @/defineblock */
  82
  83 /*! @defineblock Attribute Matching
  84  * Attribute value comparison operations.
  85  */
  86 #define ASL_QUERY_OP_CASEFOLD      0x0010
  87 #define ASL_QUERY_OP_PREFIX                0x0020
  88 #define ASL_QUERY_OP_SUFFIX                0x0040
  89 #define ASL_QUERY_OP_SUBSTRING     0x0060
  90 #define ASL_QUERY_OP_NUMERIC       0x0080
  91 #define ASL_QUERY_OP_REGEX         0x0100
  92
  93 #define ASL_QUERY_OP_EQUAL         0x0001
  94 #define ASL_QUERY_OP_GREATER       0x0002
  95 #define ASL_QUERY_OP_GREATER_EQUAL 0x0003
  96 #define ASL_QUERY_OP_LESS          0x0004
  97 #define ASL_QUERY_OP_LESS_EQUAL    0x0005
  98 #define ASL_QUERY_OP_NOT_EQUAL     0x0006
  99 #define ASL_QUERY_OP_TRUE          0x0007
 100 /*! @/defineblock */
 101
 102 /*! @defineblock Message Attributes
 103  *
 104  * These attributes are known by ASL, and are generally
 105  * associated with all log messages.
 106  * Additional attributes may be added as desired.
 107  */
 108 #define ASL_KEY_TIME        "Time"          /* Timestamp.  Set automatically */
 109 #define ASL_KEY_TIME_NSEC   "TimeNanoSec"   /* Nanosecond time. */
 110 #define ASL_KEY_HOST        "Host"          /* Sender's address (set by the server). */
 111 #define ASL_KEY_SENDER      "Sender"        /* Sender's identification string.  Default is process name. */
 112 #define ASL_KEY_FACILITY    "Facility"      /* Sender's facility.  Default is "user". */
 113 #define ASL_KEY_PID         "PID"           /* Sending process ID encoded as a string.  Set automatically. */
 114 #define ASL_KEY_UID         "UID"           /* UID that sent the log message (set by the server). */
 115 #define ASL_KEY_GID         "GID"           /* GID that sent the log message (set by the server). */
 116 #define ASL_KEY_LEVEL       "Level"         /* Log level number encoded as a string.  See levels above. */
 117 #define ASL_KEY_MSG         "Message"       /* Message text. */
 118 #define ASL_KEY_READ_UID    "ReadUID"       /* User read access (-1 is any user). */
 119 #define ASL_KEY_READ_GID    "ReadGID"       /* Group read access (-1 is any group). */
 120 #define ASL_KEY_EXPIRE_TIME "ASLExpireTime" /* Expiration time for messages with long TTL. */
 121 #define ASL_KEY_MSG_ID      "ASLMessageID"  /* 64-bit message ID number (set by the server). */
 122 #define ASL_KEY_SESSION     "Session"       /* Session (set by the launchd). */
 123 #define ASL_KEY_REF_PID     "RefPID"        /* Reference PID for messages proxied by launchd */
 124 #define ASL_KEY_REF_PROC    "RefProc"       /* Reference process for messages proxied by launchd */
 125 #define ASL_KEY_AUX_TITLE   "ASLAuxTitle"   /* Auxiliary title string */
 126 #define ASL_KEY_AUX_UTI     "ASLAuxUTI"     /* Auxiliary Uniform Type ID */
 127 #define ASL_KEY_AUX_URL     "ASLAuxURL"     /* Auxiliary Uniform Resource Locator */
 128 #define ASL_KEY_AUX_DATA    "ASLAuxData"    /* Auxiliary in-line data */
 129 #define ASL_KEY_OPTION      "ASLOption"     /* Internal */
 130 #define ASL_KEY_SENDER_INSTANCE "SenderInstance"        /* Sender instance UUID. */
 131 /*! @/defineblock */
 132
 133 /*! @defineblock aslmsg Types
 134  * Message type argument passed to asl_new().
 135  */
 136 #define ASL_TYPE_MSG    0
 137 #define ASL_TYPE_QUERY  1
 138 /*! @/defineblock */
 139
 140 /*! @defineblock Filter Masks
 141  * Used in client-side filtering, which determines which
 142  * messages are sent by the client to the syslogd server.
 143  */
 144 #define ASL_FILTER_MASK_EMERG   0x01
 145 #define ASL_FILTER_MASK_ALERT   0x02
 146 #define ASL_FILTER_MASK_CRIT    0x04
 147 #define ASL_FILTER_MASK_ERR     0x08
 148 #define ASL_FILTER_MASK_WARNING 0x10
 149 #define ASL_FILTER_MASK_NOTICE  0x20
 150 #define ASL_FILTER_MASK_INFO    0x40
 151 #define ASL_FILTER_MASK_DEBUG   0x80
 152 /*! @/defineblock */
 153
 154 /*! @defineblock Filter Mask Macros
 155  * Macros to create bitmasks for filter settings - see asl_set_filter().
 156  */
 157 #define ASL_FILTER_MASK(level) (1 << (level))
 158 #define ASL_FILTER_MASK_UPTO(level) ((1 << ((level) + 1)) - 1)
 159 /*! @/defineblock */
 160
 161 /*! @defineblock Client Creation Options
 162  * Options for asl_open().
 163  */
 164 #define ASL_OPT_STDERR          0x00000001
 165 #define ASL_OPT_NO_DELAY    0x00000002
 166 #define ASL_OPT_NO_REMOTE   0x00000004
 167 /*! @/defineblock */
 168
 169 /*! @defineblock File Descriptor Types
 170  * Instructions on how to treat the file descriptor in asl_log_descriptor().
 171  */
 172 #define ASL_LOG_DESCRIPTOR_READ  1
 173 #define ASL_LOG_DESCRIPTOR_WRITE 2
 174
 175 /*! @defineblock Output file message and time formats.
 176  * These select internally defined formats for printed log messages for
 177  * asl_add_output_file().  Custom message and time formats may also be
 178  * used.  These pre-defined formats and custom formats are described in detail
 179  * in the syslog(1) manual page.
 180  */
 181 #define ASL_MSG_FMT_RAW "raw"
 182 #define ASL_MSG_FMT_STD "std"
 183 #define ASL_MSG_FMT_BSD "bsd"
 184 #define ASL_MSG_FMT_XML "xml"
 185 #define ASL_MSG_FMT_MSG "msg"
 186
 187 #define ASL_TIME_FMT_SEC "sec"
 188 #define ASL_TIME_FMT_UTC "utc"
 189 #define ASL_TIME_FMT_LCL "lcl"
 190
 191 /*! @defineblock Text Encoding Types
 192  * These are used by the library when formatting messages to be written
 193  * to file descriptors associated with an ASL client handle with
 194  * asl_add_output_file().  The syslog(1) manual page describes text encoding
 195  * in detail.  ASL_ENCODE_ASL corresponds to the "vis" encoding option
 196  * described in the syslog(1) manual.  ASL_ENCODE_XML should be used in
 197  * combination with ASL_MSG_FMT_XML to ensure that special XML characters
 198  * are correctly encoded.
 199  */
 200 #define ASL_ENCODE_NONE 0
 201 #define ASL_ENCODE_SAFE 1
 202 #define ASL_ENCODE_ASL  2
 203 #define ASL_ENCODE_XML  3
 204
 205 /*!
 206  * ASL_PREFILTER_LOG is a macro similar to asl_log(), but it first checks
 207  * if the message will simply be ignored due to local filter settings.
 208  * This prevents the variable argument list from being evaluated.
 209  * Note that the message may still be processed if it will be written
 210  * to a file or stderr.
 211  *
 212  * @param asl
 213  *    (input) An ASL client handle
 214  * @param msg
 215  *    (input) An aslmsg (default attributes will be supplied if msg is NULL)
 216  * @param level
 217  *    (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG)
 218  * @param format
 219  *    (input) A printf() - style format string followed by a list of arguments
 220  */
 221 #define ASL_PREFILTER_LOG(asl, msg, level, format, ...) \
 222         do { \
 223                 aslclient _asl = (asl); \
 224                 aslmsg _msg = (msg); \
 225                 uint32_t _asl_eval = _asl_evaluate_send(_asl, _msg, (level)); \
 226                 if (_asl_eval != 0) _asl_lib_log(_asl, _asl_eval, _msg, (format), ## __VA_ARGS__); \
 227         } while (0)
 228
 229 __BEGIN_DECLS
 230
 231 /* ASL Library SPI - do not call directly */
 232 int _asl_lib_log(aslclient asl, uint32_t eval, aslmsg msg, const char *format, ...) __printflike(4, 5);
 233
 234 uint32_t _asl_evaluate_send(aslclient asl, aslmsg msg, int level);
 235
 236 /*!
 237  * Initialize a connection to the ASL server.
 238  *
 239  * This call is optional in most cases.  The library will perform any
 240  * necessary initializations on the fly.  A call to asl_open() is required
 241  * if optional settings must be made before messages are sent to the server.
 242  * These include setting the client filter and managing additional output
 243  * file descriptors.  Note that the default setting of the client filter is
 244  * ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE), so ASL_LEVEL_DEBUG and ASL_LEVEL_INFO
 245  * messages are not sent to the server by default.
 246  *
 247  * Options (defined above) may be set using the opts parameter. They are:
 248  *
 249  *   ASL_OPT_STDERR    - adds stderr as an output file descriptor
 250  *
 251  *   ASL_OPT_NO_DELAY  - connects to the server immediately
 252  *
 253  *   ASL_OPT_NO_REMOTE - disables the remote-control mechanism for adjusting
 254  *                       filter levers for processes using e.g. syslog -c ...
 255  *
 256  * @param ident
 257  *    (input) Sender name
 258  * @param facility
 259  *    (input) Facility name
 260  * @param opts
 261  *    (input) Options (see asl_open Options)
 262  * @result Returns an ASL client handle
 263  */
 264 aslclient asl_open(const char *ident, const char *facility, uint32_t opts);
 265
 266 /*!
 267  * Shuts down a connection to the server.
 268  *
 269  * @param asl
 270  *    (input) An ASL client handle
 271  */
 272 void asl_close(aslclient asl);
 273
 274 /*!
 275  * Write log messages to the given file descriptor.
 276  *
 277  * Log messages will be written to this file as well as to the server.
 278  * This is equivalent to calling:
 279  * asl_add_output_file(asl, descriptor, ASL_MSG_FMT_STD, ASL_TIME_FMT_LCL, ASL_FILTER_MASK_UPTO(ASL_LEVEL_DEBUG), ASL_ENCODE_SAFE)
 280  *
 281  * @param asl
 282  *    (input) An ASL client handle
 283  * @param descriptor
 284  *    (input) A file descriptor
 285  * @result Returns 0 on success, non-zero on failure
 286 */
 287 int asl_add_log_file(aslclient asl, int descriptor);
 288
 289 /*!
 290  * Write log messages to the given file descriptor.
 291  *
 292  * Log messages will be written to this file as well as to the server.
 293  * This routine extends the basic interface offered by asl_add_log_file(),
 294  * allowing control of the format used to write log message written to the file.
 295  * control of the time zone used when printing time values, and allowing
 296  * individual filtering control for each log file.
 297  *
 298  * @param asl
 299  *    (input) An ASL client handle
 300  * @param descriptor
 301  *    (input) A file descriptor
 302  * @param mfmt
 303  *    (input) A character string specifying the message format
 304  * @param tfmt
 305  *    (input) A character string specifying the time format
 306  * @param filter
 307  *    (input) A filter value
 308  * @param text_encoding
 309  *    (input) A text encoding type
 310  * @result Returns 0 on success, non-zero on failure
 311  */
 312 int asl_add_output_file(aslclient asl, int descriptor, const char *mfmt, const char *tfmt, int filter, int text_encoding) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 313
 314 /*!
 315  * Write log messages to the given file descriptor.
 316  *
 317  * Sets or changes a filter value for filtering messages written to a file associated
 318  * with an ASL client handle using asl_add_output_file() or asl_add_log_file().
 319  *
 320  * @param asl
 321  *    (input) An ASL client handle
 322  * @param descriptor
 323  *    (input) A file descriptor
 324  * @param filter
 325  *    (input) A filter value
 326  * @result Returns the previous filter value
 327  */
 328 int asl_set_output_file_filter(aslclient ac, int fd, int filter) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 329
 330 /*!
 331  * Stop writing log messages to the given file descriptor.
 332  * The file descripter is not closed by this routine.
 333  *
 334  * @param asl
 335  *    (input) An ASL client handle
 336  * @param descriptor
 337  *    (input) A file descriptor
 338  * @result Returns 0 on success, non-zero on failure
 339  */
 340 int asl_remove_log_file(aslclient asl, int descriptor);
 341
 342 /*!
 343  * Set a filter for messages being sent to the server.
 344  * The filter is a bitmask representing priorities.  The ASL_FILTER_MASK
 345  * macro may be used to convert a priority level into a bitmask for that
 346  * level.  The ASL_FILTER_MASK_UPTO macro creates a bitmask for all
 347  * priorities up to and including a given priority.
 348  * Messages with priority levels that do not have a corresponding bit
 349  * set in the filter are not sent to the server, although they will be
 350  * sent to any file descripters added with asl_add_log_file().
 351  * The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE).
 352  * Returns the previous filter value.
 353  *
 354  * @param asl
 355  *    (input) An ASL client handle
 356  * @param f
 357  *    (input) A filter value
 358  * @result Returns the previous filter value
 359  */
 360 int asl_set_filter(aslclient asl, int f);
 361
 362 /*
 363  * Examine attribute keys.
 364  *
 365  * @param msg
 366  *    (input) An ASL message
 367  * @param n
 368  *    (input) An index value
 369  * @result Returns the key of the nth attribute in a message (beginning at zero),
 370  * or NULL if n is greater than the largest message index.
 371  */
 372 const char *asl_key(aslmsg msg, uint32_t n);
 373
 374 /*!
 375  * Create a new log message or query message.
 376  *
 377  * @param type
 378  *    (input) Message type (see aslmsg Types)
 379  * @result Returns a newly allocated asmsg of the specified type
 380  */
 381 aslmsg asl_new(uint32_t type);
 382
 383 /*!
 384  * Set or re-set a message attribute.
 385  *
 386  * @param msg
 387  *    (input) An aslmsg
 388  * @param key
 389  *    (input) Attribute key
 390  * @param value
 391  *    (input) Attribute value
 392  * @result returns 0 for success, non-zero for failure
 393  */
 394 int asl_set(aslmsg msg, const char *key, const char *value);
 395
 396 /*!
 397  * Remove a message attribute.
 398  *
 399  * @param msg
 400  *    (input) An aslmsg
 401  * @param key
 402  *    (input) Attribute key
 403  * returns 0 for success, non-zero for failure
 404  */
 405 int asl_unset(aslmsg msg, const char *key);
 406
 407 /*!
 408  * Get the value of a message attribute.
 409  *
 410  * @param msg
 411  *    (input) An aslmsg
 412  * @param key
 413  *    (input) Attribute key
 414  * @result Returns the attribute value, or NULL if the message does not contain the key
 415  */
 416 const char *asl_get(aslmsg msg, const char *key);
 417
 418 /*!
 419  * Log a message with a particular log level.
 420  *
 421  * @param asl
 422  *    (input) An ASL client handle
 423  * @param msg
 424  *    (input) An aslmsg (default attributes will be supplied if msg is NULL)
 425  * @param level
 426  *    (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG)
 427  * @param format
 428  *    (input) A printf() - style format string followed by a list of arguments
 429  * @result Returns 0 for success, non-zero for failure
 430  */
 431 int asl_log(aslclient asl, aslmsg msg, int level, const char *format, ...) __printflike(4, 5);
 432
 433 /*!
 434  * Log a message with a particular log level.
 435  * Similar to asl_log, but takes a va_list argument.
 436  *
 437  * @param asl
 438  *    (input) An ASL client handle
 439  * @param msg
 440  *    (input) An aslmsg (default attributes will be supplied if msg is NULL)
 441  * @param level
 442  *    (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG)
 443  * @param format
 444  *    (input) A printf() - style format string followed by a list of arguments
 445  * @param ap
 446  *    (input) A va_list containing the values for the format string
 447  * @result Returns 0 for success, non-zero for failure
 448  */
 449 int asl_vlog(aslclient asl, aslmsg msg, int level, const char *format, va_list ap) __printflike(4, 0);
 450
 451 /*!
 452  * Log a message.
 453  *
 454  * This routine may be used instead of asl_log() or asl_vlog() if asl_set()
 455  * has been used to set all of a message's attributes.
 456  *
 457  * @param asl
 458  *    (input) An ASL client handle
 459  * @param msg
 460  *    (input) An aslmsg
 461  * @result Returns 0 for success, non-zero for failure
 462  */
 463 int asl_send(aslclient asl, aslmsg msg);
 464
 465 /*!
 466  * Free a message.  Frees all the attribute keys and values.
 467  *
 468  * @param msg
 469  *    (input) An aslmsg to free
 470  */
 471 void asl_free(aslmsg msg);
 472
 473 /*!
 474  * Set arbitrary parameters of a query.
 475  * This is similar to asl_set, but allows richer query operations.
 476  * See ASL_QUERY_OP_* above.
 477  *
 478  * @param msg
 479  *    (input) An aslmsg
 480  * @param key
 481  *    (input) Attribute key
 482  * @param value
 483  *    (input) Attribute value
 484  * @param op
 485  *    (input) An operation (ASL_QUERY_OP_*)
 486  * @result Returns 0 for success, non-zero for failure
 487  */
 488 int asl_set_query(aslmsg msg, const char *key, const char *value, uint32_t op);
 489
 490 /*!
 491  * Search for messages matching the criteria described by the aslmsg.
 492  * The caller should set the attributes to match using asl_set_query() or asl_set().
 493  * The operatoin ASL_QUERY_OP_EQUAL is used for attributes set with asl_set().
 494  *
 495  * @param msg
 496  *    (input) An aslmsg to match
 497  * @result Returns a set of messages accessable using aslresponse_next(),
 498  */
 499 aslresponse asl_search(aslclient asl, aslmsg msg);
 500
 501 /*!
 502  * Iterate over responses returned from asl_search().
 503  *
 504  * @param r
 505  *    (input) An aslresponse returned by asl_search()
 506  * @result Returns the next message (an aslmsg) in the response, or NULL when there are no more messages
 507  */
 508 aslmsg aslresponse_next(aslresponse r);
 509
 510 /*!
 511  * Free a response returned from asl_search().
 512  * @param r
 513  *    (input) An aslresponse returned by asl_search()
 514  */
 515 void aslresponse_free(aslresponse r);
 516
 517 /*!
 518  * Creates an auxiliary file that may be used to save arbitrary data.  The ASL message msg
 519  * will be saved at the time that the auxiliary file is closed with asl_close_auxiliary_file().
 520  * The log entry will include any keys and values found in msg, and it will include the title
 521  * and Uniform Type Identifier specified.  If NULL is supplied as a value for the uti parameter,
 522  * the type "public.data" is used.  Console.app will display a hyperlink to the file.
 523  * Output parameter out_descriptor will contain a readable and writable file descriptor for the new
 524  * auxiliary file.
 525  *
 526  * By default, the file will be world-readable.  If the message contains a ReadUID and/or a
 527  * ReadGID key, then the values for those keys will determine read access to the file.
 528  *
 529  * The file will be deleted at the same time that the message expires from the ASL data store.
 530  * The aslmanager utility manages message expiry.  If msg contains a value for ASLExpireTime,
 531  * then the message and the file will not be deleted before that time.  The value may be in
 532  * seconds after the Epoch, or it may be ctime() format, e.g "Thu Jun 24 18:22:48 2010".
 533  *
 534  * @param msg
 535  *    (input) An aslmsg
 536  * @param tite
 537  *    (input) A title string for the file
 538  * @param uti
 539  *    (input) Uniform Type Identifier for the file
 540  * @param out_descriptor
 541  *    (output) A writable file descriptor
 542  * @result Returns 0 for success, non-zero for failure
 543  */
 544 int asl_create_auxiliary_file(aslmsg msg, const char *title, const char *uti, int *out_descriptor)
 545 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0);
 546
 547 /*!
 548  * Close an auxiliary file opened by asl_create_auxiliary_file() when writing is complete.
 549  * syslogd will log the message provided to asl_create_auxiliary_file() when this routine
 550  * is called.
 551  *
 552  * @param descriptor
 553  *    (input) The file descriptor
 554  * @result Returns 0 for success, non-zero for failure
 555  */
 556 int asl_close_auxiliary_file(int descriptor)
 557 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0);
 558
 559 /*!
 560  * Sends an ASL message to syslogd along with a title string, Uniform Resource Locator,
 561  * and Uniform Type Identifier specified.  Console.app will hyperlink the title string to
 562  * the specified URL.  If NULL is supplied as a value for the uti parameter, the default
 563  * type "public.data" is used.
 564  *
 565  * @param msg
 566  *    (input) An aslmsg
 567  * @param title
 568  *    (input) A title string for the file
 569  * @param uti
 570  *    (input) Uniform Type Identifier for the file
 571  * @param url
 572  *    (input) Uniform Type Locator
 573  * @result Returns 0 for success, non-zero for failure
 574  */
 575 int asl_log_auxiliary_location(aslmsg msg, const char *title, const char *uti, const char *url)
 576 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0);
 577
 578 /*!
 579  * Creates an aslclient for logging to a file descriptor.  The file must be opened for read and
 580  * write access.  This routine may be used in conjunction with asl_create_auxiliary_file() to
 581  * save ASL format log messages to an auxiliary file.
 582  *
 583  * The file will be truncated if it is not empty.  When logging to the auxiliary file is complete,
 584  * aslclient should be closed using asl_close().  The file should be closed using
 585  * asl_close_auxiliary_file() if it was returned by asl_create_auxiliary_file(), or close()
 586  * otherwise.
 587  *
 588  * The returned aslclient is thread-safe.
 589  *
 590  * Note that per-message read access controls (ReadUID and ReadGID) and message expire
 591  * times (ASLExpireTime) keys have no effect for messages written to this file.
 592  *
 593  * @param descriptor
 594  *    (input) A file descriptor
 595  * @param ident
 596  *    (input) Sender name
 597  * @param facility
 598  *    (input) Facility name
 599  * @result An aslclient
 600  */
 601 aslclient asl_open_from_file(int descriptor, const char *ident, const char *facility)
 602 __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0);
 603
 604 /*!
 605  * This API provides functionality to use file descriptors to send logging
 606  * data to ASL.
 607  *
 608  * asl is retained by ASL and must still be closed by the caller by calling
 609  * asl_close() if the caller loses reference to it.  msg is copied by ASL and
 610  * similarly must still be freed by the caller by calling asl_free() if the
 611  * caller loses reference to it.  Any changes made to it after calling
 612  * asl_log_descriptor() are not applicable to the message used. descriptor
 613  * is treated differentlty based on the value of fd_type.
 614  *
 615  * If fd_type is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read
 616  * access.  ASL uses GCD to read from the descriptor as data becomes available.
 617  * These data are line buffered and passed to asl_log.  When EOF is read, the
 618  * descriptor is closed.
 619  *
 620  * Example:
 621  * asl_log_descriptor(c, m, ASL_LEVEL_NOTICE, STDIN_FILENO, ASL_LOG_DESCRIPTOR_READ);
 622  *
 623  * If fd_type is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new
 624  * writable descriptor is created with the same fileno.  Any data written to
 625  * this new descriptor are line buffered and passed to asl_log.  When EOF is
 626  * sent, no further data are read.  The caller is responsible for closing the
 627  * new descriptor.  One common use for this API is to redirect writes to stdout
 628  * or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as descriptor.
 629  *
 630  * Example:
 631  * asl_log_descriptor(c, m, ASL_LEVEL_NOTICE, STDOUT_FILENO, ASL_LOG_DESCRIPTOR_WRITE);
 632  * asl_log_descriptor(c, m, ASL_LEVEL_ERR, STDERR_FILENO, ASL_LOG_DESCRIPTOR_WRITE);
 633  *
 634  * @param asl
 635  *    (input) An ASL client handle
 636  * @param msg
 637  *    (input) An aslmsg (default attributes will be supplied if msg is NULL)
 638  * @param level
 639  *    (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG)
 640  * @param descriptor
 641  *    (input) An open file descriptor to read from
 642  * @param fd_type
 643  *    (input) Either ASL_LOG_DESCRIPTOR_READ or ASL_LOG_DESCRIPTOR_WRITE
 644  * @result Returns 0 for success, non-zero for failure
 645  */
 646 int asl_log_descriptor(aslclient asl, aslmsg msg, int level, int descriptor, uint32_t fd_type)
 647 __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_5_1);
 648
 649 __END_DECLS
 650
 651 #endif /* __ASL_H__ */