[832e33c] | 1 | @c |
---|
| 2 | @c COPYRIGHT (c) 1988-1998. |
---|
| 3 | @c On-Line Applications Research Corporation (OAR). |
---|
| 4 | @c All rights reserved. |
---|
| 5 | @c |
---|
| 6 | @c $Id$ |
---|
| 7 | @c |
---|
| 8 | |
---|
| 9 | @chapter Event Logging Manager |
---|
| 10 | |
---|
| 11 | @section Introduction |
---|
| 12 | |
---|
[d1a859c] | 13 | The event logging manager provides a portable method for logging |
---|
[a99ea16] | 14 | system and application events and subsequent processing of those |
---|
[d1a859c] | 15 | events. The capabilities in this manager were defined in the POSIX |
---|
| 16 | 1003.1h/D3 proposed standard titled @b{Services for Reliable, |
---|
| 17 | Available, and Serviceable Systems}. |
---|
[832e33c] | 18 | |
---|
| 19 | The directives provided by the event logging manager are: |
---|
| 20 | |
---|
| 21 | @itemize @bullet |
---|
[ebc67925] | 22 | @item @code{log_write} - Write to the Log |
---|
| 23 | @item @code{log_open} - Open a log file |
---|
| 24 | @item @code{log_read} - Read from the system Log |
---|
| 25 | @item @code{log_notify} - Notify Process of writes to the system log |
---|
| 26 | @item @code{log_close} - Close log descriptor |
---|
| 27 | @item @code{log_seek} - Reposition log file offset |
---|
| 28 | @item @code{log_severity_before} - Compare event record severities |
---|
| 29 | @item @code{log_facilityemptyset} - Manipulate log facility sets |
---|
| 30 | @item @code{log_facilityfillset} - Manipulate log facility sets |
---|
| 31 | @item @code{log_facilityaddset} - Manipulate log facility sets |
---|
| 32 | @item @code{log_facilitydelset} - Manipulate log facility sets |
---|
| 33 | @item @code{log_facilityismember} - Manipulate log facility sets |
---|
[832e33c] | 34 | @end itemize |
---|
| 35 | |
---|
| 36 | @section Background |
---|
| 37 | |
---|
[d1a859c] | 38 | @subsection Log Files and Events |
---|
| 39 | |
---|
| 40 | System log |
---|
| 41 | |
---|
| 42 | Non-system logs |
---|
| 43 | |
---|
| 44 | Events, facility, severity |
---|
| 45 | |
---|
| 46 | @subsection Queries |
---|
| 47 | |
---|
[832e33c] | 48 | @section Operations |
---|
| 49 | |
---|
[d1a859c] | 50 | @subsection Creating and Writing a non-System Log |
---|
| 51 | |
---|
| 52 | Discuss creating and writing to a non-system log. |
---|
| 53 | |
---|
| 54 | @example |
---|
| 55 | log_create |
---|
| 56 | log_write loop |
---|
| 57 | @end example |
---|
| 58 | |
---|
| 59 | @subsection Reading a Log |
---|
| 60 | |
---|
| 61 | Discuss opening and reading from a log. |
---|
| 62 | |
---|
| 63 | @example |
---|
| 64 | build a query |
---|
| 65 | log_open |
---|
| 66 | log_read loop |
---|
| 67 | @end example |
---|
| 68 | |
---|
[832e33c] | 69 | @section Directives |
---|
| 70 | |
---|
| 71 | This section details the event logging manager's directives. |
---|
| 72 | A subsection is dedicated to each of this manager's directives |
---|
| 73 | and describes the calling sequence, related constants, usage, |
---|
| 74 | and status codes. |
---|
| 75 | |
---|
| 76 | @page |
---|
[ebc67925] | 77 | @subsection log_write - Write to the Log |
---|
[832e33c] | 78 | |
---|
| 79 | @subheading CALLING SEQUENCE: |
---|
| 80 | |
---|
| 81 | @ifset is-C |
---|
| 82 | @example |
---|
[30cc2e0] | 83 | #include <evlog.h> |
---|
| 84 | |
---|
[832e33c] | 85 | int log_write( |
---|
[ebc67925] | 86 | const log_facility_t facility, |
---|
| 87 | const int event_id, |
---|
| 88 | const log_severity_t severity, |
---|
| 89 | const void *buf, |
---|
| 90 | const size_t len |
---|
[832e33c] | 91 | ); |
---|
| 92 | @end example |
---|
| 93 | @end ifset |
---|
| 94 | |
---|
| 95 | @ifset is-Ada |
---|
| 96 | @end ifset |
---|
| 97 | |
---|
| 98 | @subheading STATUS CODES: |
---|
| 99 | |
---|
[16bed8a] | 100 | @table @b |
---|
[ebc67925] | 101 | @item EINVAL |
---|
| 102 | The facility argument is not a valid log_facility. |
---|
[d1a859c] | 103 | |
---|
[ebc67925] | 104 | @item EINVAL |
---|
[d5ef5bd1] | 105 | The severity argument exceeds @code{LOG_SEVERITY_MAX} |
---|
[d1a859c] | 106 | |
---|
[ebc67925] | 107 | @item EINVAL |
---|
[d5ef5bd1] | 108 | The len argument exceeds @code{LOG_ENTRY_MAXLEN} |
---|
[d1a859c] | 109 | |
---|
[ebc67925] | 110 | @item ENOSPC |
---|
| 111 | The log file has run out of space on the device. |
---|
[d1a859c] | 112 | |
---|
[ebc67925] | 113 | @item EPERM |
---|
| 114 | The caller does not have appropriate permission for writing to |
---|
| 115 | the given facility. |
---|
[d1a859c] | 116 | |
---|
[ebc67925] | 117 | @item EIO |
---|
| 118 | An I/O error occurred in writing to the system event log. |
---|
[16bed8a] | 119 | |
---|
| 120 | @end table |
---|
| 121 | |
---|
[832e33c] | 122 | @subheading DESCRIPTION: |
---|
| 123 | |
---|
[d1a859c] | 124 | The @code{log_write} function writes an event record, consisting |
---|
| 125 | of event attributes, and the data identified by the @code{buf} |
---|
| 126 | argument, to the system log. The @code{len} argument specifies |
---|
| 127 | the length in bytes of the buffer pointed to by @code{buf}. The |
---|
| 128 | @code{len} argument shall specify the value of the event record |
---|
| 129 | length attribute. The value of @code{len} shall be less than or |
---|
| 130 | equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail. |
---|
| 131 | |
---|
| 132 | The @code{event_id} argument identifies the type of event record |
---|
| 133 | being written. The @code{event_id} argument shall specify the value |
---|
| 134 | of the event ID attribute of the event record. |
---|
| 135 | |
---|
| 136 | The argument @code{facility} indicates the facility from which the |
---|
[a99ea16] | 137 | event type is drawn. The @code{facility} argument shall specify the |
---|
[d1a859c] | 138 | value of the event record facility attribute. The value of the |
---|
| 139 | @code{facility} argument shall be a valid log facility or the |
---|
| 140 | @code{log_write} function shall fail. |
---|
| 141 | |
---|
| 142 | The @code{severity} argument indicates the severity level of the |
---|
| 143 | event record. The @code{severity} argument shall specify the value |
---|
| 144 | of the event record severity attribute. The value of the |
---|
| 145 | @code{severity} argument shall be less than or equal to |
---|
| 146 | @code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. |
---|
| 147 | |
---|
| 148 | The effective_UID of the calling process shall specify the event |
---|
[a99ea16] | 149 | record UID attribute. The effective-GID of the calling process |
---|
[d1a859c] | 150 | shall specify the event record GID attribute. The process ID |
---|
| 151 | of the calling process shall specify the event record process ID |
---|
| 152 | attribute. The process group ID of the calling process shall |
---|
| 153 | specify the event record process group ID attribute. The current |
---|
| 154 | value of the system clock shall specify the event record timestamp |
---|
| 155 | attribute. |
---|
[ebc67925] | 156 | |
---|
[832e33c] | 157 | @subheading NOTES: |
---|
| 158 | |
---|
[d1a859c] | 159 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 160 | this service is available. |
---|
| 161 | |
---|
[832e33c] | 162 | @page |
---|
[ebc67925] | 163 | @subsection log_open - Open a log file |
---|
[832e33c] | 164 | |
---|
| 165 | @subheading CALLING SEQUENCE: |
---|
| 166 | |
---|
| 167 | @ifset is-C |
---|
| 168 | @example |
---|
[30cc2e0] | 169 | #include <evlog.h> |
---|
| 170 | |
---|
[832e33c] | 171 | int log_open( |
---|
[6520befe] | 172 | logd_t *logdes, |
---|
[ebc67925] | 173 | const char *path, |
---|
| 174 | const log_query_t *query |
---|
[832e33c] | 175 | ); |
---|
| 176 | @end example |
---|
| 177 | @end ifset |
---|
| 178 | |
---|
| 179 | @ifset is-Ada |
---|
| 180 | @end ifset |
---|
| 181 | |
---|
| 182 | @subheading STATUS CODES: |
---|
| 183 | |
---|
[16bed8a] | 184 | @table @b |
---|
[ebc67925] | 185 | @item EACCES |
---|
| 186 | Search permission is denied on a component of the path prefix, |
---|
| 187 | or the log file exists and read permission is denied. |
---|
[d1a859c] | 188 | |
---|
[ebc67925] | 189 | @item EINTR |
---|
| 190 | A signal interrupted the call to log_open(). |
---|
[d1a859c] | 191 | |
---|
[ebc67925] | 192 | @item EINVAL |
---|
| 193 | The log_severity field of the query argument exceeds |
---|
[d5ef5bd1] | 194 | @code{LOG_SEVERITY_MAX}. |
---|
[d1a859c] | 195 | |
---|
[ebc67925] | 196 | @item EINVAL |
---|
| 197 | The path argument referred to a file that was not a log file. |
---|
[d1a859c] | 198 | |
---|
[ebc67925] | 199 | @item EMFILE |
---|
| 200 | Too many log file descriptors are currently in use by this |
---|
| 201 | process. |
---|
[d1a859c] | 202 | |
---|
[ebc67925] | 203 | @item ENAMETOOLONG |
---|
[d5ef5bd1] | 204 | The length of the path string exceeds @code{PATH_MAX}, or a pathname |
---|
| 205 | component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is |
---|
[ebc67925] | 206 | in effect. |
---|
[d1a859c] | 207 | |
---|
[ebc67925] | 208 | @item ENFILE |
---|
| 209 | Too many files are currently open in the system. |
---|
[d1a859c] | 210 | |
---|
[ebc67925] | 211 | @item ENOENT |
---|
| 212 | The file specified by the path argument does not exist. |
---|
[d1a859c] | 213 | |
---|
[ebc67925] | 214 | @item ENOTDIR |
---|
| 215 | A component of the path prefix is not a directory. |
---|
[16bed8a] | 216 | |
---|
| 217 | @end table |
---|
| 218 | |
---|
[832e33c] | 219 | @subheading DESCRIPTION: |
---|
| 220 | |
---|
[d1a859c] | 221 | The @code{log_open} function establishes the connection between a |
---|
| 222 | log file and a log file descriptor. It creates an open log file |
---|
[6520befe] | 223 | descriptor that refers to this query stream on the specified log file |
---|
| 224 | The log file descriptor is used by the other log functions to refer |
---|
| 225 | to that log query stream. The @code{path} argument points to a |
---|
| 226 | pathname for a log file. A @code{path} argument of NULL specifies |
---|
| 227 | the current system log file. |
---|
| 228 | |
---|
| 229 | The @code{query} argument is not NULL, then it points to a log query |
---|
| 230 | specification that is used to filter the records in the log file on |
---|
| 231 | subsequent @code{log_read} operations. This restricts the set of |
---|
| 232 | event records read using the returned log file descriptor to those |
---|
| 233 | which match the query. A query match occurs for a given record when |
---|
| 234 | that record's facility is a member of the query's facility set and |
---|
| 235 | the record's severity is greater than or equal to the severity specified |
---|
| 236 | in the query. |
---|
| 237 | |
---|
| 238 | If the value of the @code{query} argument is NULL, no query filter |
---|
| 239 | shall be applied. |
---|
[ebc67925] | 240 | |
---|
[832e33c] | 241 | @subheading NOTES: |
---|
| 242 | |
---|
[d1a859c] | 243 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 244 | this service is available. |
---|
| 245 | |
---|
[6520befe] | 246 | POSIX specifies that @code{EINVAL} will be returned if the |
---|
| 247 | @code{log_facilities} field of the @code{query} argument is not |
---|
| 248 | a valid facility set. In this implementation, this condition |
---|
| 249 | can never occur. |
---|
| 250 | |
---|
| 251 | Many error codes that POSIX specifies to be returned by @code{log_open} |
---|
| 252 | should actually be detected by @code{open} and passed back by the |
---|
| 253 | @code{log_open} implementation. In this implementation, @code{EACCESS}, |
---|
| 254 | @code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT}, |
---|
| 255 | and @code{ENOTDIR} are detected in this manner. |
---|
| 256 | |
---|
[832e33c] | 257 | @page |
---|
[ebc67925] | 258 | @subsection log_read - Read from the system Log |
---|
[832e33c] | 259 | |
---|
| 260 | @subheading CALLING SEQUENCE: |
---|
| 261 | |
---|
| 262 | @ifset is-C |
---|
| 263 | @example |
---|
[30cc2e0] | 264 | #include <evlog.h> |
---|
| 265 | |
---|
[832e33c] | 266 | int log_read( |
---|
[af5a571] | 267 | const logd_t logdes, |
---|
[ebc67925] | 268 | struct log_entry *entry, |
---|
| 269 | void *log_buf, |
---|
| 270 | const size_t log_len, |
---|
| 271 | const size_t *log_sizeread |
---|
[832e33c] | 272 | ); |
---|
| 273 | @end example |
---|
| 274 | @end ifset |
---|
| 275 | |
---|
| 276 | @ifset is-Ada |
---|
| 277 | @end ifset |
---|
| 278 | |
---|
| 279 | @subheading STATUS CODES: |
---|
| 280 | |
---|
[16bed8a] | 281 | @table @b |
---|
[ebc67925] | 282 | @item EBADF |
---|
| 283 | The logdes argument is not a valid log file descriptor. |
---|
[d1a859c] | 284 | |
---|
[ebc67925] | 285 | @item EBUSY |
---|
| 286 | No data available. The open log file descriptor references |
---|
| 287 | the current system log. and there are no unread event records |
---|
| 288 | remaining. |
---|
[d1a859c] | 289 | |
---|
[ebc67925] | 290 | @item EINTR |
---|
| 291 | A signal interrupted the call to log_read(). |
---|
[d1a859c] | 292 | |
---|
[ebc67925] | 293 | @item EIO |
---|
| 294 | An I/O error occurred in reading from the event log. |
---|
[16bed8a] | 295 | |
---|
| 296 | @end table |
---|
| 297 | |
---|
[832e33c] | 298 | @subheading DESCRIPTION: |
---|
| 299 | |
---|
[d1a859c] | 300 | The @code{log_read} function shall attempt to read the @code{log_entry} |
---|
| 301 | structure and @code{log_len} bytes of data from the next event record |
---|
| 302 | of the log file associated with the open log file descriptor @code{logdes}, |
---|
| 303 | placing the @code{log_entry} structure into the buffer pointed to by |
---|
| 304 | @code{entry}, and the data into the buffer pointed to by @code{log_buf}. |
---|
| 305 | The log record ID of the returned event record shall be stored in the |
---|
[a99ea16] | 306 | @code{log_recid} member of the @code{log_entry} structure for the event |
---|
[d1a859c] | 307 | record. |
---|
| 308 | |
---|
| 309 | If the query attribute of the open log file description associated with |
---|
| 310 | the @code{logdes} is set, the event record read shall match that query. |
---|
| 311 | If the @code{entry} argument is not NULL it will point to a @code{log_entry} |
---|
[a99ea16] | 312 | structure which shall be filled with the creation information for this log |
---|
[d1a859c] | 313 | entry. If the argument @code{log_buf} is not NULL the data written with the |
---|
| 314 | log entry will be placed in the buffer. The size of the buffer is specified |
---|
| 315 | by the argument @code{log_len}. |
---|
| 316 | |
---|
| 317 | If the @code{log_read} is successful the call shall store the actual length |
---|
| 318 | of the data associated with the event record into the location specified by |
---|
| 319 | @code{log_sizeread}. This number may be smaller or greater than |
---|
| 320 | @code{log_len}. |
---|
[ebc67925] | 321 | |
---|
[832e33c] | 322 | @subheading NOTES: |
---|
| 323 | |
---|
[d1a859c] | 324 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 325 | this service is available. |
---|
| 326 | |
---|
[832e33c] | 327 | @page |
---|
[ebc67925] | 328 | @subsection log_notify - Notify Process of writes to the system log. |
---|
[832e33c] | 329 | |
---|
| 330 | @subheading CALLING SEQUENCE: |
---|
| 331 | |
---|
| 332 | @ifset is-C |
---|
| 333 | @example |
---|
[30cc2e0] | 334 | #include <evlog.h> |
---|
| 335 | |
---|
[832e33c] | 336 | int log_notify( |
---|
[ebc67925] | 337 | const logd_t logdes, |
---|
| 338 | const struct sigevent *notification |
---|
[832e33c] | 339 | ); |
---|
| 340 | @end example |
---|
| 341 | @end ifset |
---|
| 342 | |
---|
| 343 | @ifset is-Ada |
---|
| 344 | @end ifset |
---|
| 345 | |
---|
| 346 | @subheading STATUS CODES: |
---|
| 347 | |
---|
[16bed8a] | 348 | @table @b |
---|
[ebc67925] | 349 | @item EBADF |
---|
[a99ea16] | 350 | The logdes argument is not a valid log file descriptor. |
---|
[d1a859c] | 351 | |
---|
[ebc67925] | 352 | @item EINVAL |
---|
| 353 | The notification argument specifies an invalid signal. |
---|
[d1a859c] | 354 | |
---|
[ebc67925] | 355 | @item EINVAL |
---|
| 356 | The process has requested a notify on a log that will not be |
---|
| 357 | written to. |
---|
[d1a859c] | 358 | |
---|
[30cc2e0] | 359 | @item ENOSYS |
---|
[ebc67925] | 360 | The function log_notify() is not supported by this implementation. |
---|
[16bed8a] | 361 | |
---|
| 362 | @end table |
---|
| 363 | |
---|
[832e33c] | 364 | @subheading DESCRIPTION: |
---|
| 365 | |
---|
[d1a859c] | 366 | If the argument @code{notification} is not NULL this function registers |
---|
| 367 | the calling process to be notified of event records received by the system |
---|
| 368 | log, which match the query parameters associated with the open log descriptor |
---|
| 369 | specified by @code{logdes}. The notification specified by the |
---|
| 370 | @code{notification} argument shall be sent to the process when an event |
---|
| 371 | record received by the system log is matched by the query attribute of the |
---|
| 372 | open log file description associated with the @code{logdes} log file |
---|
| 373 | descriptor. If the calling process has already registered a notification |
---|
| 374 | for the @code{logdes} log file descriptor, the new notification shall |
---|
| 375 | replace the existing notification registration. |
---|
| 376 | |
---|
| 377 | If the @code{notification} argument is NULL and the calling process is |
---|
| 378 | currently registered to be notified for the @code{logdes} log file |
---|
| 379 | descriptor, the existing registration shall be removed. |
---|
[09470e0] | 380 | |
---|
[832e33c] | 381 | @subheading NOTES: |
---|
| 382 | |
---|
[d1a859c] | 383 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 384 | this service is available. |
---|
| 385 | |
---|
[832e33c] | 386 | @page |
---|
[ebc67925] | 387 | @subsection log_close - Close log descriptor |
---|
[832e33c] | 388 | |
---|
| 389 | @subheading CALLING SEQUENCE: |
---|
| 390 | |
---|
| 391 | @ifset is-C |
---|
| 392 | @example |
---|
[30cc2e0] | 393 | #include <evlog.h> |
---|
| 394 | |
---|
[832e33c] | 395 | int log_close( |
---|
[ebc67925] | 396 | const logd_t logdes |
---|
[832e33c] | 397 | ); |
---|
| 398 | @end example |
---|
| 399 | @end ifset |
---|
| 400 | |
---|
| 401 | @ifset is-Ada |
---|
| 402 | @end ifset |
---|
| 403 | |
---|
| 404 | @subheading STATUS CODES: |
---|
| 405 | |
---|
[16bed8a] | 406 | @table @b |
---|
[ebc67925] | 407 | @item EBADF |
---|
| 408 | The logdes argument is not a valid log file descriptor. |
---|
[16bed8a] | 409 | |
---|
| 410 | @end table |
---|
| 411 | |
---|
[832e33c] | 412 | @subheading DESCRIPTION: |
---|
| 413 | |
---|
[d1a859c] | 414 | The @code{log_close} function deallocates the open log file descriptor |
---|
| 415 | indicated by @code{log_des}. |
---|
[2dd561a3] | 416 | |
---|
[d1a859c] | 417 | When all log file descriptors associated with an open log file description |
---|
| 418 | have been closed, the open log file description shall be freed. |
---|
[2dd561a3] | 419 | |
---|
[d1a859c] | 420 | If the link count of the log file is zero, when all log file descriptors |
---|
| 421 | have been closed, the space occupied by the log file shall be freed and the |
---|
| 422 | log file shall no longer be accessible. |
---|
[2dd561a3] | 423 | |
---|
[d1a859c] | 424 | If the process has successfully registered a notification request for the |
---|
| 425 | log file descriptor, the registration shall be removed. |
---|
[ebc67925] | 426 | |
---|
[832e33c] | 427 | @subheading NOTES: |
---|
| 428 | |
---|
[d1a859c] | 429 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 430 | this service is available. |
---|
| 431 | |
---|
[832e33c] | 432 | @page |
---|
[ebc67925] | 433 | @subsection log_seek - Reposition log file offset |
---|
[832e33c] | 434 | |
---|
| 435 | @subheading CALLING SEQUENCE: |
---|
| 436 | |
---|
| 437 | @ifset is-C |
---|
| 438 | @example |
---|
[30cc2e0] | 439 | #include <evlog.h> |
---|
| 440 | |
---|
[832e33c] | 441 | int log_seek( |
---|
[ebc67925] | 442 | const logd_t logdes, |
---|
| 443 | log_recid_t log_recid |
---|
[832e33c] | 444 | ); |
---|
| 445 | @end example |
---|
| 446 | @end ifset |
---|
| 447 | |
---|
| 448 | @ifset is-Ada |
---|
| 449 | @end ifset |
---|
| 450 | |
---|
| 451 | @subheading STATUS CODES: |
---|
| 452 | |
---|
[16bed8a] | 453 | @table @b |
---|
[ebc67925] | 454 | @item EBADF |
---|
[af5a571] | 455 | The @code{logdes} argument is not a valid log file descriptor. |
---|
[16bed8a] | 456 | |
---|
| 457 | @end table |
---|
| 458 | |
---|
[832e33c] | 459 | @subheading DESCRIPTION: |
---|
| 460 | |
---|
[af5a571] | 461 | The @code{log_seek} function sets the log file offset of the open |
---|
[a99ea16] | 462 | log description associated with the @code{logdes} log file descriptor |
---|
[d1a859c] | 463 | to the event record in the log file identified by @code{log_recid}. |
---|
| 464 | The @code{log_recid} argument is either the record id of a valid event |
---|
| 465 | record or one of the following values, as defined in the header <evlog.h>: |
---|
| 466 | |
---|
| 467 | @table @b |
---|
| 468 | @item LOG_SEEK_START |
---|
| 469 | Set log file position to point at the first event |
---|
[af5a571] | 470 | record in the log file. |
---|
[2dd561a3] | 471 | |
---|
[d1a859c] | 472 | @item LOG_SEEK_END |
---|
| 473 | Set log file position to point after the last event |
---|
[af5a571] | 474 | record in the log file. |
---|
[2dd561a3] | 475 | |
---|
[d1a859c] | 476 | @end table |
---|
[2dd561a3] | 477 | |
---|
[832e33c] | 478 | @subheading NOTES: |
---|
| 479 | |
---|
[d1a859c] | 480 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 481 | this service is available. |
---|
| 482 | |
---|
[af5a571] | 483 | This implementation can not return @code{EINTR}. |
---|
| 484 | |
---|
| 485 | This implementation can not return @code{EINVAL} to indicate that |
---|
| 486 | the @code{log_recid} argument is not a valid record id. |
---|
| 487 | |
---|
[832e33c] | 488 | @page |
---|
[ebc67925] | 489 | @subsection log_severity_before - Compare event record severities |
---|
[832e33c] | 490 | |
---|
| 491 | @subheading CALLING SEQUENCE: |
---|
| 492 | |
---|
| 493 | @ifset is-C |
---|
| 494 | @example |
---|
[30cc2e0] | 495 | #include <evlog.h> |
---|
| 496 | |
---|
[832e33c] | 497 | int log_severity_before( |
---|
[ebc67925] | 498 | log_severity_t s1, |
---|
| 499 | log_severity_t s2 |
---|
[832e33c] | 500 | ); |
---|
| 501 | @end example |
---|
| 502 | @end ifset |
---|
| 503 | |
---|
| 504 | @ifset is-Ada |
---|
| 505 | @end ifset |
---|
| 506 | |
---|
| 507 | @subheading STATUS CODES: |
---|
| 508 | |
---|
[16bed8a] | 509 | @table @b |
---|
[c5568160] | 510 | @item 0 |
---|
| 511 | The severity of @code{s1} is less than that of @code{s2}. |
---|
| 512 | |
---|
| 513 | @item 1 |
---|
| 514 | The severity of @code{s1} is greater than or equal that of @code{s2}. |
---|
| 515 | |
---|
[ebc67925] | 516 | @item EINVAL |
---|
[d5ef5bd1] | 517 | The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}. |
---|
[16bed8a] | 518 | |
---|
| 519 | @end table |
---|
| 520 | |
---|
[832e33c] | 521 | @subheading DESCRIPTION: |
---|
| 522 | |
---|
[c5568160] | 523 | The @code{log_severity_before} function compares the severity order |
---|
| 524 | of the @code{s1} and @code{s2} arguments. If @code{s1} is of |
---|
| 525 | severity greater than or equal to that of @code{s2}, then this |
---|
| 526 | function returns 1. Otherwise, it returns 0. |
---|
[2dd561a3] | 527 | |
---|
[c5568160] | 528 | If either @code{s1} or @code{s2} specify invalid severity values, the |
---|
| 529 | return value of @code{log_severity_before} is unspecified. |
---|
[ebc67925] | 530 | |
---|
[832e33c] | 531 | @subheading NOTES: |
---|
| 532 | |
---|
[d1a859c] | 533 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 534 | this service is available. |
---|
| 535 | |
---|
[c5568160] | 536 | The POSIX specification of the return value for this function is ambiguous. |
---|
| 537 | If @code{EINVAL} is equal to 1 in an implementation, then the application |
---|
| 538 | can not distinguish between greater than and an error condition. |
---|
| 539 | |
---|
[832e33c] | 540 | @page |
---|
[ebc67925] | 541 | @subsection log_facilityemptyset - Manipulate log facility sets |
---|
[832e33c] | 542 | |
---|
| 543 | @subheading CALLING SEQUENCE: |
---|
| 544 | |
---|
| 545 | @ifset is-C |
---|
| 546 | @example |
---|
[30cc2e0] | 547 | #include <evlog.h> |
---|
| 548 | |
---|
[832e33c] | 549 | int log_facilityemptyset( |
---|
[ebc67925] | 550 | log_facility_set_t *set |
---|
[832e33c] | 551 | ); |
---|
| 552 | @end example |
---|
| 553 | @end ifset |
---|
| 554 | |
---|
| 555 | @ifset is-Ada |
---|
| 556 | @end ifset |
---|
| 557 | |
---|
| 558 | @subheading STATUS CODES: |
---|
| 559 | |
---|
[16bed8a] | 560 | @table @b |
---|
[d65d22a0] | 561 | @item EFAULT |
---|
| 562 | The @code{set} argument is an invalid pointer. |
---|
[16bed8a] | 563 | |
---|
| 564 | @end table |
---|
| 565 | |
---|
[832e33c] | 566 | @subheading DESCRIPTION: |
---|
| 567 | |
---|
[d1a859c] | 568 | The @code{log_facilityemptyset} function initializes the facility |
---|
[a99ea16] | 569 | set pointed to by the argument @code{set}, such that all facilities |
---|
[d65d22a0] | 570 | are excluded. |
---|
| 571 | |
---|
| 572 | @subheading NOTES: |
---|
| 573 | |
---|
| 574 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 575 | this service is available. |
---|
[d1a859c] | 576 | |
---|
| 577 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 578 | @code{log_facilityfillset} at least once for each object of type |
---|
| 579 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 580 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 581 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 582 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 583 | @code{log_open} functions, the results are undefined. |
---|
| 584 | |
---|
[832e33c] | 585 | @page |
---|
[ebc67925] | 586 | @subsection log_facilityfillset - Manipulate log facility sets |
---|
[832e33c] | 587 | |
---|
| 588 | @subheading CALLING SEQUENCE: |
---|
| 589 | |
---|
| 590 | @ifset is-C |
---|
| 591 | @example |
---|
[30cc2e0] | 592 | #include <evlog.h> |
---|
| 593 | |
---|
[832e33c] | 594 | int log_facilityfillset( |
---|
[ebc67925] | 595 | log_facility_set_t *set |
---|
[832e33c] | 596 | ); |
---|
| 597 | @end example |
---|
| 598 | @end ifset |
---|
| 599 | |
---|
| 600 | @ifset is-Ada |
---|
| 601 | @end ifset |
---|
| 602 | |
---|
| 603 | @subheading STATUS CODES: |
---|
| 604 | |
---|
[16bed8a] | 605 | @table @b |
---|
[d65d22a0] | 606 | @item EFAULT |
---|
| 607 | The @code{set} argument is an invalid pointer. |
---|
[16bed8a] | 608 | |
---|
| 609 | @end table |
---|
| 610 | |
---|
[832e33c] | 611 | @subheading DESCRIPTION: |
---|
| 612 | |
---|
[d65d22a0] | 613 | The @code{log_facilityfillset} function initializes the facility |
---|
[a99ea16] | 614 | set pointed to by the argument @code{set}, such that all facilities |
---|
[d1a859c] | 615 | are included. |
---|
| 616 | |
---|
[d65d22a0] | 617 | @subheading NOTES: |
---|
| 618 | |
---|
| 619 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 620 | this service is available. |
---|
| 621 | |
---|
[d1a859c] | 622 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 623 | @code{log_facilityfillset} at least once for each object of type |
---|
| 624 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 625 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 626 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 627 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 628 | @code{log_open} functions, the results are undefined. |
---|
| 629 | |
---|
[832e33c] | 630 | @page |
---|
[ebc67925] | 631 | @subsection log_facilityaddset - Manipulate log facility sets |
---|
[832e33c] | 632 | |
---|
| 633 | @subheading CALLING SEQUENCE: |
---|
| 634 | |
---|
| 635 | @ifset is-C |
---|
| 636 | @example |
---|
[30cc2e0] | 637 | #include <evlog.h> |
---|
| 638 | |
---|
[832e33c] | 639 | int log_facilityaddset( |
---|
[ebc67925] | 640 | log_facility_set_t *set, |
---|
[d65d22a0] | 641 | log_facility_t facilityno |
---|
[832e33c] | 642 | ); |
---|
| 643 | @end example |
---|
| 644 | @end ifset |
---|
| 645 | |
---|
| 646 | @ifset is-Ada |
---|
| 647 | @end ifset |
---|
| 648 | |
---|
| 649 | @subheading STATUS CODES: |
---|
| 650 | |
---|
[16bed8a] | 651 | @table @b |
---|
[d65d22a0] | 652 | @item EFAULT |
---|
| 653 | The @code{set} argument is an invalid pointer. |
---|
| 654 | |
---|
[ebc67925] | 655 | @item EINVAL |
---|
[d65d22a0] | 656 | The @code{facilityno} argument is not a valid facility. |
---|
[16bed8a] | 657 | |
---|
| 658 | @end table |
---|
| 659 | |
---|
[832e33c] | 660 | @subheading DESCRIPTION: |
---|
| 661 | |
---|
[d65d22a0] | 662 | The @code{log_facilityaddset} function adds the individual |
---|
| 663 | facility specified by the value of the argument @code{facilityno} |
---|
| 664 | to the facility set pointed to by the argument @code{set}. |
---|
[d1a859c] | 665 | |
---|
[d65d22a0] | 666 | @subheading NOTES: |
---|
| 667 | |
---|
| 668 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 669 | this service is available. |
---|
[d1a859c] | 670 | |
---|
| 671 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 672 | @code{log_facilityfillset} at least once for each object of type |
---|
| 673 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 674 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 675 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 676 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 677 | @code{log_open} functions, the results are undefined. |
---|
| 678 | |
---|
[832e33c] | 679 | @page |
---|
[ebc67925] | 680 | @subsection log_facilitydelset - Manipulate log facility sets |
---|
[832e33c] | 681 | |
---|
| 682 | @subheading CALLING SEQUENCE: |
---|
| 683 | |
---|
| 684 | @ifset is-C |
---|
| 685 | @example |
---|
[30cc2e0] | 686 | #include <evlog.h> |
---|
| 687 | |
---|
[832e33c] | 688 | int log_facilitydelset( |
---|
[ebc67925] | 689 | log_facility_set_t *set, |
---|
[d65d22a0] | 690 | log_facility_t facilityno |
---|
[832e33c] | 691 | ); |
---|
| 692 | @end example |
---|
| 693 | @end ifset |
---|
| 694 | |
---|
| 695 | @ifset is-Ada |
---|
| 696 | @end ifset |
---|
| 697 | |
---|
| 698 | @subheading STATUS CODES: |
---|
| 699 | |
---|
[16bed8a] | 700 | @table @b |
---|
[d65d22a0] | 701 | @item EFAULT |
---|
| 702 | The @code{set} argument is an invalid pointer. |
---|
| 703 | |
---|
[ebc67925] | 704 | @item EINVAL |
---|
[d65d22a0] | 705 | The @code{facilityno} argument is not a valid facility. |
---|
[16bed8a] | 706 | |
---|
| 707 | @end table |
---|
| 708 | |
---|
[832e33c] | 709 | @subheading DESCRIPTION: |
---|
| 710 | |
---|
[d65d22a0] | 711 | The @code{log_facilitydelset} function deletes the individual |
---|
| 712 | facility specified by the value of the argument @code{facilityno} |
---|
| 713 | from the facility set pointed to by the argument @code{set}. |
---|
[d1a859c] | 714 | |
---|
[d65d22a0] | 715 | @subheading NOTES: |
---|
| 716 | |
---|
| 717 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 718 | this service is available. |
---|
[d1a859c] | 719 | |
---|
| 720 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 721 | @code{log_facilityfillset} at least once for each object of type |
---|
| 722 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 723 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 724 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 725 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 726 | @code{log_open} functions, the results are undefined. |
---|
| 727 | |
---|
[832e33c] | 728 | @page |
---|
[ebc67925] | 729 | @subsection log_facilityismember - Manipulate log facility sets |
---|
[832e33c] | 730 | |
---|
| 731 | @subheading CALLING SEQUENCE: |
---|
| 732 | |
---|
| 733 | @ifset is-C |
---|
| 734 | @example |
---|
[30cc2e0] | 735 | #include <evlog.h> |
---|
| 736 | |
---|
[832e33c] | 737 | int log_facilityismember( |
---|
[ebc67925] | 738 | const log_facility_set_t *set, |
---|
| 739 | log_facility_t facilityno, |
---|
| 740 | const int *member |
---|
[832e33c] | 741 | ); |
---|
| 742 | @end example |
---|
| 743 | @end ifset |
---|
| 744 | |
---|
| 745 | @ifset is-Ada |
---|
| 746 | @end ifset |
---|
| 747 | |
---|
| 748 | @subheading STATUS CODES: |
---|
| 749 | |
---|
[16bed8a] | 750 | @table @b |
---|
[d65d22a0] | 751 | @item EFAULT |
---|
| 752 | The @code{set} or @code{member} argument is an invalid pointer. |
---|
| 753 | |
---|
[ebc67925] | 754 | @item EINVAL |
---|
[d65d22a0] | 755 | The @code{facilityno} argument is not a valid facility. |
---|
[16bed8a] | 756 | |
---|
| 757 | @end table |
---|
| 758 | |
---|
[832e33c] | 759 | @subheading DESCRIPTION: |
---|
| 760 | |
---|
[d1a859c] | 761 | The @code{log_facilityismember} function tests whether the facility |
---|
| 762 | specified by the value of the argument @code{facilityno} is a member |
---|
| 763 | of the set pointed to by the argument @code{set}. Upon successful |
---|
| 764 | completion, the @code{log_facilityismember} function either returns |
---|
| 765 | a value of one to the location specified by @code{member} if the |
---|
[d65d22a0] | 766 | specified facility is a member of the specified set or value of |
---|
| 767 | zero to the location specified by @code{member} if the specified |
---|
| 768 | facility is not a member of the specified set. |
---|
[2dd561a3] | 769 | |
---|
[832e33c] | 770 | @subheading NOTES: |
---|
| 771 | |
---|
[d1a859c] | 772 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 773 | this service is available. |
---|
| 774 | |
---|
[d65d22a0] | 775 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 776 | @code{log_facilityfillset} at least once for each object of type |
---|
| 777 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 778 | such an object is not initialized in this way, but is nonetheless |
---|
| 779 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
| 780 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 781 | @code{log_open} functions, the results are undefined. |
---|
| 782 | |
---|
[2a23c28] | 783 | @page |
---|
| 784 | @subsection log_create - Creates a log file |
---|
| 785 | |
---|
| 786 | @subheading CALLING SEQUENCE: |
---|
| 787 | |
---|
| 788 | @ifset is-C |
---|
| 789 | @example |
---|
[30cc2e0] | 790 | #include <evlog.h> |
---|
| 791 | |
---|
[2a23c28] | 792 | int log_create( |
---|
| 793 | logd_t *ld, |
---|
| 794 | const char *path, |
---|
| 795 | ); |
---|
| 796 | @end example |
---|
| 797 | @end ifset |
---|
| 798 | |
---|
| 799 | @ifset is-Ada |
---|
| 800 | @end ifset |
---|
| 801 | |
---|
| 802 | @subheading STATUS CODES: |
---|
| 803 | |
---|
| 804 | @table @b |
---|
| 805 | @item ENOMEM |
---|
| 806 | The is ???????????? |
---|
| 807 | |
---|
| 808 | @end table |
---|
| 809 | |
---|
| 810 | @subheading DESCRIPTION: |
---|
| 811 | |
---|
[d1a859c] | 812 | This function dynamically allocates memory for the @code{ld}, associates |
---|
[30cc2e0] | 813 | a directory path to the @code{ld}, and provides access permissions to the |
---|
[d1a859c] | 814 | @code{ld}. |
---|
[2a23c28] | 815 | |
---|
| 816 | @subheading NOTES: |
---|
| 817 | |
---|
[d1a859c] | 818 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 819 | this service is available. |
---|
| 820 | |
---|
[2a23c28] | 821 | @page |
---|
| 822 | @subsection log_sys_create - Creates a system log file |
---|
| 823 | |
---|
| 824 | @subheading CALLING SEQUENCE: |
---|
| 825 | |
---|
| 826 | @ifset is-C |
---|
| 827 | @example |
---|
[30cc2e0] | 828 | #include <evlog.h> |
---|
| 829 | |
---|
[2a23c28] | 830 | int log_sys_create(); |
---|
| 831 | @end example |
---|
| 832 | @end ifset |
---|
| 833 | |
---|
| 834 | @ifset is-Ada |
---|
| 835 | @end ifset |
---|
| 836 | |
---|
| 837 | @subheading STATUS CODES: |
---|
| 838 | |
---|
| 839 | @table @b |
---|
| 840 | @item EEXIST |
---|
| 841 | The directory path to the system log already exist. |
---|
| 842 | |
---|
| 843 | @end table |
---|
| 844 | |
---|
| 845 | @subheading DESCRIPTION: |
---|
| 846 | |
---|
[d1a859c] | 847 | This function will create a predefined system log directory path and |
---|
| 848 | system log file if they do not already exist. |
---|
[2a23c28] | 849 | |
---|
| 850 | @subheading NOTES: |
---|
| 851 | |
---|
[d1a859c] | 852 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 853 | this service is available. |
---|