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