1 /* 2 * Copyright (c) 2004-2013 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 <stddef.h> 29 #include <stdarg.h> 30 #include <sys/cdefs.h> 31 #include <Availability.h> 32 33 /* Version number encodes the date YYYYMMDD */ 34 #define ASL_API_VERSION 20131108 35 36 typedef struct __asl_object_s *asl_object_t; 37 typedef asl_object_t aslclient; 38 typedef asl_object_t aslmsg; 39 typedef asl_object_t aslresponse; 40 41 /*! @header 42 * These routines provide an interface to the Apple System Log facility. 43 * The API allows client applications to create flexible, structured messages 44 * and send them to the syslogd server. Messages received by the server are 45 * saved in a data store, subject to input filtering constraints. 46 * This API also permits clients to create queries and search the message 47 * data store for matching messages. 48 */ 49 50 /* 51 * NOTE FOR HeaderDoc 52 * 53 * These are added to allow headerdoc2html to process 54 * the prototypes of asl_log and asl_vlog correctly. 55 * The "-p" option to headerdoc2html is required. 56 */ 57 #ifndef __printflike 58 /*! @parseOnly */ 59 #define __printflike(a,b) 60 #endif 61 62 #pragma mark - 63 64 /*! @defineblock Log Message Priority Levels 65 * Log levels of the message. 66 */ 67 #define ASL_LEVEL_EMERG 0 68 #define ASL_LEVEL_ALERT 1 69 #define ASL_LEVEL_CRIT 2 70 #define ASL_LEVEL_ERR 3 71 #define ASL_LEVEL_WARNING 4 72 #define ASL_LEVEL_NOTICE 5 73 #define ASL_LEVEL_INFO 6 74 #define ASL_LEVEL_DEBUG 7 75 /*! @/defineblock */ 76 77 #pragma mark - 78 79 /*! @defineblock Log Message Priority Level Strings 80 * Strings corresponding to log levels. 81 */ 82 #define ASL_STRING_EMERG "Emergency" 83 #define ASL_STRING_ALERT "Alert" 84 #define ASL_STRING_CRIT "Critical" 85 #define ASL_STRING_ERR "Error" 86 #define ASL_STRING_WARNING "Warning" 87 #define ASL_STRING_NOTICE "Notice" 88 #define ASL_STRING_INFO "Info" 89 #define ASL_STRING_DEBUG "Debug" 90 /*! @/defineblock */ 91 92 #pragma mark - 93 94 /*! @defineblock Attribute Matching 95 * Attribute value comparison operations. 96 */ 97 #define ASL_QUERY_OP_CASEFOLD 0x0010 98 #define ASL_QUERY_OP_PREFIX 0x0020 99 #define ASL_QUERY_OP_SUFFIX 0x0040 100 #define ASL_QUERY_OP_SUBSTRING 0x0060 101 #define ASL_QUERY_OP_NUMERIC 0x0080 102 #define ASL_QUERY_OP_REGEX 0x0100 103 104 #define ASL_QUERY_OP_EQUAL 0x0001 105 #define ASL_QUERY_OP_GREATER 0x0002 106 #define ASL_QUERY_OP_GREATER_EQUAL 0x0003 107 #define ASL_QUERY_OP_LESS 0x0004 108 #define ASL_QUERY_OP_LESS_EQUAL 0x0005 109 #define ASL_QUERY_OP_NOT_EQUAL 0x0006 110 #define ASL_QUERY_OP_TRUE 0x0007 111 /*! @/defineblock */ 112 113 #pragma mark - 114 115 /*! @defineblock Message Attributes 116 * These attributes are known by ASL, and are generally 117 * associated with all log messages. 118 * Additional attributes may be added as desired. 119 */ 120 #define ASL_KEY_TIME "Time" /* Timestamp. Set automatically */ 121 #define ASL_KEY_TIME_NSEC "TimeNanoSec" /* Nanosecond time. */ 122 #define ASL_KEY_HOST "Host" /* Sender's address (set by the server). */ 123 #define ASL_KEY_SENDER "Sender" /* Sender's identification string. Default is process name. */ 124 #define ASL_KEY_FACILITY "Facility" /* Sender's facility. Default is "user". */ 125 #define ASL_KEY_PID "PID" /* Sending process ID encoded as a string. Set automatically. */ 126 #define ASL_KEY_UID "UID" /* UID that sent the log message (set by the server). */ 127 #define ASL_KEY_GID "GID" /* GID that sent the log message (set by the server). */ 128 #define ASL_KEY_LEVEL "Level" /* Log level number encoded as a string. See levels above. */ 129 #define ASL_KEY_MSG "Message" /* Message text. */ 130 #define ASL_KEY_READ_UID "ReadUID" /* User read access (-1 is any user). */ 131 #define ASL_KEY_READ_GID "ReadGID" /* Group read access (-1 is any group). */ 132 #define ASL_KEY_EXPIRE_TIME "ASLExpireTime" /* Expiration time for messages with long TTL. */ 133 #define ASL_KEY_MSG_ID "ASLMessageID" /* 64-bit message ID number (set by the server). */ 134 #define ASL_KEY_SESSION "Session" /* Session (set by the launchd). */ 135 #define ASL_KEY_REF_PID "RefPID" /* Reference PID for messages proxied by launchd */ 136 #define ASL_KEY_REF_PROC "RefProc" /* Reference process for messages proxied by launchd */ 137 #define ASL_KEY_AUX_TITLE "ASLAuxTitle" /* Auxiliary title string */ 138 #define ASL_KEY_AUX_UTI "ASLAuxUTI" /* Auxiliary Uniform Type ID */ 139 #define ASL_KEY_AUX_URL "ASLAuxURL" /* Auxiliary Uniform Resource Locator */ 140 #define ASL_KEY_AUX_DATA "ASLAuxData" /* Auxiliary in-line data */ 141 #define ASL_KEY_OPTION "ASLOption" /* Internal */ 142 #define ASL_KEY_MODULE "ASLModule" /* Internal */ 143 #define ASL_KEY_SENDER_INSTANCE "SenderInstance" /* Sender instance UUID. */ 144 #define ASL_KEY_SENDER_MACH_UUID "SenderMachUUID" /* Sender Mach-O UUID. */ 145 #define ASL_KEY_FINAL_NOTIFICATION "ASLFinalNotification" /* syslogd posts value as a notification when message has been processed */ 146 #define ASL_KEY_OS_ACTIVITY_ID "OSActivityID" /* Current OS Activity for the logging thread */ 147 /*! @/defineblock */ 148 149 #pragma mark - 150 151 /*! @defineblock ASL Object Types 152 * The library uses only one opaque type - asl_object_t. 153 * Many of the routines can operate on several different types. 154 * For example, asl_search() can be used to search a list of messages, 155 * an ASL database directory or data file, or the main ASL database. 156 * It can even be used to check a single message against a query 157 * message, or against another message to check for exact match. 158 * 159 * The first three types are container objects - messages, queries, 160 * and lists of messages or queries. The following types are 161 * abstractions for ASL data files and ASL data stores (directories 162 * containing data files). 163 * 164 * ASL_TYPE_CLIENT is a high-level object that abstracts ASL 165 * interactions. It may access ASL stores or files directly, 166 * and it may communicate with ASL daemons. 167 * 168 */ 169 #define ASL_TYPE_UNDEF 0xffffffff 170 #define ASL_TYPE_MSG 0 171 #define ASL_TYPE_QUERY 1 172 #define ASL_TYPE_LIST 2 173 #define ASL_TYPE_FILE 3 174 #define ASL_TYPE_STORE 4 175 #define ASL_TYPE_CLIENT 5 176 /*! @/defineblock */ 177 178 #pragma mark - 179 180 /*! @defineblock search directions 181 * Used for asl_store_match(), asl_file_match(), and asl_match(). 182 */ 183 #define ASL_MATCH_DIRECTION_FORWARD 1 184 #define ASL_MATCH_DIRECTION_REVERSE -1 185 /*! @/defineblock */ 186 187 #pragma mark - 188 189 /*! @defineblock Filter Masks 190 * Used in client-side filtering, which determines which 191 * messages are sent by the client to the syslogd server. 192 */ 193 #define ASL_FILTER_MASK_EMERG 0x01 194 #define ASL_FILTER_MASK_ALERT 0x02 195 #define ASL_FILTER_MASK_CRIT 0x04 196 #define ASL_FILTER_MASK_ERR 0x08 197 #define ASL_FILTER_MASK_WARNING 0x10 198 #define ASL_FILTER_MASK_NOTICE 0x20 199 #define ASL_FILTER_MASK_INFO 0x40 200 #define ASL_FILTER_MASK_DEBUG 0x80 201 /*! @/defineblock */ 202 203 #pragma mark - 204 205 /*! @defineblock Filter Mask Macros 206 * Macros to create bitmasks for filter settings - see asl_set_filter(). 207 */ 208 #define ASL_FILTER_MASK(level) (1 << (level)) 209 #define ASL_FILTER_MASK_UPTO(level) ((1 << ((level) + 1)) - 1) 210 /*! @/defineblock */ 211 212 #pragma mark - 213 214 /*! @defineblock Client Creation Options 215 * Options for asl_open(). 216 * Note that ASL_OPT_NO_DELAY no longer has any effect. 217 */ 218 #define ASL_OPT_STDERR 0x00000001 219 #define ASL_OPT_NO_DELAY 0x00000002 220 #define ASL_OPT_NO_REMOTE 0x00000004 221 /*! @/defineblock */ 222 223 #pragma mark - 224 225 /*! @defineblock File and Store Open Options 226 * Options for asl_open_path(). 227 */ 228 #define ASL_OPT_OPEN_WRITE 0x00000001 229 #define ASL_OPT_CREATE_STORE 0x00000002 230 /*! @/defineblock */ 231 232 #pragma mark - 233 234 /*! @defineblock File Descriptor Types 235 * Instructions on how to treat the file descriptor in asl_log_descriptor(). 236 */ 237 #define ASL_LOG_DESCRIPTOR_READ 1 238 #define ASL_LOG_DESCRIPTOR_WRITE 2 239 240 #pragma mark - 241 242 /*! @defineblock Output file message and time formats. 243 * These select internally defined formats for printed log messages for 244 * asl_add_output_file(). Custom message and time formats may also be 245 * used. These pre-defined formats and custom formats are described in detail 246 * in the syslog(1) manual page. 247 */ 248 #define ASL_MSG_FMT_RAW "raw" 249 #define ASL_MSG_FMT_STD "std" 250 #define ASL_MSG_FMT_BSD "bsd" 251 #define ASL_MSG_FMT_XML "xml" 252 #define ASL_MSG_FMT_MSG "msg" 253 254 #define ASL_TIME_FMT_SEC "sec" 255 #define ASL_TIME_FMT_UTC "utc" 256 #define ASL_TIME_FMT_LCL "lcl" 257 258 #pragma mark - 259 260 /*! @defineblock Text Encoding Types 261 * These are used by the library when formatting messages to be written 262 * to file descriptors associated with an ASL client handle with 263 * asl_add_output_file(). The syslog(1) manual page describes text encoding 264 * in detail. ASL_ENCODE_ASL corresponds to the "vis" encoding option 265 * described in the syslog(1) manual. ASL_ENCODE_XML should be used in 266 * combination with ASL_MSG_FMT_XML to ensure that special XML characters 267 * are correctly encoded. 268 */ 269 #define ASL_ENCODE_NONE 0 270 #define ASL_ENCODE_SAFE 1 271 #define ASL_ENCODE_ASL 2 272 #define ASL_ENCODE_XML 3 273 274 #pragma mark - 275 276 /*! 277 * ASL_PREFILTER_LOG is a macro similar to asl_log(), but it first checks 278 * if the message will simply be ignored due to local filter settings. 279 * This prevents the variable argument list from being evaluated. 280 * Note that the message may still be processed if it will be written 281 * to a file or stderr. 282 * 283 * @param client 284 * (input) An ASL_TYPE_CLIENT object. 285 * @param msg 286 * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). 287 * @param level 288 * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). 289 * @param format 290 * (input) A printf() - style format string followed by a list of arguments. 291 */ 292 #define ASL_PREFILTER_LOG(client, msg, level, format, ...) \ 293 do { \ 294 asl_object_t _client = (client); \ 295 asl_object_t _msg = (msg); \ 296 uint32_t _asl_eval = _asl_evaluate_send(_client, _msg, (level)); \ 297 if (_asl_eval != 0) _asl_lib_log(_client, _asl_eval, _msg, (format), ## __VA_ARGS__); \ 298 } while (0) 299 300 #pragma mark - 301 302 __BEGIN_DECLS 303 304 /* ASL Library SPI - do not call directly */ 305 int _asl_lib_log(asl_object_t client, uint32_t eval, asl_object_t msg, const char *format, ...) __printflike(4, 5); 306 uint32_t _asl_evaluate_send(asl_object_t client, asl_object_t msg, int level); 307 308 /*! 309 * Initialize a connection to the ASL server. 310 * 311 * This call is optional in many cases. The library will perform any 312 * necessary initializations on the fly. A call to asl_open() is required 313 * if optional settings must be made before messages are sent to the server. 314 * These include setting the client filter and managing additional output 315 * file descriptors. Note that the default setting of the client filter is 316 * ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE), so ASL_LEVEL_DEBUG and ASL_LEVEL_INFO 317 * messages are not sent to the server by default. 318 * A separate client connection is required for multiple threads or 319 * dispatch queues. 320 * 321 * Options (defined above) may be set using the opts parameter. They are: 322 * 323 * ASL_OPT_STDERR - adds stderr as an output file descriptor 324 * 325 * ASL_OPT_NO_REMOTE - disables the remote-control mechanism for adjusting 326 * filter levers for processes using e.g. syslog -c ... 327 * 328 * @param ident 329 * (input) Sender name. 330 * @param facility 331 * (input) Facility name. 332 * @param opts 333 * (input) Options (see Client Creation Options). 334 * @result Returns an ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). 335 */ 336 asl_object_t asl_open(const char *ident, const char *facility, uint32_t opts) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 337 338 /*! 339 * Open an ASL database or ASL data file for read or write access. 340 * 341 * Opens an ASL database if the path specifies a directory, or 342 * an ASL data file if the path specifies a file. Opens the system 343 * ASL database if path is NULL. 344 * 345 * If the ASL_OPT_OPEN_READ option is specified, the database or data file may be 346 * searched with asl_search() or asl_match(). asl_next() and asl_prev() may be used 347 * to iterate over the messages in the database or file. 348 * 349 * If the ASL_OPT_OPEN_WRITE option is specified, an existing file or database is 350 * opened for writing. New messages may be added to the file or database using 351 * asl_append(), asl_send(), asl_log(), or asl_vlog(). Existing messages in the 352 * store or file may not be deleted or modified. 353 * 354 * If the path does not exist, asl_open_path() will create a new database if 355 * ASL_OPT_CREATE_STORE is set in the options, or a new data file otherwise. 356 * The file will be created with the user's effective UID and GID as owner and 357 * group. The mode will be 0644. If a different mode, UID, or GID is desired, 358 * an empty file or directory may be pre-created with the desired settings. 359 * 360 * @param path 361 * (input) Location of the ASL database or ASL data file in the filesystem. 362 * A value of NULL may be used to open the system's database. 363 * @param opts 364 * (input) Options (see File and Store Open Options). 365 * @result Returns an ASL object of type ASL_TYPE_STORE or ASL_TYPE_FILE, or NULL on failure. 366 */ 367 asl_object_t asl_open_path(const char *path, uint32_t opts) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 368 369 /*! 370 * Shuts down a connection to the server. 371 * This routine is identical to asl_release(). 372 * 373 * @param obj 374 * (input) An ASL object. 375 */ 376 void asl_close(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 377 378 /*! 379 * Write log messages to the given file descriptor. 380 * 381 * Log messages will be written to this file as well as to the server. 382 * This is equivalent to calling: 383 * asl_add_output_file(asl, descriptor, ASL_MSG_FMT_STD, ASL_TIME_FMT_LCL, ASL_FILTER_MASK_UPTO(ASL_LEVEL_DEBUG), ASL_ENCODE_SAFE) 384 * 385 * @param client 386 * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). 387 * @param descriptor 388 * (input) A file descriptor. 389 * @result Returns 0 on success, non-zero on failure. 390 */ 391 int asl_add_log_file(asl_object_t client, int descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 392 393 /*! 394 * Write log messages to the given file descriptor. 395 * 396 * Log messages will be written to this file as well as to the server. 397 * This routine extends the basic interface offered by asl_add_log_file(), 398 * allowing control of the format used to write log message written to the file. 399 * control of the time zone used when printing time values, and allowing 400 * individual filtering control for each log file. 401 * 402 * @param client 403 * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). 404 * @param descriptor 405 * (input) A file descriptor. 406 * @param mfmt 407 * (input) A character string specifying the message format. 408 * @param tfmt 409 * (input) A character string specifying the time format. 410 * @param filter 411 * (input) A filter value. 412 * @param text_encoding 413 * (input) A text encoding type. 414 * @result Returns 0 on success, non-zero on failure. 415 */ 416 int asl_add_output_file(asl_object_t client, int fd, const char *mfmt, const char *tfmt, int filter, int text_encoding) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 417 418 /*! 419 * Write log messages to the given file descriptor. 420 * 421 * Sets or changes a filter value for filtering messages written to a file associated 422 * with an ASL client handle using asl_add_output_file() or asl_add_log_file(). 423 * 424 * @param client 425 * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). 426 * @param descriptor 427 * (input) A file descriptor. 428 * @param filter 429 * (input) A filter value. 430 * @result Returns the previous filter value. 431 */ 432 int asl_set_output_file_filter(asl_object_t client, int fd, int filter) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 433 434 /*! 435 * Stop writing log messages to the given file descriptor. 436 * The file descripter is not closed by this routine. 437 * 438 * @param client 439 * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). 440 * @param descriptor 441 * (input) A file descriptor. 442 * @result Returns 0 on success, non-zero on failure. 443 */ 444 int asl_remove_log_file(asl_object_t client, int descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 445 446 /*! 447 * Set a filter for messages being sent to the server. 448 * The filter is a bitmask representing priorities. The ASL_FILTER_MASK 449 * macro may be used to convert a priority level into a bitmask for that 450 * level. The ASL_FILTER_MASK_UPTO macro creates a bitmask for all 451 * priorities up to and including a given priority. 452 * Messages with priority levels that do not have a corresponding bit 453 * set in the filter are not sent to the server, although they will be 454 * sent to any file descripters added with asl_add_log_file(). 455 * The default setting is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE). 456 * Returns the previous filter value. 457 * 458 * @param client 459 * (input) An ASL client handle (asl_object_t of type ASL_TYPE_CLIENT). 460 * @param f 461 * (input) A filter value. 462 * @result Returns the previous filter value. 463 */ 464 int asl_set_filter(asl_object_t client, int f) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 465 466 /* 467 * Examine attribute keys. 468 * 469 * @param msg 470 * (input) An ASL message or query (asl_object_t of type ASL_TYPE_MSG or ASL_TYPE_QUERY). 471 * @param n 472 * (input) An index value. 473 * @result Returns the key of the nth attribute in a message (beginning at zero), 474 * or NULL if n is greater than the largest message index. 475 */ 476 const char *asl_key(asl_object_t msg, uint32_t n) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 477 478 /* 479 * Examine attribute keys. 480 * 481 * @param msg 482 * (input) An ASL message or query (asl_object_t of type ASL_TYPE_MSG or ASL_TYPE_QUERY). 483 * @param key 484 * (output) key at the given index. May be NULL. 485 * @param val 486 * (output) val at the given index. May be NULL. 487 * @param op 488 * (output) op at the given index. May be NULL. 489 * @param n 490 * (input) An index value. 491 * @result returns 0 for success, non-zero for failure. 492 */ 493 int asl_fetch_key_val_op(asl_object_t msg, uint32_t n, const char **key, const char **val, uint32_t *op) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 494 495 /*! 496 * Create a new log message, query message, message list, or a connection to the system database. 497 * 498 * @param type 499 * (input) ASL_TYPE_MSG, ASL_TYPE_QUERY, ASL_TYPE_LIST, or ASL_TYPE_CLIENT. 500 * @result Returns a newly allocated asl_object_t of the specified type. 501 * 502 * @discussion 503 * New objects of type ASL_TYPE_CLIENT will be created with default settings for 504 * a client connection, equivalent to asl_open(NULL, NULL, 0). 505 * The Sender and Facility values associated with an ASL_TYPE_CLIENT may 506 * be reset using asl_set(). 507 */ 508 asl_object_t asl_new(uint32_t type) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 509 510 /*! 511 * Set or re-set a message or query attribute. 512 * May also be used to set values associated with an ASL_TYPE_CLIENT object, 513 * such as Sender and Facility. 514 * 515 * @param obj 516 * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. 517 * @param key 518 * (input) Attribute key. 519 * @param value 520 * (input) Attribute value. 521 * @result returns 0 for success, non-zero for failure. 522 */ 523 int asl_set(asl_object_t obj, const char *key, const char *value) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 524 525 /*! 526 * Remove a key/value attribute. 527 * 528 * @param obj 529 * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. 530 * @param key 531 * (input) Attribute key. 532 * returns 0 for success, non-zero for failure. 533 */ 534 int asl_unset(asl_object_t obj, const char *key) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 535 536 /*! 537 * Get the value associated with an attribute key. 538 * 539 * @param obj 540 * (input) An ASL object of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_CLIENT. 541 * @param key 542 * (input) Attribute key. 543 * @result Returns the attribute value, or NULL if the object does not contain the key. 544 */ 545 const char *asl_get(asl_object_t msg, const char *key) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 546 547 /*! 548 * Log a message with a particular log level. 549 * 550 * @param obj 551 * (input) An asl_object_t or NULL. 552 * @param msg 553 * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). 554 * @param level 555 * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). 556 * @param format 557 * (input) A printf() - style format string followed by a list of arguments. 558 * @result Returns 0 for success, non-zero for failure. 559 * 560 * @discussion 561 * The input object may be of any type. 562 * In typical usage, obj is of type ASL_TYPE_CLIENT or obj is NULL. 563 * NULL causes the library to use the default ASL client handle. 564 * This routine prepares a message for tranmission to the ASL server daemon (syslogd), 565 * The message is sent to the server subject to filter settings. The message may also 566 * be formatted and printed to various output files. 567 * 568 * For ASL_TYPE_MSG, this routine will set all key/value pairs in the input object as 569 * they would appear if the message were being sent to the server. This includes 570 * setting alues for ASL_KEY_TIME, ASL_KEY_TIME_NSEC, ASL_KEY_HOST, and so on. 571 * 572 * If the object is of type ASL_TYPE_STORE or ASL_TYPE_FILE, a message will be 573 * constructed (as above) and saved in the file or data store. No filtering is done. 574 * 575 * If obj is of type ASL_TYPE_LIST, a message is created and appended to the list. 576 * 577 * The object type ASL_TYPE_QUERY is supported, but the key/value pairs set in the 578 * object will have an operator value of zero. 579 */ 580 int asl_log(asl_object_t client, asl_object_t msg, int level, const char *format, ...) __printflike(4, 5) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 581 582 /*! 583 * Log a message with a particular log level. 584 * 585 * This API is a simplified version of asl_log(). It uses the default (NULL) ASL client handle, 586 * and does not have a msg parameter to supply additonal key/value pairs to be attached to the 587 * message sent to the syslogd server. 588 * 589 * @param level 590 * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). 591 * @param format 592 * (input) A printf() - style format string followed by a list of arguments. 593 * @result Returns 0 for success, non-zero for failure. 594 */ 595 int asl_log_message(int level, const char *format, ...) __printflike(2, 3) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 596 597 /*! 598 * Log a message with a particular log level. 599 * Similar to asl_log, but takes a va_list argument. 600 * 601 * @param asl 602 * (input) An ASL object or NULL. 603 * @param msg 604 * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). 605 * @param level 606 * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG). 607 * @param format 608 * (input) A printf() - style format string followed by a list of arguments. 609 * @param ap 610 * (input) A va_list containing the values for the format string. 611 * @result Returns 0 for success, non-zero for failure. 612 * @discussion 613 * See the discussion for asl_log() for a description of how this routine treats different 614 * types of input object. 615 * 616 */ 617 int asl_vlog(asl_object_t obj, asl_object_t msg, int level, const char *format, va_list ap) __printflike(4, 0) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 618 619 /*! 620 * Log a message. 621 * 622 * This routine may be used instead of asl_log() or asl_vlog() if asl_set() 623 * has been used to set all of a message's attributes. 624 * 625 * @param asl 626 * (input) An ASL object or NULL. 627 * @param msg 628 * (input) An asl_object_t of type ASL_TYPE_MSG. 629 * @result Returns 0 for success, non-zero for failure. 630 * @discussion 631 * See the discussion for asl_log() for a description of how this routine treats different 632 * types of input object. 633 */ 634 int asl_send(asl_object_t obj, asl_object_t msg) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 635 636 /*! 637 * DEPRECATED: Free an ASL object and all internal resources associated with it. 638 * This routine is identical to asl_release(), which should be used instead. 639 * Note that we don't issue a deprecation warning - yet. 640 * 641 * @param obj 642 * (input) An ASL object to free. 643 */ 644 void asl_free(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 645 646 /*! 647 * Increment the internal reference count of an ASL object. 648 * 649 * @param obj 650 * (input) An ASL object to retain. 651 * @result Returns the object. 652 */ 653 asl_object_t asl_retain(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 654 655 /*! 656 * Decrement the internal reference count of an ASL object. 657 * Frees the object when the reference count becomes zero. 658 * 659 * @param obj 660 * (input) An ASL object to release. 661 */ 662 void asl_release(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 663 664 /*! 665 * Get the internal type of an ASL object. 666 * 667 * @param obj 668 * (input) An ASL object. 669 * @result Returns the object type. 670 */ 671 uint32_t asl_get_type(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 672 673 /*! 674 * Set arbitrary parameters of a query. 675 * This is similar to asl_set, but allows richer query operations. 676 * See ASL_QUERY_OP_* above. 677 * 678 * @param msg 679 * (input) An ASL object of type ASL_TYPE_QUERY. 680 * @param key 681 * (input) Attribute key 682 * @param value 683 * (input) Attribute value 684 * @param op 685 * (input) An operation (ASL_QUERY_OP_*) 686 * @result Returns 0 for success, non-zero for failure 687 */ 688 int asl_set_query(asl_object_t msg, const char *key, const char *value, uint32_t op) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 689 690 /*! 691 * Search for messages matching the criteria described by an query object. 692 * The caller should set the attributes to match using asl_set_query() or asl_set(). 693 * The operation ASL_QUERY_OP_EQUAL is used for attributes set with asl_set(). 694 * 695 * @param obj 696 * (input) An ASL object to search. 697 * @param query 698 * (input) An asl_object_t of type ASL_TYPE_QUERY or ASL_TYPE_MSG. 699 * query may be NULL, which matches anything. 700 * @result Returns an ASL object containing messages matching the query, or NULL if there are no matches. 701 * 702 * @discussion 703 * The object to search may be of any type. 704 * ASL_TYPE_CLIENT searches the main ASL database. 705 * ASL_TYPE_STORE searches an ASL database in the filesystem. 706 * ASL_TYPE_FILE searches an ASL data file in the filesystem. 707 * ASL_TYPE_LIST searches for matches in a list of messages. 708 * 709 * A NULL query matches anything. 710 * 711 * If obj is of type ASL_TYPE_MSG and query is of type ASL_TYPE_QUERY, obj is matched against the query, 712 * and a list containing the "obj" object is returned if the match succeeds. 713 * 714 * If both obj and query are objects of type ASL_TYPE_MSG or both are of type ASL_TYPE_QUERY, 715 * they are tested for exact match. A list containing the "obj" object is returned if the match is exact. 716 * 717 * If obj is of type ASL_TYPE_QUERY and query is of type ASL_TYPE_MSG, the routine returns NULL. 718 * 719 */ 720 asl_object_t asl_search(asl_object_t obj, asl_object_t query) __OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0); 721 722 /*! 723 * DEPRECATED: Iterate over messages in an asl_object_t (same as an aslresponse). 724 * This routine is identical to asl_next(). 725 * 726 * @param list 727 * (input) An asl_object_t (aslresponse). 728 * @result Returns the next message contained in an ASL object, or NULL when there are no more messages. 729 * 730 * @discussion 731 * This routine is deprecated in favor of asl_next(). 732 */ 733 asl_object_t aslresponse_next(asl_object_t obj) __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_4,__MAC_10_10,__IPHONE_2_0,__IPHONE_7_0, "Use asl_next instead"); 734 735 /*! 736 * DEPRECATED: Free an asl_object_t. 737 * This routine is identical to asl_release(). 738 * 739 * @param list 740 * (input) An asl_object_t (aslresponse). 741 * 742 * @discussion 743 * This routine is deprecated in favor of asl_release(). 744 */ 745 void aslresponse_free(asl_object_t obj) __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_4,__MAC_10_10,__IPHONE_2_0,__IPHONE_7_0, "Use asl_release instead"); 746 747 /*! 748 * Append messages to an object of type ASL_TYPE_LIST. The input "obj" 749 * parameter may be of type ASL_TYPE_MSG or ASL_TYPE_QUERY, in which case 750 * the object is appended to the list, or "obj" may be of type ASL_TYPE_LIST, 751 * in which case each object in that list is appended to the "list" object. 752 * Does nothing if either list or obj are NULL. 753 * 754 * @param obj 755 * (input) An object of type ASLTYPE_CLIENT or ASL_TYPE_LIST, or an object of type 756 * ASL_TYPE_FILE or ASL_TYPE_STORE that is open for write operations. 757 * @param obj_to_add 758 * (input) An object of type ASL_TYPE_MSG, ASL_TYPE_QUERY or type ASL_TYPE_LIST. 759 */ 760 void asl_append(asl_object_t obj, asl_object_t obj_to_add) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 761 762 /*! 763 * Prepend messages to an object of type ASL_TYPE_LIST. The input "obj" 764 * parameter may be of type ASL_TYPE_MSG or ASL_TYPE_QUERY, in which case 765 * the object is prepended to the list, or "obj" may be of type ASL_TYPE_LIST, 766 * in which case each object in that list is prepended to the "list" object. 767 * Does nothing if either list or obj are NULL. 768 * 769 * @param obj 770 * (input) An object of type ASL_TYPE_LIST. 771 * @param obj_to_add 772 * (input) An object of type ASL_TYPE_MSG, ASL_TYPE_QUERY or type ASL_TYPE_LIST. 773 */ 774 void asl_prepend(asl_object_t obj, asl_object_t obj_to_add) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 775 776 /*! 777 * Get the number of key/value pairs in an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY, 778 * or the number of components in an object of type ASL_TYPE_LIST. 779 * 780 * @param obj 781 * (input) An asl_object_t of type ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_LIST. 782 * @result The number of components in the object. 783 * Returns zero if object is empty or NULL, or if the type is not 784 * ASL_TYPE_MSG, ASL_TYPE_QUERY, or ASL_TYPE_LIST. 785 */ 786 size_t asl_count(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 787 788 /*! 789 * Retreive a message from an object of type ASL_TYPE_LIST. 790 * 791 * @param obj 792 * (input) An asl_object_t of type ASL_TYPE_LIST 793 * @result Returns the message (an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY) at the specified index. 794 * Returns NULL if the index is out of range or if list is not an object of type ASL_TYPE_LIST. 795 */ 796 asl_object_t asl_get_index(asl_object_t list, size_t index) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 797 798 /*! 799 * Remove the message at a specified index from an object of type ASL_TYPE_LIST. 800 * 801 * @param list 802 * (input) An object of type ASL_TYPE_LIST. 803 */ 804 void asl_remove_index(asl_object_t list, size_t index) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 805 806 /*! 807 * Creates an auxiliary file that may be used to save arbitrary data. The ASL message msg 808 * will be saved at the time that the auxiliary file is closed with asl_close_auxiliary_file(). 809 * The log entry will include any keys and values found in msg, and it will include the title 810 * and Uniform Type Identifier specified. If NULL is supplied as a value for the uti parameter, 811 * the type "public.data" is used. Console.app will display a hyperlink to the file. 812 * Output parameter out_descriptor will contain a readable and writable file descriptor for the new 813 * auxiliary file. 814 * 815 * By default, the file will be world-readable. If the message contains a ReadUID and/or a 816 * ReadGID key, then the values for those keys will determine read access to the file. 817 * 818 * The file will be deleted at the same time that the message expires from the ASL data store. 819 * The aslmanager utility manages message expiry. If msg contains a value for ASLExpireTime, 820 * then the message and the file will not be deleted before that time. The value may be in 821 * seconds after the Epoch, or it may be ctime() format, e.g "Thu Jun 24 18:22:48 2010". 822 * 823 * @param msg 824 * (input) An object of type ASL_TYPE_MSG. 825 * @param tite 826 * (input) A title string for the file. 827 * @param uti 828 * (input) Uniform Type Identifier for the file. 829 * @param out_descriptor 830 * (output) A writable file descriptor. 831 * @result Returns 0 for success, non-zero for failure 832 */ 833 int asl_create_auxiliary_file(asl_object_t msg, const char *title, const char *uti, int *out_descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); 834 835 /*! 836 * Close an auxiliary file opened by asl_create_auxiliary_file() when writing is complete. 837 * syslogd will log the message provided to asl_create_auxiliary_file() when this routine 838 * is called. 839 * 840 * @param descriptor 841 * (input) The file descriptor 842 * @result Returns 0 for success, non-zero for failure 843 */ 844 int asl_close_auxiliary_file(int descriptor) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); 845 846 /*! 847 * Sends an ASL message to syslogd along with a title string, Uniform Resource Locator, 848 * and Uniform Type Identifier specified. Console.app will hyperlink the title string to 849 * the specified URL. If NULL is supplied as a value for the uti parameter, the default 850 * type "public.data" is used. 851 * 852 * @param msg 853 * (input) An object of type ASL_TYPE_MSG. 854 * @param title 855 * (input) A title string for the file 856 * @param uti 857 * (input) Uniform Type Identifier for the file 858 * @param url 859 * (input) Uniform Type Locator 860 * @result Returns 0 for success, non-zero for failure 861 */ 862 int asl_log_auxiliary_location(asl_object_t msg, const char *title, const char *uti, const char *url) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); 863 864 /*! 865 * Creates an object of type ASL_TYPE_CLIENT for logging to a file descriptor. 866 * The file must be opened for read and write access. This routine may be used in conjunction 867 * with asl_create_auxiliary_file() to save ASL format log messages to an auxiliary file. 868 * 869 * When logging to the file is complete, the returned object should be released with asl_release(). 870 * The file descriptor should be closed using asl_close_auxiliary_file() if it was returned by 871 * asl_create_auxiliary_file(), or close() otherwise. 872 * 873 * The returned client object is thread-safe. It contains a lock that is aquired by 874 * the calling thread. Note that this may cause unexpected syncronization behavior 875 * if multiple threads log to the returned object, or in applications that use the 876 * object in multiple dispatch queues. 877 * 878 * Note that per-message read access controls (ReadUID and ReadGID) and message expire 879 * times (ASLExpireTime) keys have no effect for messages written to this file. 880 * 881 * Also note that files are NOT truncated. This is a change in OS X 10.9 and iOS 7.0. 882 * Previous versions of this routine truncated the file before writing. Callers 883 * may use ftruncate() to truncate the file if desired. If an existing non-empty 884 * file is used, it must be an ASL format data file. 885 * 886 * @param descriptor 887 * (input) A file descriptor 888 * @param ident 889 * (input) Sender name 890 * @param facility 891 * (input) Facility name 892 * @result An object of type ASL_TYPE_CLIENT. 893 */ 894 asl_object_t asl_open_from_file(int descriptor, const char *ident, const char *facility) __OSX_AVAILABLE_STARTING(__MAC_10_7,__IPHONE_5_0); 895 896 /*! 897 * This API provides functionality to use file descriptors to send logging 898 * data to ASL. 899 * 900 * asl is retained by ASL and must still be closed by the caller by calling 901 * asl_close() if the caller loses reference to it. msg is copied by ASL and 902 * similarly must still be freed by the caller by calling asl_free() if the 903 * caller loses reference to it. Any changes made to it after calling 904 * asl_log_descriptor() are not applicable to the message used. descriptor 905 * is treated differentlty based on the value of fd_type. 906 * 907 * If fd_type is ASL_LOG_DESCRIPTOR_READ, the descriptor must be open for read 908 * access. ASL uses GCD to read from the descriptor as data becomes available. 909 * These data are line buffered and passed to asl_log. When EOF is read, the 910 * descriptor is closed. 911 * 912 * Example: 913 * asl_log_descriptor(c, m, ASL_LEVEL_NOTICE, STDIN_FILENO, ASL_LOG_DESCRIPTOR_READ); 914 * 915 * If fd_type is ASL_LOG_DESCRIPTOR_WRITE, the descriptor is closed and a new 916 * writable descriptor is created with the same fileno. Any data written to 917 * this new descriptor are line buffered and passed to asl_log. When EOF is 918 * sent, no further data are read. The caller is responsible for closing the 919 * new descriptor. One common use for this API is to redirect writes to stdout 920 * or stderr to ASL by passing STDOUT_FILENO or STDERR_FILENO as descriptor. 921 * 922 * Example: 923 * asl_log_descriptor(c, m, ASL_LEVEL_NOTICE, STDOUT_FILENO, ASL_LOG_DESCRIPTOR_WRITE); 924 * asl_log_descriptor(c, m, ASL_LEVEL_ERR, STDERR_FILENO, ASL_LOG_DESCRIPTOR_WRITE); 925 * 926 * @param client 927 * (input) An ASL object of type ASL_TYPE_CLIENT. 928 * @param msg 929 * (input) An asl_object_t of type ASL_TYPE_MSG (default attributes will be supplied if msg is NULL). 930 * @param level 931 * (input) Log level (ASL_LEVEL_DEBUG to ASL_LEVEL_EMERG) 932 * @param descriptor 933 * (input) An open file descriptor to read from 934 * @param fd_type 935 * (input) Either ASL_LOG_DESCRIPTOR_READ or ASL_LOG_DESCRIPTOR_WRITE 936 * @result Returns 0 for success, non-zero for failure 937 */ 938 int asl_log_descriptor(asl_object_t asl, asl_object_t msg, int level, int descriptor, uint32_t fd_type) __OSX_AVAILABLE_STARTING(__MAC_10_8,__IPHONE_5_1); 939 940 #pragma mark - 941 942 943 /*! 944 * Creates a string representation of an ASL message. 945 * 946 * This utility creates a character string suitable for printing an ASL message. 947 * The returned string ends with a newline character. The caller is responsible 948 * for freeing the returned string. 949 * The message is formatted according to the specified format string. Timestamps 950 * are formatted accoring to the specified time format string. Special characters 951 * are enoded as specified by the text_encoding parameter. 952 * 953 * @param msg 954 * (input) An asl_object_t of type ASL_TYPE_MSG. 955 * @param fmt 956 * (input) A format specification string. See "Output file message and time formats" 957 * for standard formats. See the syslog(1) man page for more discussion on formats. 958 * @param fmt 959 * (input) A time format specification string. See "Output file message and time formats" 960 * for standard formats. See the syslog(1) man page for more discussion on time formats. 961 * @param text_encoding 962 * (input) Text encoding control (for special characters). See "Text Encoding Types". 963 * @result Returns a character string, or NULL in case of a failure. 964 */ 965 char *asl_format(asl_object_t msg, const char *msg_fmt, const char *time_fmt, uint32_t text_encoding) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 966 967 /*! 968 * Encodes a buffer with embedded nul characters into a nul terminated C string. 969 * The result must be freed by the caller. 970 * 971 * This utility is used to encode the value associated with ASL_KEY_AUX_DATA 972 * in an ASL_TYPE_MSG object. An ASL_KEY_AUX_DATA key/value pair is used to hold the 973 * data written to a file descriptor created by asl_create_auxiliary_file on iOS 974 * systems, where the ASL database is stored in memory. 975 * 976 * @param buf 977 * (input) Pointer to a data buffer. 978 * @param len 979 * (input) Length (in octets) of data buffer. 980 * @result Returns an encoded character string. 981 */ 982 char *asl_encode_buffer(const char *buf, size_t len) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 983 984 /*! 985 * Decodes a C string previously created by asl_encode_buffer back into a buffer, 986 * possibly containing embedded nul characters. Allocates memory for the buffer 987 * and returns a pointer in an output parameter "buf". 988 * The caller is responsible for freeing the buffer. 989 * 990 * This routine should be used to decode the value associated with an 991 * ASL_KEY_AUX_DATA key in an ASL_TYPE_MSG object. 992 * 993 * @param in 994 * (input) Pointer to nul-terminated string created by asl_encode_buffer. 995 * @param buf 996 * (output) Pointer to a newly allocated data buffer. 997 * @param len 998 * (input) Length (in octets) of data buffer. 999 * @result Returns 0 on success, non-zero on failure. 1000 */ 1001 int asl_decode_buffer(const char *in, char **buf, size_t *len) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 1002 1003 /*! 1004 * Iterate forward through messages in an asl_object_t. 1005 * The asl_object_t object maintains an internal position index for the underlying 1006 * collection of ASL messages, whether the asl_object_t represents a list, a 1007 * data file, or an ASL database. The position index is moved forward and the 1008 * "next" message is returned. 1009 * 1010 * @param obj 1011 * (input) An asl_object_t. 1012 * @result Returns the next message (an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY) from the object, 1013 * which should be of type ASL_TYPE_CLIENT, ASL_TYPE_LIST, ASL_TYPE_STORE, or ASL_TYPE_FILE. 1014 * Returns NULL when there are no more messages or if obj is not a type that holds messages. 1015 */ 1016 asl_object_t asl_next(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 1017 1018 /*! 1019 * Iterate backwards through messages in an asl_object_t. 1020 * The asl_object_t object maintains an internal position index for the underlying 1021 * collection of ASL messages, whether the asl_object_t represents a list, a 1022 * data file, or an ASL database. The position index is moved backward and the 1023 * "previous" message is returned. 1024 * 1025 * @param data 1026 * (input) An asl_object_t. 1027 * @result Returns the previous message (an object of type ASL_TYPE_MSG or ASL_TYPE_QUERY) from the object, 1028 * which should be of type ASL_TYPE_CLIENT, ASL_TYPE_LIST, ASL_TYPE_STORE, or ASL_TYPE_FILE. 1029 * Returns NULL when there are no more messages or if obj is not a type that holds messages. 1030 */ 1031 asl_object_t asl_prev(asl_object_t obj) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 1032 1033 /*! 1034 * Reset internal interation index in an asl_object_t. 1035 * 1036 * @param obj 1037 * (input) An object of type ASL_TYPE_CLIENT, ASL_TYPE_LIST, ASL_TYPE_STORE, or ASL_TYPE_FILE. 1038 * @param position 1039 * (input) Use 0 to position the internal interation index at the beginning of the asl_object_t object, 1040 * and SIZE_MAX to position it at the end. Other values of position may cause unpredictable behavior. 1041 */ 1042 void asl_reset_iteration(asl_object_t obj, size_t position) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 1043 1044 /*! 1045 * Searches an asl_object_t. 1046 * The search is controlled by a list of queries, and returns a list with matching messages. 1047 * A message is returned if it matches any of the queries in the query list. 1048 * A NULL querylist matches anything. 1049 * 1050 * The caller may provide a starting ASL message ID, a direction, and a count. 1051 * A start ID value of 0 means that matching should commence at the beginning of the target obj. 1052 * A value of SIZE_MAX indicates that matching should commence at the end (most recent message) 1053 * in the target. If a non-zero count value is supplied, the routine will return when it has 1054 * found that many messages, or it has checked all messages. If a non-zero duration is supplied, 1055 * the routine will return after the specified time (in microseconds). 1056 * If both count and duration are non-zero, the routine will return when the desired number of 1057 * items has been matched or when the specified duration has been exceeded, whichever occurs first. 1058 * The search direction may be ASL_MATCH_DIRECTION_FORWARD or ASL_MATCH_DIRECTION_REVERSE. 1059 * The routine sets the value of the out parameter last to be an index of the last message 1060 * checked while matching. To fetch matching messages in batches (using a small count or 1061 * duration value), the start value for each iteration should be set to (last + 1) if searching 1062 * forward, or (last - 1)for reverse search. 1063 * 1064 * @param data 1065 * (input) An asl_object_t object. 1066 * @param querylist 1067 * (input) An asl_object_t object containing zero or more queries. 1068 * @param last 1069 * (output) An internal position index of the last message checked while matching in the asl_object_t object. 1070 * @param start 1071 * (input) A position index specifying where matching should commence. 1072 * @param count 1073 * (input) The maximum number of messages to be returned in the res output list (zero indicates no limit). 1074 * @param duration 1075 * (input) A limit (in microseconds) on the time to be spent searching for results. Zero indicates no time limit. 1076 * @param direction 1077 * (input) ASL_MATCH_DIRECTION_FORWARD or ASL_MATCH_DIRECTION_REVERSE. 1078 * @result Returns an ASL object containing messages matching the querylist, or NULL if there are no matches. 1079 */ 1080 asl_object_t asl_match(asl_object_t data, asl_object_t querylist, size_t *last, size_t start, size_t count, uint32_t duration, int32_t direction) __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0); 1081 1082 __END_DECLS 1083 1084 #endif /* __ASL_H__ */ 1085