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 32typedef struct __aslclient *aslclient; 33typedef struct __aslmsg *aslmsg; 34typedef 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 */ 232int _asl_lib_log(aslclient asl, uint32_t eval, aslmsg msg, const char *format, ...) __printflike(4, 5); 233 234uint32_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 */ 264aslclient 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 */ 272void 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*/ 287int 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 */ 312int 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 */ 328int 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 */ 340int 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 */ 360int 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 */ 372const 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 */ 381aslmsg 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 */ 394int 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 */ 405int 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 */ 416const 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 */ 431int 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 */ 449int 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 */ 463int 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 */ 471void 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 */ 488int 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 */ 499aslresponse 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 */ 508aslmsg 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 */ 515void 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 */ 544int 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 */ 556int 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 */ 575int 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 */ 601aslclient 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 */ 646int 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__ */ 652