| 1 | .\" Copyright (c) 2005-2010 Apple Inc. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms, with or without |
| 5 | .\" modification, are permitted provided that the following conditions |
| 6 | .\" are met: |
| 7 | .\" 1. Redistributions of source code must retain the above copyright |
| 8 | .\" notice, this list of conditions and the following disclaimer. |
| 9 | .\" 2. Redistributions in binary form must reproduce the above copyright |
| 10 | .\" notice, this list of conditions and the following disclaimer in the |
| 11 | .\" documentation and/or other materials provided with the distribution. |
| 12 | .\" 4. Neither the name of Apple Computer nor the names of its contributors |
| 13 | .\" may be used to endorse or promote products derived from this software |
| 14 | .\" without specific prior written permission. |
| 15 | .\" |
| 16 | .\" THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER AND CONTRIBUTORS ``AS IS'' AND |
| 17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| 18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| 19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| 20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| 21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| 22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| 23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| 24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| 25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| 26 | .\" SUCH DAMAGE. |
| 27 | .\" |
| 28 | .\" |
| 29 | .Dd March 3, 2010 |
| 30 | .Dt asl 3 |
| 31 | .Os "Mac OS X" |
| 32 | .Sh NAME |
| 33 | .Nm asl_add_log_file , |
| 34 | .Nm asl_close , |
| 35 | .Nm asl_close_auxiliary_file , |
| 36 | .Nm asl_create_auxiliary_file , |
| 37 | .Nm asl_free , |
| 38 | .Nm asl_get , |
| 39 | .Nm asl_key , |
| 40 | .Nm asl_log , |
| 41 | .Nm asl_log_auxiliary_location , |
| 42 | .Nm asl_new , |
| 43 | .Nm asl_open , |
| 44 | .Nm asl_open_from_file , |
| 45 | .Nm asl_remove_log_file , |
| 46 | .Nm asl_search , |
| 47 | .Nm asl_send , |
| 48 | .Nm asl_set , |
| 49 | .Nm asl_set_filter , |
| 50 | .Nm asl_set_query , |
| 51 | .Nm asl_unset , |
| 52 | .Nm asl_vlog , |
| 53 | .Nm aslresponse_free , |
| 54 | .Nm aslresponse_next |
| 55 | .Nd system log message sending and searching functions |
| 56 | .Sh SYNOPSIS |
| 57 | .Fd #include <asl.h> |
| 58 | .\" |
| 59 | .Ft int |
| 60 | .Fo asl_add_log_file |
| 61 | .Fa "aslclient asl" |
| 62 | .Fa "int fd" |
| 63 | .Fc |
| 64 | .Ft void |
| 65 | .Fo asl_close |
| 66 | .Fa "aslclient asl" |
| 67 | .Fc |
| 68 | .Ft void |
| 69 | .Fo asl_close_auxiliary_file |
| 70 | .Fa "int fd" |
| 71 | .Fc |
| 72 | .Ft void |
| 73 | .Fo asl_create_auxiliary_file |
| 74 | .Fa "aslmsg msg" |
| 75 | .Fa "const char *title" |
| 76 | .Fa "const char *uti" |
| 77 | .Fa "int *out_fd" |
| 78 | .Fc |
| 79 | .Ft void |
| 80 | .Fo asl_free |
| 81 | .Fa "aslmsg msg" |
| 82 | .Fc |
| 83 | .Ft const char * |
| 84 | .Fo asl_get |
| 85 | .Fa "aslmsg msg" |
| 86 | .Fa "const char *key" |
| 87 | .Fc |
| 88 | .Ft const char * |
| 89 | .Fo asl_key |
| 90 | .Fa "aslmsg msg" |
| 91 | .Fa "uint32_t n" |
| 92 | .Fc |
| 93 | .Ft int |
| 94 | .Fo asl_log |
| 95 | .Fa "aslclient asl" |
| 96 | .Fa "aslmsg msg" |
| 97 | .Fa "int level" |
| 98 | .Fa "const char *format" |
| 99 | .Fa "..." |
| 100 | .Fc |
| 101 | .Ft void |
| 102 | .Fo asl_log_auxiliary_location |
| 103 | .Fa "aslmsg msg" |
| 104 | .Fa "const char *title" |
| 105 | .Fa "const char *uti" |
| 106 | .Fa "const char *url" |
| 107 | .Fc |
| 108 | .Ft aslmsg |
| 109 | .Fo asl_new |
| 110 | .Fa "uint32_t type" |
| 111 | .Fc |
| 112 | .Ft aslclient |
| 113 | .Fo asl_open |
| 114 | .Fa "const char *ident" |
| 115 | .Fa "const char *facility" |
| 116 | .Fa "uint32_t opts" |
| 117 | .Fc |
| 118 | .Ft aslclient |
| 119 | .Fo asl_open_from_file |
| 120 | .Fa "int fd" |
| 121 | .Fa "const char *ident" |
| 122 | .Fa "const char *facility" |
| 123 | .Fc |
| 124 | .Ft int |
| 125 | .Fo asl_remove_log_file |
| 126 | .Fa "aslclient asl" |
| 127 | .Fa "int fd" |
| 128 | .Fc |
| 129 | .Ft aslresponse |
| 130 | .Fo asl_search |
| 131 | .Fa "aslclient asl" |
| 132 | .Fa "aslmsg msg" |
| 133 | .Fc |
| 134 | .Ft int |
| 135 | .Fo asl_send |
| 136 | .Fa "aslclient asl" |
| 137 | .Fa "aslmsg msg" |
| 138 | .Fc |
| 139 | .Ft int |
| 140 | .Fo asl_set |
| 141 | .Fa "aslmsg msg" |
| 142 | .Fa "const char *key" |
| 143 | .Fa "const char *value" |
| 144 | .Fc |
| 145 | .Ft int |
| 146 | .Fo asl_set_filter |
| 147 | .Fa "aslclient asl" |
| 148 | .Fa "int f" |
| 149 | .Fc |
| 150 | .Ft int |
| 151 | .Fo asl_set_query |
| 152 | .Fa "aslmsg msg" |
| 153 | .Fa "const char *key" |
| 154 | .Fa "const char *value" |
| 155 | .Fa "uint32_t op" |
| 156 | .Fc |
| 157 | .Ft int |
| 158 | .Fo asl_unset |
| 159 | .Fa "aslmsg msg" |
| 160 | .Fa "const char *key" |
| 161 | .Fc |
| 162 | .Ft int |
| 163 | .Fo asl_vlog |
| 164 | .Fa "aslclient asl" |
| 165 | .Fa "aslmsg msg" |
| 166 | .Fa "int level" |
| 167 | .Fa "const char *format" |
| 168 | .Fa "va_list ap" |
| 169 | .Fc |
| 170 | .Ft void |
| 171 | .Fo aslresponse_free |
| 172 | .Fa "aslresponse r" |
| 173 | .Fc |
| 174 | .Ft aslmsg |
| 175 | .Fo aslresponse_next |
| 176 | .Fa "aslresponse r" |
| 177 | .Fc |
| 178 | .Sh DESCRIPTION |
| 179 | These routines provide an interface to the Apple System Log facility. |
| 180 | They are intended to be a replacement for the |
| 181 | .Xr syslog 3 |
| 182 | API, which will continue to be supported for backwards compatibility. |
| 183 | The new API allows client applications |
| 184 | to create flexible, structured messages and send them to the |
| 185 | .Nm syslogd |
| 186 | server, where they may undergo additional processing. |
| 187 | Messages received by the server are saved in a data store |
| 188 | (subject to input filtering constraints). |
| 189 | This API permits clients to create queries |
| 190 | and search the message data store for matching messages. |
| 191 | .Pp |
| 192 | An introduction to the concepts underlying this interface follows the interface summary below. |
| 193 | .Ss INTERFACE SUMMARY |
| 194 | .Fo asl_open |
| 195 | .Fa ident |
| 196 | .Fa facility |
| 197 | .Fa opts |
| 198 | .Fc |
| 199 | creates and returns a client handle, or NULL if an error occurs in the library. |
| 200 | Messages sent using this handle will default to having the string |
| 201 | .Ar ident |
| 202 | as the value associated with the ASL_KEY_SENDER key, and the value |
| 203 | .Ar facility |
| 204 | associated with the ASL_KEY_FACILITY key. |
| 205 | Several options are available, as described in the |
| 206 | .Sx CLIENT HANDLES |
| 207 | section. |
| 208 | .Pp |
| 209 | Multi-threaded applications should create one client handle for each thread that logs messages. |
| 210 | A client may use NULL as a client handle, in which case a default handle managed by the library will be used. |
| 211 | A NULL handle may be used safely by multiple threads, but the threads will contend for a single internal lock when |
| 212 | sending log messages using a NULL handle. |
| 213 | .Pp |
| 214 | .Fo asl_close |
| 215 | .Fa asl |
| 216 | .Fc |
| 217 | closes the client handle |
| 218 | .Ar asl |
| 219 | and releases its associated resources. |
| 220 | .Pp |
| 221 | .Fo asl_add_log_file |
| 222 | .Fa asl |
| 223 | .Fa fd |
| 224 | .Fc |
| 225 | adds the file descriptor |
| 226 | .Ar fd |
| 227 | to the a set of file descriptors associated with the client handle |
| 228 | .Ar asl . |
| 229 | Each log message sent by that client handle is also written to these file descriptors. |
| 230 | Returns 0 on success, non-zero on failure. |
| 231 | .Pp |
| 232 | .Fo asl_remove_log_file |
| 233 | .Fa asl |
| 234 | .Fa fd |
| 235 | .Fc |
| 236 | removes a file descriptor from the set of file descriptors associated with a client handle. |
| 237 | Returns 0 on success, non-zero on failure. |
| 238 | .Pp |
| 239 | .Fo asl_new |
| 240 | .Fa type |
| 241 | .Fc |
| 242 | allocates and returns an aslmsg structure, or NULL in the case of a failure in the library. |
| 243 | The |
| 244 | .Ar type |
| 245 | argument must be ASL_TYPE_MSG or ASL_TYPE_QUERY. |
| 246 | .Pp |
| 247 | .Fo asl_free |
| 248 | .Fa msg |
| 249 | .Fc |
| 250 | frees an aslmsg and releases resources associated with the structure. |
| 251 | .Pp |
| 252 | .Fo asl_set |
| 253 | .Fa msg |
| 254 | .Fa key |
| 255 | .Fa value |
| 256 | .Fc |
| 257 | creates a new key and value in an aslmsg structure, or replaces the value of an existing key. |
| 258 | Returns 0 on success, non-zero on failure. |
| 259 | .Pp |
| 260 | .Fo asl_set_query |
| 261 | .Fa msg |
| 262 | .Fa key |
| 263 | .Fa op |
| 264 | .Fa value |
| 265 | .Fc |
| 266 | is used to construct searches. |
| 267 | It is similar to |
| 268 | .Fn asl_set , |
| 269 | except that it takes an additional |
| 270 | .Ar op |
| 271 | (operation) argument. |
| 272 | Creates a new (key, op, value) triple in an aslmsg structure, |
| 273 | or replaces the value and operation for an existing key. |
| 274 | See the |
| 275 | .Sx SEARCHING |
| 276 | section for more information. |
| 277 | Returns 0 on success, non-zero on failure. |
| 278 | .Pp |
| 279 | .Fo asl_unset |
| 280 | .Fa msg |
| 281 | .Fa key |
| 282 | .Fc |
| 283 | removes a key and its associated value from an aslmsg structure. |
| 284 | Returns 0 on success, non-zero on failure. |
| 285 | .Pp |
| 286 | .Fo asl_key |
| 287 | .Fa msg |
| 288 | .Fa n |
| 289 | .Fc |
| 290 | returns the nth key in an aslmsg (beginning at zero), |
| 291 | allowing an application to iterate through the keys. |
| 292 | Returns NULL if |
| 293 | .Ar n |
| 294 | indexes beyond the number of keys in |
| 295 | .Ar msg . |
| 296 | .Pp |
| 297 | .Fo asl_get |
| 298 | .Fa msg |
| 299 | .Fa key |
| 300 | .Fc |
| 301 | returns the value associated with |
| 302 | .Ar key |
| 303 | in the aslmsg |
| 304 | .Ar msg . |
| 305 | Returns NULL if |
| 306 | .Ar msg |
| 307 | does not contain |
| 308 | . Ar key . |
| 309 | .Pp |
| 310 | .Fo asl_set_filter |
| 311 | .Fa asl |
| 312 | .Fa f |
| 313 | .Fc |
| 314 | sets a filter for messages being sent to the server. |
| 315 | The filter is a bitmask representing priority levels. |
| 316 | Only messages having a priority level with a corresponding bit set in the filter mask are sent to the |
| 317 | .Nm syslogd |
| 318 | server. |
| 319 | The filter does not control writes to additional files associated with the client handle using |
| 320 | .Fn asl_add_log_file . |
| 321 | Returns the previous filter value. |
| 322 | .Pp |
| 323 | .Fo asl_log |
| 324 | .Fa asl |
| 325 | .Fa msg |
| 326 | .Fa level |
| 327 | .Fa format |
| 328 | .Fa args... |
| 329 | .Fc |
| 330 | sends a log to the server (subject to filtering, see |
| 331 | .Fn asl_set_filter |
| 332 | above) and to any file descriptors associated with the client handle |
| 333 | .Ar asl . |
| 334 | The |
| 335 | .Ar msg |
| 336 | argument may contain any keys and values, which will be formatted as part of the log message. |
| 337 | The value for ASL_KEY_LEVEL is supplied by the |
| 338 | .Ar level |
| 339 | argument. |
| 340 | The value for ASL_KEY_MESSAGE is computed from |
| 341 | .Ar format |
| 342 | and the associated arguments |
| 343 | .Ar args... . |
| 344 | Normal |
| 345 | .Fn printf |
| 346 | style argument processing is applied to the format and the arguments. |
| 347 | The format may also contain |
| 348 | .Dq %m |
| 349 | which will be substituted with the string value corresponding to the current |
| 350 | .Em errno . |
| 351 | .Pp |
| 352 | .Fo asl_vlog |
| 353 | .Fa asl |
| 354 | .Fa msg |
| 355 | .Fa level |
| 356 | .Fa format |
| 357 | .Fa ap |
| 358 | .Fc |
| 359 | is similar to |
| 360 | .Fn asl_log |
| 361 | except that it takes a va_list argument. |
| 362 | .Pp |
| 363 | .Fo asl_send |
| 364 | .Fa asl |
| 365 | .Fa msg |
| 366 | .Fc |
| 367 | is similar to |
| 368 | .Fn asl_log , |
| 369 | exceopt the value for ASL_KEY_MESSAGE is taken from |
| 370 | .Ar msg |
| 371 | rather than being constructed using a |
| 372 | .Fn printf |
| 373 | style syntax. |
| 374 | .Pp |
| 375 | .Fo asl_search |
| 376 | .Fa asl |
| 377 | .Fa msg |
| 378 | .Fc |
| 379 | searches for messages that match the keys and values in |
| 380 | .Ar msg , |
| 381 | subject to matching operations associated with those keys and values. |
| 382 | The |
| 383 | .Ar msg |
| 384 | argument should be constructed using |
| 385 | .Fn asl_set_query . |
| 386 | See the |
| 387 | .Sx SEARCHING |
| 388 | section for details on constructing queries. |
| 389 | Returns an aslresponse structure that contains matching log messages. |
| 390 | NULL is returned in case of error or if there are no matching messages in the ASL database. |
| 391 | .Pp |
| 392 | .Fo aslresponse_next |
| 393 | .Fa r |
| 394 | .Fc |
| 395 | iterates over an aslresponse structure returned by |
| 396 | .Fn asl_search . |
| 397 | Each call returns the next aslmsg in the response. |
| 398 | Returns NULL when there are no further messages. |
| 399 | .Pp |
| 400 | .Fo aslresponse_free |
| 401 | .Fa r |
| 402 | .Fc |
| 403 | frees the aslresponse structure |
| 404 | .Ar r |
| 405 | and all of its associated resources. |
| 406 | .Pp |
| 407 | .Fo asl_create_auxiliary_file |
| 408 | .Fa msg |
| 409 | .Fa title |
| 410 | .Fa uti |
| 411 | .Fa out_fd |
| 412 | .Fc |
| 413 | Creates an auxiliary file that may be used by the client to save arbitrary data. |
| 414 | When the file is closed using |
| 415 | .Fo asl_close_auxiliary_file |
| 416 | .Fc , |
| 417 | .Nm syslogd |
| 418 | will log the specified |
| 419 | .Fa msg |
| 420 | along with the |
| 421 | .Fa title |
| 422 | and the Uniform Type Identifier provided by |
| 423 | .Fa uti . |
| 424 | If a NULL value is supplied for |
| 425 | .Fa uti |
| 426 | the type |
| 427 | .Dq public.data |
| 428 | will be used. |
| 429 | The |
| 430 | .Nm Console |
| 431 | application will display the message with a link to the file. |
| 432 | .Pp |
| 433 | Auxiliary files are saved in the ASL data store. |
| 434 | They are automatically deleted at the same time that the log message expires. |
| 435 | Messages expire in 7 days by default. |
| 436 | A value set for the ASLExpireTime key will override the default. |
| 437 | Read access for the auxiliary file will be the same as read access for |
| 438 | .Fa msg . |
| 439 | By default, messages (and auxiliary files) are world-readable. |
| 440 | Access may be limited by setting values for the ReadUID and ReadGID keys. |
| 441 | .Pp |
| 442 | .Fo asl_close_auxiliary_file |
| 443 | .Fa fd |
| 444 | .Fc |
| 445 | closes the file descriptor |
| 446 | .Ar fd |
| 447 | previously returned by a call to |
| 448 | .Fn asl_create_auxiliary_file . |
| 449 | .Pp |
| 450 | .Fo asl_log_auxiliary_location |
| 451 | .Fa msg |
| 452 | .Fa title |
| 453 | .Fa uti |
| 454 | .Fa url |
| 455 | .Fc |
| 456 | will log the specified |
| 457 | .Fa msg |
| 458 | along with the |
| 459 | .Fa title , |
| 460 | the Uniform Type Identifier provided by |
| 461 | .Fa uti , |
| 462 | and the Uniform Resource Locator provided by |
| 463 | .Fa url . |
| 464 | The |
| 465 | .Nm Console |
| 466 | application will display the message with a link to the file. |
| 467 | This allows a client to save data in an auxiliary file, but unlike |
| 468 | .Fo asl_create_auxiliary_file |
| 469 | .Fc , |
| 470 | the life-cycle of this file must be managed by some external system. |
| 471 | The file will not be removed when the corresponding log message expired from the ASL data store. |
| 472 | .Pp |
| 473 | .Fo asl_open_from_file |
| 474 | .Fa fd |
| 475 | .Fa facility |
| 476 | .Fa opts |
| 477 | .Fc |
| 478 | creates a client handle for an open file descriptor |
| 479 | .Fa fd . |
| 480 | This routine may be used in conjunction with |
| 481 | .Fo asl_create_auxiliary_file |
| 482 | .Fc |
| 483 | or |
| 484 | .Fo asl_log_auxiliary_location |
| 485 | .Fc |
| 486 | to save ASL format log messages in an auxiliary file. |
| 487 | The UTI type |
| 488 | .Dq com.apple.asl-file |
| 489 | should be used for ASL format auxiliary files. |
| 490 | .Pp |
| 491 | Files with this format may be read from the command line using |
| 492 | .Nm syslog Fl f Ar file , |
| 493 | or from the |
| 494 | .Nm Console |
| 495 | utility. |
| 496 | .Pp |
| 497 | The file must be open for read and write access. |
| 498 | The file will be truncated and its existing contents will be lost. |
| 499 | .Fo asl_close |
| 500 | .Fc |
| 501 | must be called to close the client handle when logging to this file is complete. |
| 502 | The file should be closed using |
| 503 | .Fo asl_close_auxiliary_file |
| 504 | .Fc |
| 505 | if it was returned by |
| 506 | .Fo asl_create_auxiliary_file |
| 507 | .Fc , |
| 508 | or |
| 509 | .Fo close |
| 510 | .Fc |
| 511 | otherwise. |
| 512 | .Pp |
| 513 | The client handle may be used safely by multiple threads. |
| 514 | The threads will contend for a single internal lock when saving log messages to a file. |
| 515 | .Pp |
| 516 | Note that messages with ReadUID or ReadGID values will simply be saved to the file, |
| 517 | and will not effect read access to either the message or the file itself. |
| 518 | Similarly, messages with ASLExpireTime values will be saved, but will not effect the |
| 519 | life-cycle of either the individual messages or the file. |
| 520 | .Ss MESSAGES |
| 521 | At the core of this API is the aslmsg structure. |
| 522 | Although the structure is opaque and may not be directly manipulated, |
| 523 | it contains a list of key/value pairs. |
| 524 | All keys and values are NUL-character terminated C language strings. |
| 525 | UTF-8 encoding may be used for non-ASCII characters. |
| 526 | .Pp |
| 527 | Message structures are generally used to send log messages, |
| 528 | and are created thusly: |
| 529 | .Pp |
| 530 | aslmsg m = asl_new(ASL_TYPE_MSG); |
| 531 | .Pp |
| 532 | Another message type, ASL_TYPE_QUERY, |
| 533 | is used to create queries when searching the data store. |
| 534 | Query type messages and searching are described in detail in the |
| 535 | .Sx SEARCHING |
| 536 | section. |
| 537 | For the remainder of this section, |
| 538 | the messages described will be of the ASL_TYPE_MSG variety. |
| 539 | .Pp |
| 540 | Each aslmsg contains a default set of keys |
| 541 | and values that are associated with them. |
| 542 | These keys are listed in the asl.h header file. |
| 543 | They are: |
| 544 | .Pp |
| 545 | #define ASL_KEY_TIME "Time" |
| 546 | #define ASL_KEY_HOST "Host" |
| 547 | #define ASL_KEY_SENDER "Sender" |
| 548 | #define ASL_KEY_FACILITY "Facility" |
| 549 | #define ASL_KEY_PID "PID" |
| 550 | #define ASL_KEY_UID "UID" |
| 551 | #define ASL_KEY_GID "GID" |
| 552 | #define ASL_KEY_LEVEL "Level" |
| 553 | #define ASL_KEY_MSG "Message" |
| 554 | .Pp |
| 555 | Many of these correspond to equivalent parts of messages described in the |
| 556 | .Xr syslog 3 |
| 557 | API. |
| 558 | Values associated with these message keys are assigned appropriate defaults. |
| 559 | The value for ASL_KEY_HOST is the local host name, |
| 560 | the value associated with ASL_KEY_SENDER is the process name, |
| 561 | the ASL_KEY_PID is the client's process ID number, and so on. |
| 562 | .Pp |
| 563 | Note the addition of the UID and GID keys. |
| 564 | The values for UID and GID are set in library code by the message sender. |
| 565 | The server will attempt to confirm the values, |
| 566 | but no claim is made that these values cannot be maliciously overridden |
| 567 | in an attempt to deceive a log message reader |
| 568 | as to the identity of the sender of a message. |
| 569 | The contents of log messages must be regarded as insecure. |
| 570 | .Pp |
| 571 | The |
| 572 | .Xr asl 3 |
| 573 | API does not require a process to choose a facility name. |
| 574 | The |
| 575 | .Nm syslogd |
| 576 | server will use a default value of |
| 577 | .Dq user |
| 578 | if a facility is not set. |
| 579 | However, a client may set a facility name as an argument in the |
| 580 | .Nm asl_open |
| 581 | call, or by setting a specific value for the ASL_KEY_FACILITY in a message: |
| 582 | .Pp |
| 583 | asl_set(m, ASL_KEY_FACILITY, "com.somename.greatservice"); |
| 584 | .Pp |
| 585 | An application may choose any facility name at will. |
| 586 | Different facility names may be attached to different messages, perhaps to distinguish different subsystems in log messages. |
| 587 | Developers are encouraged to adopt a |
| 588 | .Dq Reverse ICANN |
| 589 | naming convention to avoid conflicting facility names. |
| 590 | .Pp |
| 591 | Default values are set in the message for each of the keys listed above, |
| 592 | except for ASL_KEY_MSG, |
| 593 | which may be explicitly set at any time using the |
| 594 | .Nm asl_set |
| 595 | routine, or implicitly set at the time the message is sent using the |
| 596 | .Nm asl_log |
| 597 | or |
| 598 | .Nm asl_vlog |
| 599 | routines. |
| 600 | These two routines also have an integer-level parameter |
| 601 | for specifying the log priority. |
| 602 | The ASL_KEY_LEVEL value is set accordingly. |
| 603 | Finally, the value associated with ASL_KEY_TIME |
| 604 | is set in the sending routine. |
| 605 | .Pp |
| 606 | Although it may appear that there is significant overhead required |
| 607 | to send a log message using this API, |
| 608 | the opposite is actually true. |
| 609 | A simple |
| 610 | .Dq Hello World |
| 611 | program requires only: |
| 612 | .Pp |
| 613 | #include <asl.h> |
| 614 | ... |
| 615 | asl_log(NULL, NULL, ASL_LEVEL_INFO, "Hello World!"); |
| 616 | .Pp |
| 617 | Both |
| 618 | .Nm asl_log |
| 619 | and |
| 620 | .Nm asl_vlog |
| 621 | will provide the appropriate default values |
| 622 | when passed a NULL aslmsg argument. |
| 623 | .Pp |
| 624 | .Pp |
| 625 | In this example, the aslclient argument is NULL. |
| 626 | This is sufficient for a single-threaded application, |
| 627 | or for an application which only sends log messages from a single thread. |
| 628 | When logging from multiple threads, |
| 629 | each thread |
| 630 | .Em should |
| 631 | open a separate client handle using |
| 632 | .Nm asl_open . |
| 633 | The client handle may then be closed when it is no longer required using |
| 634 | .Nm asl_close . |
| 635 | Multiple threads may log messages safely using a NULL aslclient argument, |
| 636 | but the library will use an internal lock, so that in fact only one thread |
| 637 | will log at a time. |
| 638 | .Pp |
| 639 | When an application requires additional keys and values |
| 640 | to be associated with each log message, |
| 641 | a single message structure may be allocated and set up as |
| 642 | .Dq template |
| 643 | message of sorts: |
| 644 | .Pp |
| 645 | aslmsg m = asl_new(ASL_TYPE_MSG); |
| 646 | asl_set(m, ASL_KEY_FACILITY, "com.secrets.r.us"); |
| 647 | asl_set(m, "Clearance", "Top Secret"); |
| 648 | ... |
| 649 | asl_log(NULL, m, ASL_LEVEL_NOTICE, "Message One"); |
| 650 | ... |
| 651 | asl_log(NULL, m, ASL_LEVEL_ERR, "Message Two"); |
| 652 | .Pp |
| 653 | The message structure will carry the values set for the |
| 654 | .Dq Facility |
| 655 | and |
| 656 | .Dq Clearance |
| 657 | keys so that they are used in each call to |
| 658 | .Nm asl_log , |
| 659 | while the log level and the message text |
| 660 | are taken from the calling parameters. |
| 661 | .Pp |
| 662 | The |
| 663 | .Ar format |
| 664 | argument to |
| 665 | .Nm asl_log |
| 666 | and |
| 667 | .Nm asl_vlog |
| 668 | is identical to |
| 669 | .Xr printf 3 , |
| 670 | and may include |
| 671 | .Ql %m , |
| 672 | which is replaced by the current error message |
| 673 | (as denoted by the global variable |
| 674 | .Va errno ; |
| 675 | see |
| 676 | .Xr strerror 3 . ) |
| 677 | .Pp |
| 678 | Key/value pairs may be removed from a message structure with |
| 679 | .Nm asl_unset . |
| 680 | A message may be freed using |
| 681 | .Nm asl_free . |
| 682 | .Pp |
| 683 | The |
| 684 | .Nm asl_send |
| 685 | routine is used by |
| 686 | .Nm asl_log |
| 687 | and |
| 688 | .Nm asl_vlog |
| 689 | to transmit a message to the server. |
| 690 | This routine sets the value associated with ASL_KEY_TIME |
| 691 | and sends the message. |
| 692 | It may be called directly if all of a message's key/value pairs |
| 693 | have been created using |
| 694 | .Nm asl_set . |
| 695 | .Ss SECURITY |
| 696 | Messages that are sent to the |
| 697 | .Nm syslogd |
| 698 | server may be saved in a message store. |
| 699 | The store may be searched using |
| 700 | .Nm asl_search , |
| 701 | as described below. |
| 702 | By default, all messages are readable by any user. |
| 703 | However, some applications may wish to restrict read access |
| 704 | for some messages. |
| 705 | To accomodate this, |
| 706 | a client may set a value for the "ReadUID" and "ReadGID" keys. |
| 707 | These keys may be associated with a value |
| 708 | containing an ASCII representation of a numeric UID or GID. |
| 709 | Only the root user (UID 0), |
| 710 | the user with the given UID, |
| 711 | or a member of the group with the given GID |
| 712 | may fetch access-controlled messages from the database. |
| 713 | .Pp |
| 714 | Although the ASL system does not require a "Facility" key in a message, |
| 715 | many processes specify a "Facility" value similar |
| 716 | to the common usage of the BSD |
| 717 | .Nm syslog |
| 718 | API, although developers are encouraged to adopt facility names that make sense for their application. |
| 719 | A |
| 720 | .Dq Reverse ICANN |
| 721 | naming convention (e.g. "com.apple.system.syslog") should be adopted to avoid conflicting names. |
| 722 | The ASL system generally allows any string to be used as a facility value, |
| 723 | with one exception. |
| 724 | The value "com.apple.system", |
| 725 | or any string that has "com.apple.system" as a prefix, |
| 726 | may only be used by processes running with the UID 0. |
| 727 | This allows system processes to log messages that can not be "spoofed" by user processes. |
| 728 | Non-UID 0 client processes that specify "com.apple.system" as a facility, will be assigned the value "user" |
| 729 | by the |
| 730 | .Nm syslogd |
| 731 | server. |
| 732 | .Ss CLIENT HANDLES |
| 733 | When logging is done from a single thread, |
| 734 | a NULL value may be used in any of the routines |
| 735 | that require an aslclient argument. |
| 736 | In this case, the library will open an internal client handle |
| 737 | on behalf of the application. |
| 738 | .Pp |
| 739 | If multiple threads must do logging, |
| 740 | or if client options are desired, |
| 741 | then the application should call |
| 742 | .Nm asl_open |
| 743 | to create a client handle for each thread. |
| 744 | As a convenience, |
| 745 | the |
| 746 | .Nm asl_open |
| 747 | routine may be given an ident argument, |
| 748 | which becomes the default value for the ASL_KEY_SENDER key, |
| 749 | and a facility argument, |
| 750 | which becomes the value associated with the ASL_KEY_FACILITY key. |
| 751 | .Pp |
| 752 | Several options are available when creating a client handle. |
| 753 | They are: |
| 754 | .Pp |
| 755 | .Bl -tag -width "ASL_OPT_NO_REMOTE" -compact |
| 756 | .It ASL_OPT_STDERR |
| 757 | adds stderr as an output file descriptor |
| 758 | .It ASL_OPT_NO_DELAY |
| 759 | connects to the server immediately |
| 760 | .It ASL_OPT_NO_REMOTE |
| 761 | disables remote-control filter adjustment |
| 762 | .El |
| 763 | .Pp |
| 764 | ASL_OPT_NO_DELAY makes the client library connect to the |
| 765 | .Nm syslogd |
| 766 | server at the time that |
| 767 | .Nm asl_open |
| 768 | is called, rather than waiting for the first message to be sent. |
| 769 | Opening the connection is quite fast, but some applications may want to avoid any unnecessary delays when calling |
| 770 | .Nm asl_log , |
| 771 | .Nm asl_vlog , |
| 772 | or |
| 773 | .Nm asl_send . |
| 774 | .Pp |
| 775 | See the FILTERING section below, and the |
| 776 | .Xr syslog 1 |
| 777 | for additional details on filter controls. |
| 778 | .Pp |
| 779 | A client handle is closed and it's resources released using |
| 780 | .Nm asl_close . |
| 781 | Note that if additional file descriptors were added to the handle, |
| 782 | either using the ASL_OPT_STDERR option |
| 783 | or afterwards with the |
| 784 | .Nm asl_add_log_file |
| 785 | routine, those file descriptors are not closed by |
| 786 | .Nm asl_close . |
| 787 | .Ss LOGGING TO ADDITIONAL FILES |
| 788 | If a client handle is opened with the ASL_OPT_STDERR option to |
| 789 | .Nm asl_open , |
| 790 | a copy of each log message will be sent to stderr. |
| 791 | Additional output streams may be include using |
| 792 | .Nm asl_add_log_file . |
| 793 | .Pp |
| 794 | Messages sent to stderr or other files are printed in the "standard" message format |
| 795 | also used as a default format by the |
| 796 | .Xr syslog 1 |
| 797 | command line utility. |
| 798 | Non-ASCII characters in a message are encoded using the |
| 799 | .Dq safe |
| 800 | encoding style used by |
| 801 | .Xr syslog 1 |
| 802 | with the |
| 803 | .Fl E Ar safe |
| 804 | option. |
| 805 | Backspace characters are printed as ^H. |
| 806 | Carriage returns are mapped to newlines. |
| 807 | A tab character is appended after newlines so that message text is indented. |
| 808 | .Pp |
| 809 | File descriptors may be removed from the list of outputs associated |
| 810 | with a client handle with |
| 811 | .Nm asl_remove_log_file . |
| 812 | This routine simply removes the file descriptor from the output list. |
| 813 | The file is not closed as a result. |
| 814 | .Pp |
| 815 | The ASL_OPT_STDERR option may not be unset |
| 816 | after a client handle has been opened. |
| 817 | .Ss SEARCHING |
| 818 | The |
| 819 | .Nm syslogd |
| 820 | server archives received messages in a data store |
| 821 | that may be searched using the |
| 822 | .Nm asl_search , |
| 823 | .Nm aslresponse_next , |
| 824 | and |
| 825 | .Nm aslresponse_free |
| 826 | routines. |
| 827 | A query message is created using: |
| 828 | .Pp |
| 829 | aslmsg q = asl_new(ASL_TYPE_QUERY); |
| 830 | .Pp |
| 831 | Search settings are made in the query using |
| 832 | .Nm asl_set_query . |
| 833 | A search is performed on the data store with |
| 834 | .Nm asl_search . |
| 835 | It returns an |
| 836 | .Ft aslresponse |
| 837 | structure. |
| 838 | The caller may then call |
| 839 | .Nm aslresponse_next |
| 840 | to iterate through matching messages. |
| 841 | The |
| 842 | .Ft aslresponse |
| 843 | structure may be freed with |
| 844 | .Nm aslresponse_free . |
| 845 | .Pp |
| 846 | Like other messages, ASL_TYPE_QUERY messages contain keys and values. |
| 847 | They also associate an operation with each key and value. |
| 848 | The operation is used to decide if a message matches the query. |
| 849 | The simplest operation is ASL_QUERY_OP_EQUAL, which tests for equality. |
| 850 | For example, the following code snippet searches for messages |
| 851 | with a Sender value equal to |
| 852 | .Dq MyApp . |
| 853 | .Pp |
| 854 | aslmsg m; |
| 855 | aslresponse r; |
| 856 | q = asl_new(ASL_TYPE_QUERY); |
| 857 | asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL); |
| 858 | r = asl_search(NULL, q); |
| 859 | .Pp |
| 860 | More complex searches may be performed using other query operations. |
| 861 | .Pp |
| 862 | .Bl -tag -width "ASL_QUERY_OP_GREATER_EQUAL" -compact |
| 863 | .It ASL_QUERY_OP_EQUAL |
| 864 | value equality |
| 865 | .It ASL_QUERY_OP_GREATER |
| 866 | value greater than |
| 867 | .It ASL_QUERY_OP_GREATER_EQUAL |
| 868 | value greater than or equal to |
| 869 | .It ASL_QUERY_OP_LESS |
| 870 | value less than |
| 871 | .It ASL_QUERY_OP_LESS_EQUAL |
| 872 | value less than or equal to |
| 873 | .It ASL_QUERY_OP_NOT_EQUAL |
| 874 | value not equal |
| 875 | .It ASL_QUERY_OP_REGEX |
| 876 | regular expression search |
| 877 | .It ASL_QUERY_OP_TRUE |
| 878 | always true - use to test for the existence of a key |
| 879 | .El |
| 880 | .Pp |
| 881 | Regular expression search uses |
| 882 | .Xr regex 3 |
| 883 | library. |
| 884 | Patterns are compiled using the REG_EXTENDED and REG_NOSUB options. |
| 885 | .Pp |
| 886 | Modifiers that change the behavior of these operations |
| 887 | may also be specified by ORing the modifier value with the operation. |
| 888 | The modifiers are: |
| 889 | .Pp |
| 890 | .Bl -tag -width "ASL_QUERY_OP_SUBSTRING" -compact |
| 891 | .It ASL_QUERY_OP_CASEFOLD |
| 892 | string comparisons are case-folded |
| 893 | .It ASL_QUERY_OP_PREFIX |
| 894 | match a leading substring |
| 895 | .It ASL_QUERY_OP_SUFFIX |
| 896 | match a trailing substring |
| 897 | .It ASL_QUERY_OP_SUBSTRING |
| 898 | match any substring |
| 899 | .It ASL_QUERY_OP_NUMERIC |
| 900 | values are converted to integer using |
| 901 | .Nm atoi |
| 902 | .El |
| 903 | .Pp |
| 904 | The only modifier that is checked |
| 905 | for ASL_QUERY_OP_REGEX search is ASL_QUERY_OP_CASEFOLD. |
| 906 | This causes the regular expression to be compiled |
| 907 | with the REG_ICASE option. |
| 908 | .Pp |
| 909 | If a query message contains more than one set of key/value/operation triples, |
| 910 | the result will be a logical AND. For example, to find messages from |
| 911 | .Dq MyApp |
| 912 | with a priority level less than or equal to |
| 913 | .Dq 3 : |
| 914 | .Pp |
| 915 | aslmsg q; |
| 916 | aslresponse r; |
| 917 | q = asl_new(ASL_TYPE_QUERY); |
| 918 | asl_set_query(q, ASL_KEY_SENDER, "MyApp", ASL_QUERY_OP_EQUAL); |
| 919 | asl_set_query(q, ASL_KEY_LEVEL, "3", |
| 920 | ASL_QUERY_OP_LESS_EQUAL | ASL_QUERY_OP_NUMERIC); |
| 921 | r = asl_search(NULL, q); |
| 922 | .Pp |
| 923 | After calling |
| 924 | .Nm asl_search |
| 925 | to get an |
| 926 | .Ft aslresponse |
| 927 | structure, use |
| 928 | .Nm aslresponse_next |
| 929 | to iterate through all matching messages. |
| 930 | To iterate through the keys and values in a message, use |
| 931 | .Nm asl_key |
| 932 | to iterate through the keys, then call |
| 933 | .Nm asl_get |
| 934 | to get the value associated with each key. |
| 935 | .Pp |
| 936 | aslmsg q, m; |
| 937 | int i; |
| 938 | const char *key, *val; |
| 939 | .Pp |
| 940 | ... |
| 941 | r = asl_search(NULL, q); |
| 942 | while (NULL != (m = aslresponse_next(r))) |
| 943 | { |
| 944 | for (i = 0; (NULL != (key = asl_key(m, i))); i++) |
| 945 | { |
| 946 | val = asl_get(m, key); |
| 947 | ... |
| 948 | } |
| 949 | } |
| 950 | aslresponse_free(r); |
| 951 | .Pp |
| 952 | .Ss FILTERING AND REMOTE CONTROL |
| 953 | Clients may set a filter mask value with |
| 954 | .Nm asl_set_filter . |
| 955 | The mask specifies which messages should be sent to the |
| 956 | .Nm syslogd |
| 957 | daemon by specifying a yes/no setting for each priority level. |
| 958 | Clients typically set a filter mask |
| 959 | to avoid sending relatively unimportant messages. |
| 960 | For example, Debug or Info priority level messages |
| 961 | are generally only useful for debugging operations. |
| 962 | By setting a filter mask, a process can improve performance |
| 963 | by avoiding sending messages that are in most cases unnecessary. |
| 964 | .Pp |
| 965 | .Nm asl_set_filter returns the previous value of the filter, i.e. the value of the filter before the routine was called. |
| 966 | .Pp |
| 967 | As a convenience, the macros ASL_FILTER_MASK(level) and ASL_FILTER_MASK_UPTO(level) |
| 968 | may be used to construct a bit mask corresponding to a given priority level, |
| 969 | or corresponding to a bit mask for all priority levels |
| 970 | from ASL_LEVEL_EMERG to a given input level. |
| 971 | .Pp |
| 972 | The default filter mask is ASL_FILTER_MASK_UPTO(ASL_LEVEL_NOTICE). |
| 973 | This means that by default, |
| 974 | and in the absence of remote-control changes (described below), |
| 975 | ASL_LEVEL_DEBUG and ASL_LEVEL_INFO priority level messages |
| 976 | are not sent to the |
| 977 | .Mn syslogd |
| 978 | server. |
| 979 | .Pp |
| 980 | Three different filters exist for each application. |
| 981 | The first is the filter mask set using |
| 982 | .Nm asl_set_filter |
| 983 | as described above. |
| 984 | The Apple System Log facility also manages a |
| 985 | .Dq master |
| 986 | filter mask. |
| 987 | The master filter mask usually has a value |
| 988 | that indicates to the library that it is |
| 989 | .Dq off , |
| 990 | and thus it has no effect. |
| 991 | However, the mask filter mask may be enabled |
| 992 | by giving it a value using the |
| 993 | .Nm syslog |
| 994 | command, using the |
| 995 | .Fl c |
| 996 | 0 option. |
| 997 | When the master filter mask has been set, |
| 998 | it takes precedence over the client's filter mask. |
| 999 | The client's mask is unmodified, |
| 1000 | and will become active again if remote-control filtering is disabled. |
| 1001 | .Pp |
| 1002 | In addition to the master filter mask, |
| 1003 | The Apple System Log facility |
| 1004 | also manages a per-client remote-control filter mask. |
| 1005 | Like the master filter mask, the per-client mask is usually |
| 1006 | .Dq off , |
| 1007 | having no effect on a client. |
| 1008 | If a per-client filter mask is set using the |
| 1009 | .Nm syslog |
| 1010 | command, using the |
| 1011 | .Fl c Ar process |
| 1012 | option, then it takes precedence |
| 1013 | over both the client's filter mask and the master filter mask. |
| 1014 | As is the case with the master filter mask, |
| 1015 | a per-client mask ceases having any effect when if is disabled. |
| 1016 | .Pp |
| 1017 | The ASL_OPT_NO_REMOTE option to |
| 1018 | .Nm asl_open |
| 1019 | causes both the master and per-client remote-control masks |
| 1020 | to be ignored in the library. |
| 1021 | In that case, only the client's own filter mask |
| 1022 | is used to determine which messages are sent to the server. |
| 1023 | This may be useful for Applications that produce log messages |
| 1024 | that should never be filtered, due to security considerations. |
| 1025 | Note that root (administrator) access is required |
| 1026 | to set or change the master filter mask, |
| 1027 | and that only root may change a per-client remote-control filter mask |
| 1028 | for a root (UID 0) process. |
| 1029 | .Pp |
| 1030 | The per-process remote control filter value is kept as a state value |
| 1031 | associated with a key managed by |
| 1032 | .Nm notifyd . |
| 1033 | The key is protected by an access control mechanism that only permits the |
| 1034 | filter value to be accessed and modified by the same effective UID as the |
| 1035 | ASL client at the time that the first ASL connection was created. |
| 1036 | Remote filter control using |
| 1037 | .Nm syslog Fl c |
| 1038 | will fail for processes that change effective UID after starting an ASL connection. |
| 1039 | Those processes should close all ASL client handles and then re-open ASL connections |
| 1040 | if remote filter control support is desired. |
| 1041 | .Sh HISTORY |
| 1042 | These functions first appeared in |
| 1043 | Mac OS X 10.4. |
| 1044 | .Sh SEE ALSO |
| 1045 | .Xr syslog 1 , |
| 1046 | .Xr strvis 3 , |
| 1047 | .Xr syslogd 8 |