[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 |
---|
[566669f5] | 22 | @item @code{log_write} - Write to the system Log |
---|
[b67f7946] | 23 | @item @code{log_write_any} - Write to any log file |
---|
[566669f5] | 24 | @item @code{log_write_entry} - Write entry to any log file |
---|
[ebc67925] | 25 | @item @code{log_open} - Open a log file |
---|
[82db2d3a] | 26 | @item @code{log_read} - Read from a log file |
---|
[ebc67925] | 27 | @item @code{log_notify} - Notify Process of writes to the system log |
---|
| 28 | @item @code{log_close} - Close log descriptor |
---|
| 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 |
---|
[566669f5] | 79 | @subsection log_write - Write to the system 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 |
---|
[566669f5] | 103 | @item E2BIG |
---|
| 104 | This error indicates an inconsistency in the implementation. |
---|
| 105 | Report this as a bug. |
---|
| 106 | |
---|
[ebc67925] | 107 | @item EINVAL |
---|
[566669f5] | 108 | The @code{facility} argument is not a valid log facility. |
---|
[d1a859c] | 109 | |
---|
[ebc67925] | 110 | @item EINVAL |
---|
[566669f5] | 111 | The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}. |
---|
[d1a859c] | 112 | |
---|
[ebc67925] | 113 | @item EINVAL |
---|
[566669f5] | 114 | The @code{len} argument exceeds @code{LOG_MAXIUM_BUFFER_SIZE}. |
---|
[d1a859c] | 115 | |
---|
[566669f5] | 116 | @item EINVAL |
---|
| 117 | The @code{len} argument was non-zero and @code{buf} is NULL. |
---|
[d1a859c] | 118 | |
---|
[566669f5] | 119 | @item ENOSPC |
---|
| 120 | The device which contains the log file has run out of space. |
---|
[d1a859c] | 121 | |
---|
[ebc67925] | 122 | @item EIO |
---|
[566669f5] | 123 | An I/O error occurred in writing to the log file. |
---|
[16bed8a] | 124 | |
---|
| 125 | @end table |
---|
| 126 | |
---|
[832e33c] | 127 | @subheading DESCRIPTION: |
---|
| 128 | |
---|
[566669f5] | 129 | The @code{log_write_any} function writes an event record to the |
---|
| 130 | system log file. The event record written consists of the |
---|
| 131 | event attributes specified by the @code{facility}, @code{event_id}, |
---|
| 132 | and @code{severity} arguments as well as the data identified by the |
---|
| 133 | @code{buf} and @code{len} arguments. The fields of the event record |
---|
| 134 | structure to be written are filled in as follows: |
---|
| 135 | |
---|
| 136 | @table @b |
---|
| 137 | @item log_recid |
---|
| 138 | This is set to a monotonically increasing log record id |
---|
| 139 | maintained by the system for this individual log file. |
---|
| 140 | |
---|
| 141 | @item log_size |
---|
| 142 | This is set to the value of the @code{len} argument. |
---|
| 143 | |
---|
| 144 | @item log_event_id |
---|
| 145 | This is set to the value of the @code{event_id} argument. |
---|
| 146 | |
---|
| 147 | @item log_facility |
---|
| 148 | This is set to the value of the @code{facility} argument. |
---|
| 149 | |
---|
| 150 | @item log_severity |
---|
| 151 | This is set to the value of the @code{severity} argument. |
---|
| 152 | |
---|
| 153 | @item log_uid |
---|
| 154 | This is set to the value returned by @code{geteuid}. |
---|
| 155 | |
---|
| 156 | @item log_gid |
---|
| 157 | This is set to the value returned by @code{getegid}. |
---|
| 158 | |
---|
| 159 | @item log_pid |
---|
| 160 | This is set to the value returned by @code{getpid}. |
---|
| 161 | |
---|
| 162 | @item log_pgrp |
---|
| 163 | This is set to the value returned by @code{getpgrp}. |
---|
| 164 | |
---|
| 165 | @item log_time |
---|
| 166 | This is set to the value returned by @code{clock_gettime} for the |
---|
| 167 | CLOCK_REALTIME clock source. |
---|
| 168 | |
---|
| 169 | @end table |
---|
[ebc67925] | 170 | |
---|
[832e33c] | 171 | @subheading NOTES: |
---|
| 172 | |
---|
[d1a859c] | 173 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 174 | this service is available. |
---|
| 175 | |
---|
[566669f5] | 176 | This implementation can not return the @code{EPERM} error. |
---|
| 177 | |
---|
[b67f7946] | 178 | @page |
---|
| 179 | @subsection log_write_any - Write to the any log file |
---|
| 180 | |
---|
| 181 | @subheading CALLING SEQUENCE: |
---|
| 182 | |
---|
| 183 | @ifset is-C |
---|
| 184 | @example |
---|
| 185 | #include <evlog.h> |
---|
| 186 | |
---|
| 187 | int log_write_any( |
---|
| 188 | const logd_t logdes, |
---|
| 189 | const log_facility_t facility, |
---|
| 190 | const int event_id, |
---|
| 191 | const log_severity_t severity, |
---|
| 192 | const void *buf, |
---|
| 193 | const size_t len |
---|
| 194 | ); |
---|
| 195 | @end example |
---|
| 196 | @end ifset |
---|
| 197 | |
---|
| 198 | @ifset is-Ada |
---|
| 199 | @end ifset |
---|
| 200 | |
---|
| 201 | @subheading STATUS CODES: |
---|
| 202 | |
---|
| 203 | @table @b |
---|
[566669f5] | 204 | @item E2BIG |
---|
| 205 | This error indicates an inconsistency in the implementation. |
---|
| 206 | Report this as a bug. |
---|
| 207 | |
---|
| 208 | @item EBADF |
---|
| 209 | The @code{logdes} argument is not a valid log descriptor. |
---|
| 210 | |
---|
| 211 | @item EINVAL |
---|
| 212 | The @code{facility} argument is not a valid log facility. |
---|
| 213 | |
---|
[b67f7946] | 214 | @item EINVAL |
---|
[566669f5] | 215 | The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}. |
---|
[b67f7946] | 216 | |
---|
| 217 | @item EINVAL |
---|
[566669f5] | 218 | The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}. |
---|
[b67f7946] | 219 | |
---|
| 220 | @item EINVAL |
---|
[566669f5] | 221 | The @code{len} argument was non-zero and @code{buf} is NULL. |
---|
[b67f7946] | 222 | |
---|
| 223 | @item ENOSPC |
---|
[566669f5] | 224 | The device which contains the log file has run out of space. |
---|
[b67f7946] | 225 | |
---|
[566669f5] | 226 | @item EIO |
---|
| 227 | An I/O error occurred in writing to the log file. |
---|
| 228 | |
---|
| 229 | @end table |
---|
| 230 | |
---|
| 231 | @subheading DESCRIPTION: |
---|
| 232 | |
---|
| 233 | The @code{log_write_any} function writes an event record to the log file |
---|
| 234 | specified by @code{logdes}. The event record written consists of the |
---|
| 235 | event attributes specified by the @code{facility}, @code{event_id}, |
---|
| 236 | and @code{severity} arguments as well as the data identified by the |
---|
| 237 | @code{buf} and @code{len} arguments. The fields of the event record |
---|
| 238 | structure to be written are filled in as follows: |
---|
| 239 | |
---|
| 240 | @table @b |
---|
| 241 | @item log_recid |
---|
| 242 | This is set to a monotonically increasing log record id |
---|
| 243 | maintained by the system for this individual log file. |
---|
| 244 | |
---|
| 245 | @item log_size |
---|
| 246 | This is set to the value of the @code{len} argument. |
---|
| 247 | |
---|
| 248 | @item log_event_id |
---|
| 249 | This is set to the value of the @code{event_id} argument. |
---|
| 250 | |
---|
| 251 | @item log_facility |
---|
| 252 | This is set to the value of the @code{facility} argument. |
---|
| 253 | |
---|
| 254 | @item log_severity |
---|
| 255 | This is set to the value of the @code{severity} argument. |
---|
| 256 | |
---|
| 257 | @item log_uid |
---|
| 258 | This is set to the value returned by @code{geteuid}. |
---|
| 259 | |
---|
| 260 | @item log_gid |
---|
| 261 | This is set to the value returned by @code{getegid}. |
---|
| 262 | |
---|
| 263 | @item log_pid |
---|
| 264 | This is set to the value returned by @code{getpid}. |
---|
| 265 | |
---|
| 266 | @item log_pgrp |
---|
| 267 | This is set to the value returned by @code{getpgrp}. |
---|
| 268 | |
---|
| 269 | @item log_time |
---|
| 270 | This is set to the value returned by @code{clock_gettime} for the |
---|
| 271 | CLOCK_REALTIME clock source. |
---|
| 272 | |
---|
| 273 | @end table |
---|
| 274 | |
---|
| 275 | @subheading NOTES: |
---|
| 276 | |
---|
| 277 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 278 | this service is available. |
---|
| 279 | |
---|
| 280 | This implementation can not return the @code{EPERM} error. |
---|
| 281 | |
---|
| 282 | This function is not defined in the POSIX specification. It is |
---|
| 283 | an extension provided by this implementation. |
---|
| 284 | |
---|
| 285 | @page |
---|
| 286 | @subsection log_write_entry - Write entry to any log file |
---|
| 287 | |
---|
| 288 | @subheading CALLING SEQUENCE: |
---|
| 289 | |
---|
| 290 | @ifset is-C |
---|
| 291 | @example |
---|
| 292 | #include <evlog.h> |
---|
| 293 | |
---|
| 294 | int log_write_entry( |
---|
| 295 | const logd_t logdes, |
---|
| 296 | struct log_entry *entry, |
---|
| 297 | const void *buf, |
---|
| 298 | const size_t len |
---|
| 299 | ); |
---|
| 300 | @end example |
---|
| 301 | @end ifset |
---|
| 302 | |
---|
| 303 | @ifset is-Ada |
---|
| 304 | @end ifset |
---|
| 305 | |
---|
| 306 | @subheading STATUS CODES: |
---|
| 307 | |
---|
| 308 | @table @b |
---|
| 309 | @item E2BIG |
---|
| 310 | This error indicates an inconsistency in the implementation. |
---|
| 311 | Report this as a bug. |
---|
| 312 | |
---|
| 313 | @item EBADF |
---|
| 314 | The @code{logdes} argument is not a valid log descriptor. |
---|
| 315 | |
---|
| 316 | @item EFAULT |
---|
| 317 | The @code{entry} argument is not a valid pointer to a log entry. |
---|
| 318 | |
---|
| 319 | @item EINVAL |
---|
| 320 | The @code{facility} field in @code{entry} is not a valid log facility. |
---|
| 321 | |
---|
| 322 | @item EINVAL |
---|
| 323 | The @code{severity} field in @code{entry} exceeds @code{LOG_SEVERITY_MAX}. |
---|
| 324 | |
---|
| 325 | @item EINVAL |
---|
| 326 | The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}. |
---|
| 327 | |
---|
| 328 | @item EINVAL |
---|
| 329 | The @code{len} argument was non-zero and @code{buf} is NULL. |
---|
| 330 | |
---|
| 331 | @item ENOSPC |
---|
| 332 | The device which contains the log file has run out of space. |
---|
[b67f7946] | 333 | |
---|
| 334 | @item EIO |
---|
[566669f5] | 335 | An I/O error occurred in writing to the log file. |
---|
[b67f7946] | 336 | |
---|
| 337 | @end table |
---|
| 338 | |
---|
| 339 | @subheading DESCRIPTION: |
---|
| 340 | |
---|
[566669f5] | 341 | The @code{log_write_entry} function writes an event record |
---|
| 342 | specified by the @code{entry}, @code{buf}, and @code{len} arguments. |
---|
| 343 | Most of the fields of the event record pointed to by @code{entry} |
---|
| 344 | are left intact. The following fields are filled in as follows: |
---|
| 345 | |
---|
| 346 | @table @b |
---|
| 347 | @item log_recid |
---|
| 348 | This is set to a monotonically increasing log record id |
---|
| 349 | maintained by the system for this individual log file. |
---|
| 350 | |
---|
| 351 | @item log_size |
---|
| 352 | This is set to the value of the @code{len} argument. |
---|
| 353 | |
---|
| 354 | @end table |
---|
| 355 | |
---|
| 356 | This allows existing log entries from one log file to be written to |
---|
| 357 | another log file without destroying the logged information. |
---|
[b67f7946] | 358 | |
---|
| 359 | @subheading NOTES: |
---|
| 360 | |
---|
| 361 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 362 | this service is available. |
---|
| 363 | |
---|
[566669f5] | 364 | This implementation can not return the @code{EPERM} error. |
---|
| 365 | |
---|
| 366 | This function is not defined in the POSIX specification. It is |
---|
| 367 | an extension provided by this implementation. |
---|
| 368 | |
---|
[832e33c] | 369 | @page |
---|
[ebc67925] | 370 | @subsection log_open - Open a log file |
---|
[832e33c] | 371 | |
---|
| 372 | @subheading CALLING SEQUENCE: |
---|
| 373 | |
---|
| 374 | @ifset is-C |
---|
| 375 | @example |
---|
[30cc2e0] | 376 | #include <evlog.h> |
---|
| 377 | |
---|
[832e33c] | 378 | int log_open( |
---|
[6520befe] | 379 | logd_t *logdes, |
---|
[ebc67925] | 380 | const char *path, |
---|
| 381 | const log_query_t *query |
---|
[832e33c] | 382 | ); |
---|
| 383 | @end example |
---|
| 384 | @end ifset |
---|
| 385 | |
---|
| 386 | @ifset is-Ada |
---|
| 387 | @end ifset |
---|
| 388 | |
---|
| 389 | @subheading STATUS CODES: |
---|
| 390 | |
---|
[16bed8a] | 391 | @table @b |
---|
[ebc67925] | 392 | @item EACCES |
---|
| 393 | Search permission is denied on a component of the path prefix, |
---|
| 394 | or the log file exists and read permission is denied. |
---|
[d1a859c] | 395 | |
---|
[ebc67925] | 396 | @item EINTR |
---|
| 397 | A signal interrupted the call to log_open(). |
---|
[d1a859c] | 398 | |
---|
[ebc67925] | 399 | @item EINVAL |
---|
| 400 | The log_severity field of the query argument exceeds |
---|
[d5ef5bd1] | 401 | @code{LOG_SEVERITY_MAX}. |
---|
[d1a859c] | 402 | |
---|
[ebc67925] | 403 | @item EINVAL |
---|
| 404 | The path argument referred to a file that was not a log file. |
---|
[d1a859c] | 405 | |
---|
[ebc67925] | 406 | @item EMFILE |
---|
| 407 | Too many log file descriptors are currently in use by this |
---|
| 408 | process. |
---|
[d1a859c] | 409 | |
---|
[ebc67925] | 410 | @item ENAMETOOLONG |
---|
[d5ef5bd1] | 411 | The length of the path string exceeds @code{PATH_MAX}, or a pathname |
---|
| 412 | component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is |
---|
[ebc67925] | 413 | in effect. |
---|
[d1a859c] | 414 | |
---|
[ebc67925] | 415 | @item ENFILE |
---|
| 416 | Too many files are currently open in the system. |
---|
[d1a859c] | 417 | |
---|
[ebc67925] | 418 | @item ENOENT |
---|
| 419 | The file specified by the path argument does not exist. |
---|
[d1a859c] | 420 | |
---|
[ebc67925] | 421 | @item ENOTDIR |
---|
| 422 | A component of the path prefix is not a directory. |
---|
[16bed8a] | 423 | |
---|
| 424 | @end table |
---|
| 425 | |
---|
[832e33c] | 426 | @subheading DESCRIPTION: |
---|
| 427 | |
---|
[d1a859c] | 428 | The @code{log_open} function establishes the connection between a |
---|
| 429 | log file and a log file descriptor. It creates an open log file |
---|
[6520befe] | 430 | descriptor that refers to this query stream on the specified log file |
---|
| 431 | The log file descriptor is used by the other log functions to refer |
---|
| 432 | to that log query stream. The @code{path} argument points to a |
---|
| 433 | pathname for a log file. A @code{path} argument of NULL specifies |
---|
| 434 | the current system log file. |
---|
| 435 | |
---|
| 436 | The @code{query} argument is not NULL, then it points to a log query |
---|
| 437 | specification that is used to filter the records in the log file on |
---|
| 438 | subsequent @code{log_read} operations. This restricts the set of |
---|
| 439 | event records read using the returned log file descriptor to those |
---|
| 440 | which match the query. A query match occurs for a given record when |
---|
| 441 | that record's facility is a member of the query's facility set and |
---|
| 442 | the record's severity is greater than or equal to the severity specified |
---|
| 443 | in the query. |
---|
| 444 | |
---|
| 445 | If the value of the @code{query} argument is NULL, no query filter |
---|
| 446 | shall be applied. |
---|
[ebc67925] | 447 | |
---|
[832e33c] | 448 | @subheading NOTES: |
---|
| 449 | |
---|
[d1a859c] | 450 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 451 | this service is available. |
---|
| 452 | |
---|
[6520befe] | 453 | POSIX specifies that @code{EINVAL} will be returned if the |
---|
| 454 | @code{log_facilities} field of the @code{query} argument is not |
---|
| 455 | a valid facility set. In this implementation, this condition |
---|
| 456 | can never occur. |
---|
| 457 | |
---|
| 458 | Many error codes that POSIX specifies to be returned by @code{log_open} |
---|
| 459 | should actually be detected by @code{open} and passed back by the |
---|
| 460 | @code{log_open} implementation. In this implementation, @code{EACCESS}, |
---|
| 461 | @code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT}, |
---|
| 462 | and @code{ENOTDIR} are detected in this manner. |
---|
| 463 | |
---|
[832e33c] | 464 | @page |
---|
[82db2d3a] | 465 | @subsection log_read - Read from a log file |
---|
[832e33c] | 466 | |
---|
| 467 | @subheading CALLING SEQUENCE: |
---|
| 468 | |
---|
| 469 | @ifset is-C |
---|
| 470 | @example |
---|
[30cc2e0] | 471 | #include <evlog.h> |
---|
| 472 | |
---|
[832e33c] | 473 | int log_read( |
---|
[af5a571] | 474 | const logd_t logdes, |
---|
[ebc67925] | 475 | struct log_entry *entry, |
---|
| 476 | void *log_buf, |
---|
| 477 | const size_t log_len, |
---|
| 478 | const size_t *log_sizeread |
---|
[832e33c] | 479 | ); |
---|
| 480 | @end example |
---|
| 481 | @end ifset |
---|
| 482 | |
---|
| 483 | @ifset is-Ada |
---|
| 484 | @end ifset |
---|
| 485 | |
---|
| 486 | @subheading STATUS CODES: |
---|
| 487 | |
---|
[16bed8a] | 488 | @table @b |
---|
[82db2d3a] | 489 | @item E2BIG |
---|
| 490 | This error indicates an inconsistency in the implementation. |
---|
| 491 | Report this as a bug. |
---|
| 492 | |
---|
[ebc67925] | 493 | @item EBADF |
---|
[82db2d3a] | 494 | The @code{logdes} argument is not a valid log file descriptor. |
---|
| 495 | |
---|
| 496 | @item EFAULT |
---|
| 497 | The @code{entry} argument is not a valid pointer to a log entry structure. |
---|
| 498 | |
---|
| 499 | @item EFAULT |
---|
| 500 | The @code{log_sizeread} argument is not a valid pointer to a size_t. |
---|
[d1a859c] | 501 | |
---|
[ebc67925] | 502 | @item EBUSY |
---|
[82db2d3a] | 503 | No data available. There are no unread event records remaining |
---|
| 504 | in this log file. |
---|
[d1a859c] | 505 | |
---|
[ebc67925] | 506 | @item EINTR |
---|
| 507 | A signal interrupted the call to log_read(). |
---|
[d1a859c] | 508 | |
---|
[ebc67925] | 509 | @item EIO |
---|
| 510 | An I/O error occurred in reading from the event log. |
---|
[16bed8a] | 511 | |
---|
[82db2d3a] | 512 | @item EINVAL |
---|
| 513 | The matching event record has data associated with it and |
---|
| 514 | @code{log_buf} was not a valid pointer. |
---|
| 515 | |
---|
| 516 | @item EINVAL |
---|
| 517 | The matching event record has data associated with it which is |
---|
| 518 | longer than @code{log_len}. |
---|
| 519 | |
---|
[16bed8a] | 520 | @end table |
---|
| 521 | |
---|
[832e33c] | 522 | @subheading DESCRIPTION: |
---|
| 523 | |
---|
[82db2d3a] | 524 | The @code{log_read} function reads the @code{log_entry} |
---|
| 525 | structure and up to @code{log_len} bytes of data from the next |
---|
| 526 | event record of the log file associated with the open log file |
---|
| 527 | descriptor @code{logdes}. The event record read is placed |
---|
| 528 | into the @code{log_entry} structure pointed to by |
---|
| 529 | @code{entry} and any data into the buffer pointed to by @code{log_buf}. |
---|
| 530 | The log record ID of the returned event record is be stored in the |
---|
[a99ea16] | 531 | @code{log_recid} member of the @code{log_entry} structure for the event |
---|
[d1a859c] | 532 | record. |
---|
| 533 | |
---|
| 534 | If the query attribute of the open log file description associated with |
---|
[82db2d3a] | 535 | the @code{logdes} is set, the event record read will match that query. |
---|
| 536 | |
---|
| 537 | If the @code{log_read} is successful the call stores the actual length |
---|
[d1a859c] | 538 | of the data associated with the event record into the location specified by |
---|
[82db2d3a] | 539 | @code{log_sizeread}. This number will be less than or equal to |
---|
[d1a859c] | 540 | @code{log_len}. |
---|
[ebc67925] | 541 | |
---|
[832e33c] | 542 | @subheading NOTES: |
---|
| 543 | |
---|
[d1a859c] | 544 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 545 | this service is available. |
---|
| 546 | |
---|
[82db2d3a] | 547 | When @code{EINVAL} is returned, then no data is returned although the |
---|
| 548 | event record is returned. This is an extension to the POSIX specification. |
---|
| 549 | |
---|
| 550 | The POSIX specification specifically allows @code{log_read} to write |
---|
| 551 | greater than @code{log_len} bytes into @code{log_buf}. This is highly |
---|
| 552 | undesirable and this implementation will NOT do this. |
---|
| 553 | |
---|
[832e33c] | 554 | @page |
---|
[ebc67925] | 555 | @subsection log_notify - Notify Process of writes to the system log. |
---|
[832e33c] | 556 | |
---|
| 557 | @subheading CALLING SEQUENCE: |
---|
| 558 | |
---|
| 559 | @ifset is-C |
---|
| 560 | @example |
---|
[30cc2e0] | 561 | #include <evlog.h> |
---|
| 562 | |
---|
[832e33c] | 563 | int log_notify( |
---|
[ebc67925] | 564 | const logd_t logdes, |
---|
| 565 | const struct sigevent *notification |
---|
[832e33c] | 566 | ); |
---|
| 567 | @end example |
---|
| 568 | @end ifset |
---|
| 569 | |
---|
| 570 | @ifset is-Ada |
---|
| 571 | @end ifset |
---|
| 572 | |
---|
| 573 | @subheading STATUS CODES: |
---|
| 574 | |
---|
[16bed8a] | 575 | @table @b |
---|
[ebc67925] | 576 | @item EBADF |
---|
[a99ea16] | 577 | The logdes argument is not a valid log file descriptor. |
---|
[d1a859c] | 578 | |
---|
[ebc67925] | 579 | @item EINVAL |
---|
| 580 | The notification argument specifies an invalid signal. |
---|
[d1a859c] | 581 | |
---|
[ebc67925] | 582 | @item EINVAL |
---|
| 583 | The process has requested a notify on a log that will not be |
---|
| 584 | written to. |
---|
[d1a859c] | 585 | |
---|
[30cc2e0] | 586 | @item ENOSYS |
---|
[ebc67925] | 587 | The function log_notify() is not supported by this implementation. |
---|
[16bed8a] | 588 | |
---|
| 589 | @end table |
---|
| 590 | |
---|
[832e33c] | 591 | @subheading DESCRIPTION: |
---|
| 592 | |
---|
[d1a859c] | 593 | If the argument @code{notification} is not NULL this function registers |
---|
| 594 | the calling process to be notified of event records received by the system |
---|
| 595 | log, which match the query parameters associated with the open log descriptor |
---|
| 596 | specified by @code{logdes}. The notification specified by the |
---|
| 597 | @code{notification} argument shall be sent to the process when an event |
---|
| 598 | record received by the system log is matched by the query attribute of the |
---|
| 599 | open log file description associated with the @code{logdes} log file |
---|
| 600 | descriptor. If the calling process has already registered a notification |
---|
| 601 | for the @code{logdes} log file descriptor, the new notification shall |
---|
| 602 | replace the existing notification registration. |
---|
| 603 | |
---|
| 604 | If the @code{notification} argument is NULL and the calling process is |
---|
| 605 | currently registered to be notified for the @code{logdes} log file |
---|
| 606 | descriptor, the existing registration shall be removed. |
---|
[09470e0] | 607 | |
---|
[832e33c] | 608 | @subheading NOTES: |
---|
| 609 | |
---|
[d1a859c] | 610 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 611 | this service is available. |
---|
| 612 | |
---|
[832e33c] | 613 | @page |
---|
[ebc67925] | 614 | @subsection log_close - Close log descriptor |
---|
[832e33c] | 615 | |
---|
| 616 | @subheading CALLING SEQUENCE: |
---|
| 617 | |
---|
| 618 | @ifset is-C |
---|
| 619 | @example |
---|
[30cc2e0] | 620 | #include <evlog.h> |
---|
| 621 | |
---|
[832e33c] | 622 | int log_close( |
---|
[ebc67925] | 623 | const logd_t logdes |
---|
[832e33c] | 624 | ); |
---|
| 625 | @end example |
---|
| 626 | @end ifset |
---|
| 627 | |
---|
| 628 | @ifset is-Ada |
---|
| 629 | @end ifset |
---|
| 630 | |
---|
| 631 | @subheading STATUS CODES: |
---|
| 632 | |
---|
[16bed8a] | 633 | @table @b |
---|
[ebc67925] | 634 | @item EBADF |
---|
| 635 | The logdes argument is not a valid log file descriptor. |
---|
[16bed8a] | 636 | |
---|
| 637 | @end table |
---|
| 638 | |
---|
[832e33c] | 639 | @subheading DESCRIPTION: |
---|
| 640 | |
---|
[d1a859c] | 641 | The @code{log_close} function deallocates the open log file descriptor |
---|
| 642 | indicated by @code{log_des}. |
---|
[2dd561a3] | 643 | |
---|
[d1a859c] | 644 | When all log file descriptors associated with an open log file description |
---|
[b67f7946] | 645 | have been closed, the open log file description is freed. |
---|
[2dd561a3] | 646 | |
---|
[d1a859c] | 647 | If the link count of the log file is zero, when all log file descriptors |
---|
[b67f7946] | 648 | have been closed, the space occupied by the log file is freed and the |
---|
[d1a859c] | 649 | log file shall no longer be accessible. |
---|
[2dd561a3] | 650 | |
---|
[d1a859c] | 651 | If the process has successfully registered a notification request for the |
---|
[b67f7946] | 652 | log file descriptor, the registration is removed. |
---|
[ebc67925] | 653 | |
---|
[832e33c] | 654 | @subheading NOTES: |
---|
| 655 | |
---|
[d1a859c] | 656 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 657 | this service is available. |
---|
| 658 | |
---|
[832e33c] | 659 | @page |
---|
[ebc67925] | 660 | @subsection log_seek - Reposition log file offset |
---|
[832e33c] | 661 | |
---|
| 662 | @subheading CALLING SEQUENCE: |
---|
| 663 | |
---|
| 664 | @ifset is-C |
---|
| 665 | @example |
---|
[30cc2e0] | 666 | #include <evlog.h> |
---|
| 667 | |
---|
[832e33c] | 668 | int log_seek( |
---|
[ebc67925] | 669 | const logd_t logdes, |
---|
| 670 | log_recid_t log_recid |
---|
[832e33c] | 671 | ); |
---|
| 672 | @end example |
---|
| 673 | @end ifset |
---|
| 674 | |
---|
| 675 | @ifset is-Ada |
---|
| 676 | @end ifset |
---|
| 677 | |
---|
| 678 | @subheading STATUS CODES: |
---|
| 679 | |
---|
[16bed8a] | 680 | @table @b |
---|
[ebc67925] | 681 | @item EBADF |
---|
[af5a571] | 682 | The @code{logdes} argument is not a valid log file descriptor. |
---|
[16bed8a] | 683 | |
---|
| 684 | @end table |
---|
| 685 | |
---|
[832e33c] | 686 | @subheading DESCRIPTION: |
---|
| 687 | |
---|
[af5a571] | 688 | The @code{log_seek} function sets the log file offset of the open |
---|
[a99ea16] | 689 | log description associated with the @code{logdes} log file descriptor |
---|
[d1a859c] | 690 | to the event record in the log file identified by @code{log_recid}. |
---|
| 691 | The @code{log_recid} argument is either the record id of a valid event |
---|
| 692 | record or one of the following values, as defined in the header <evlog.h>: |
---|
| 693 | |
---|
| 694 | @table @b |
---|
| 695 | @item LOG_SEEK_START |
---|
| 696 | Set log file position to point at the first event |
---|
[af5a571] | 697 | record in the log file. |
---|
[2dd561a3] | 698 | |
---|
[d1a859c] | 699 | @item LOG_SEEK_END |
---|
| 700 | Set log file position to point after the last event |
---|
[af5a571] | 701 | record in the log file. |
---|
[2dd561a3] | 702 | |
---|
[d1a859c] | 703 | @end table |
---|
[2dd561a3] | 704 | |
---|
[832e33c] | 705 | @subheading NOTES: |
---|
| 706 | |
---|
[d1a859c] | 707 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 708 | this service is available. |
---|
| 709 | |
---|
[af5a571] | 710 | This implementation can not return @code{EINTR}. |
---|
| 711 | |
---|
| 712 | This implementation can not return @code{EINVAL} to indicate that |
---|
| 713 | the @code{log_recid} argument is not a valid record id. |
---|
| 714 | |
---|
[832e33c] | 715 | @page |
---|
[ebc67925] | 716 | @subsection log_severity_before - Compare event record severities |
---|
[832e33c] | 717 | |
---|
| 718 | @subheading CALLING SEQUENCE: |
---|
| 719 | |
---|
| 720 | @ifset is-C |
---|
| 721 | @example |
---|
[30cc2e0] | 722 | #include <evlog.h> |
---|
| 723 | |
---|
[832e33c] | 724 | int log_severity_before( |
---|
[ebc67925] | 725 | log_severity_t s1, |
---|
| 726 | log_severity_t s2 |
---|
[832e33c] | 727 | ); |
---|
| 728 | @end example |
---|
| 729 | @end ifset |
---|
| 730 | |
---|
| 731 | @ifset is-Ada |
---|
| 732 | @end ifset |
---|
| 733 | |
---|
| 734 | @subheading STATUS CODES: |
---|
| 735 | |
---|
[16bed8a] | 736 | @table @b |
---|
[c5568160] | 737 | @item 0 |
---|
| 738 | The severity of @code{s1} is less than that of @code{s2}. |
---|
| 739 | |
---|
| 740 | @item 1 |
---|
| 741 | The severity of @code{s1} is greater than or equal that of @code{s2}. |
---|
| 742 | |
---|
[ebc67925] | 743 | @item EINVAL |
---|
[d5ef5bd1] | 744 | The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}. |
---|
[16bed8a] | 745 | |
---|
| 746 | @end table |
---|
| 747 | |
---|
[832e33c] | 748 | @subheading DESCRIPTION: |
---|
| 749 | |
---|
[c5568160] | 750 | The @code{log_severity_before} function compares the severity order |
---|
| 751 | of the @code{s1} and @code{s2} arguments. If @code{s1} is of |
---|
| 752 | severity greater than or equal to that of @code{s2}, then this |
---|
| 753 | function returns 1. Otherwise, it returns 0. |
---|
[2dd561a3] | 754 | |
---|
[c5568160] | 755 | If either @code{s1} or @code{s2} specify invalid severity values, the |
---|
| 756 | return value of @code{log_severity_before} is unspecified. |
---|
[ebc67925] | 757 | |
---|
[832e33c] | 758 | @subheading NOTES: |
---|
| 759 | |
---|
[d1a859c] | 760 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 761 | this service is available. |
---|
| 762 | |
---|
[c5568160] | 763 | The POSIX specification of the return value for this function is ambiguous. |
---|
| 764 | If @code{EINVAL} is equal to 1 in an implementation, then the application |
---|
| 765 | can not distinguish between greater than and an error condition. |
---|
| 766 | |
---|
[832e33c] | 767 | @page |
---|
[ebc67925] | 768 | @subsection log_facilityemptyset - Manipulate log facility sets |
---|
[832e33c] | 769 | |
---|
| 770 | @subheading CALLING SEQUENCE: |
---|
| 771 | |
---|
| 772 | @ifset is-C |
---|
| 773 | @example |
---|
[30cc2e0] | 774 | #include <evlog.h> |
---|
| 775 | |
---|
[832e33c] | 776 | int log_facilityemptyset( |
---|
[ebc67925] | 777 | log_facility_set_t *set |
---|
[832e33c] | 778 | ); |
---|
| 779 | @end example |
---|
| 780 | @end ifset |
---|
| 781 | |
---|
| 782 | @ifset is-Ada |
---|
| 783 | @end ifset |
---|
| 784 | |
---|
| 785 | @subheading STATUS CODES: |
---|
| 786 | |
---|
[16bed8a] | 787 | @table @b |
---|
[d65d22a0] | 788 | @item EFAULT |
---|
| 789 | The @code{set} argument is an invalid pointer. |
---|
[16bed8a] | 790 | |
---|
| 791 | @end table |
---|
| 792 | |
---|
[832e33c] | 793 | @subheading DESCRIPTION: |
---|
| 794 | |
---|
[d1a859c] | 795 | The @code{log_facilityemptyset} function initializes the facility |
---|
[a99ea16] | 796 | set pointed to by the argument @code{set}, such that all facilities |
---|
[d65d22a0] | 797 | are excluded. |
---|
| 798 | |
---|
| 799 | @subheading NOTES: |
---|
| 800 | |
---|
| 801 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 802 | this service is available. |
---|
[d1a859c] | 803 | |
---|
| 804 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 805 | @code{log_facilityfillset} at least once for each object of type |
---|
| 806 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 807 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 808 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 809 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 810 | @code{log_open} functions, the results are undefined. |
---|
| 811 | |
---|
[832e33c] | 812 | @page |
---|
[ebc67925] | 813 | @subsection log_facilityfillset - Manipulate log facility sets |
---|
[832e33c] | 814 | |
---|
| 815 | @subheading CALLING SEQUENCE: |
---|
| 816 | |
---|
| 817 | @ifset is-C |
---|
| 818 | @example |
---|
[30cc2e0] | 819 | #include <evlog.h> |
---|
| 820 | |
---|
[832e33c] | 821 | int log_facilityfillset( |
---|
[ebc67925] | 822 | log_facility_set_t *set |
---|
[832e33c] | 823 | ); |
---|
| 824 | @end example |
---|
| 825 | @end ifset |
---|
| 826 | |
---|
| 827 | @ifset is-Ada |
---|
| 828 | @end ifset |
---|
| 829 | |
---|
| 830 | @subheading STATUS CODES: |
---|
| 831 | |
---|
[16bed8a] | 832 | @table @b |
---|
[d65d22a0] | 833 | @item EFAULT |
---|
| 834 | The @code{set} argument is an invalid pointer. |
---|
[16bed8a] | 835 | |
---|
| 836 | @end table |
---|
| 837 | |
---|
[832e33c] | 838 | @subheading DESCRIPTION: |
---|
| 839 | |
---|
[d65d22a0] | 840 | The @code{log_facilityfillset} function initializes the facility |
---|
[a99ea16] | 841 | set pointed to by the argument @code{set}, such that all facilities |
---|
[d1a859c] | 842 | are included. |
---|
| 843 | |
---|
[d65d22a0] | 844 | @subheading NOTES: |
---|
| 845 | |
---|
| 846 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 847 | this service is available. |
---|
| 848 | |
---|
[d1a859c] | 849 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 850 | @code{log_facilityfillset} at least once for each object of type |
---|
| 851 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 852 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 853 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 854 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 855 | @code{log_open} functions, the results are undefined. |
---|
| 856 | |
---|
[832e33c] | 857 | @page |
---|
[ebc67925] | 858 | @subsection log_facilityaddset - Manipulate log facility sets |
---|
[832e33c] | 859 | |
---|
| 860 | @subheading CALLING SEQUENCE: |
---|
| 861 | |
---|
| 862 | @ifset is-C |
---|
| 863 | @example |
---|
[30cc2e0] | 864 | #include <evlog.h> |
---|
| 865 | |
---|
[832e33c] | 866 | int log_facilityaddset( |
---|
[ebc67925] | 867 | log_facility_set_t *set, |
---|
[d65d22a0] | 868 | log_facility_t facilityno |
---|
[832e33c] | 869 | ); |
---|
| 870 | @end example |
---|
| 871 | @end ifset |
---|
| 872 | |
---|
| 873 | @ifset is-Ada |
---|
| 874 | @end ifset |
---|
| 875 | |
---|
| 876 | @subheading STATUS CODES: |
---|
| 877 | |
---|
[16bed8a] | 878 | @table @b |
---|
[d65d22a0] | 879 | @item EFAULT |
---|
| 880 | The @code{set} argument is an invalid pointer. |
---|
| 881 | |
---|
[ebc67925] | 882 | @item EINVAL |
---|
[d65d22a0] | 883 | The @code{facilityno} argument is not a valid facility. |
---|
[16bed8a] | 884 | |
---|
| 885 | @end table |
---|
| 886 | |
---|
[832e33c] | 887 | @subheading DESCRIPTION: |
---|
| 888 | |
---|
[d65d22a0] | 889 | The @code{log_facilityaddset} function adds the individual |
---|
| 890 | facility specified by the value of the argument @code{facilityno} |
---|
| 891 | to the facility set pointed to by the argument @code{set}. |
---|
[d1a859c] | 892 | |
---|
[d65d22a0] | 893 | @subheading NOTES: |
---|
| 894 | |
---|
| 895 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 896 | this service is available. |
---|
[d1a859c] | 897 | |
---|
| 898 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 899 | @code{log_facilityfillset} at least once for each object of type |
---|
| 900 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 901 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 902 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 903 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 904 | @code{log_open} functions, the results are undefined. |
---|
| 905 | |
---|
[832e33c] | 906 | @page |
---|
[ebc67925] | 907 | @subsection log_facilitydelset - Manipulate log facility sets |
---|
[832e33c] | 908 | |
---|
| 909 | @subheading CALLING SEQUENCE: |
---|
| 910 | |
---|
| 911 | @ifset is-C |
---|
| 912 | @example |
---|
[30cc2e0] | 913 | #include <evlog.h> |
---|
| 914 | |
---|
[832e33c] | 915 | int log_facilitydelset( |
---|
[ebc67925] | 916 | log_facility_set_t *set, |
---|
[d65d22a0] | 917 | log_facility_t facilityno |
---|
[832e33c] | 918 | ); |
---|
| 919 | @end example |
---|
| 920 | @end ifset |
---|
| 921 | |
---|
| 922 | @ifset is-Ada |
---|
| 923 | @end ifset |
---|
| 924 | |
---|
| 925 | @subheading STATUS CODES: |
---|
| 926 | |
---|
[16bed8a] | 927 | @table @b |
---|
[d65d22a0] | 928 | @item EFAULT |
---|
| 929 | The @code{set} argument is an invalid pointer. |
---|
| 930 | |
---|
[ebc67925] | 931 | @item EINVAL |
---|
[d65d22a0] | 932 | The @code{facilityno} argument is not a valid facility. |
---|
[16bed8a] | 933 | |
---|
| 934 | @end table |
---|
| 935 | |
---|
[832e33c] | 936 | @subheading DESCRIPTION: |
---|
| 937 | |
---|
[d65d22a0] | 938 | The @code{log_facilitydelset} function deletes the individual |
---|
| 939 | facility specified by the value of the argument @code{facilityno} |
---|
| 940 | from the facility set pointed to by the argument @code{set}. |
---|
[d1a859c] | 941 | |
---|
[d65d22a0] | 942 | @subheading NOTES: |
---|
| 943 | |
---|
| 944 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 945 | this service is available. |
---|
[d1a859c] | 946 | |
---|
| 947 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 948 | @code{log_facilityfillset} at least once for each object of type |
---|
| 949 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 950 | such an object is not initialized in this way, but is nonetheless |
---|
[d65d22a0] | 951 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
[d1a859c] | 952 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 953 | @code{log_open} functions, the results are undefined. |
---|
| 954 | |
---|
[832e33c] | 955 | @page |
---|
[ebc67925] | 956 | @subsection log_facilityismember - Manipulate log facility sets |
---|
[832e33c] | 957 | |
---|
| 958 | @subheading CALLING SEQUENCE: |
---|
| 959 | |
---|
| 960 | @ifset is-C |
---|
| 961 | @example |
---|
[30cc2e0] | 962 | #include <evlog.h> |
---|
| 963 | |
---|
[832e33c] | 964 | int log_facilityismember( |
---|
[ebc67925] | 965 | const log_facility_set_t *set, |
---|
| 966 | log_facility_t facilityno, |
---|
| 967 | const int *member |
---|
[832e33c] | 968 | ); |
---|
| 969 | @end example |
---|
| 970 | @end ifset |
---|
| 971 | |
---|
| 972 | @ifset is-Ada |
---|
| 973 | @end ifset |
---|
| 974 | |
---|
| 975 | @subheading STATUS CODES: |
---|
| 976 | |
---|
[16bed8a] | 977 | @table @b |
---|
[d65d22a0] | 978 | @item EFAULT |
---|
| 979 | The @code{set} or @code{member} argument is an invalid pointer. |
---|
| 980 | |
---|
[ebc67925] | 981 | @item EINVAL |
---|
[d65d22a0] | 982 | The @code{facilityno} argument is not a valid facility. |
---|
[16bed8a] | 983 | |
---|
| 984 | @end table |
---|
| 985 | |
---|
[832e33c] | 986 | @subheading DESCRIPTION: |
---|
| 987 | |
---|
[d1a859c] | 988 | The @code{log_facilityismember} function tests whether the facility |
---|
| 989 | specified by the value of the argument @code{facilityno} is a member |
---|
| 990 | of the set pointed to by the argument @code{set}. Upon successful |
---|
| 991 | completion, the @code{log_facilityismember} function either returns |
---|
| 992 | a value of one to the location specified by @code{member} if the |
---|
[d65d22a0] | 993 | specified facility is a member of the specified set or value of |
---|
| 994 | zero to the location specified by @code{member} if the specified |
---|
| 995 | facility is not a member of the specified set. |
---|
[2dd561a3] | 996 | |
---|
[832e33c] | 997 | @subheading NOTES: |
---|
| 998 | |
---|
[d1a859c] | 999 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 1000 | this service is available. |
---|
| 1001 | |
---|
[d65d22a0] | 1002 | Applications shall call either @code{log_facilityemptyset} or |
---|
| 1003 | @code{log_facilityfillset} at least once for each object of type |
---|
| 1004 | @code{log_facilityset_t} prior to any other use of that object. If |
---|
| 1005 | such an object is not initialized in this way, but is nonetheless |
---|
| 1006 | supplied as an argument to any of the @code{log_facilityaddset}, |
---|
| 1007 | @code{logfacilitydelset}, @code{log_facilityismember} or |
---|
| 1008 | @code{log_open} functions, the results are undefined. |
---|
| 1009 | |
---|
[2a23c28] | 1010 | @page |
---|
| 1011 | @subsection log_create - Creates a log file |
---|
| 1012 | |
---|
| 1013 | @subheading CALLING SEQUENCE: |
---|
| 1014 | |
---|
| 1015 | @ifset is-C |
---|
| 1016 | @example |
---|
[30cc2e0] | 1017 | #include <evlog.h> |
---|
| 1018 | |
---|
[2a23c28] | 1019 | int log_create( |
---|
| 1020 | logd_t *ld, |
---|
| 1021 | const char *path, |
---|
| 1022 | ); |
---|
| 1023 | @end example |
---|
| 1024 | @end ifset |
---|
| 1025 | |
---|
| 1026 | @ifset is-Ada |
---|
| 1027 | @end ifset |
---|
| 1028 | |
---|
| 1029 | @subheading STATUS CODES: |
---|
| 1030 | |
---|
| 1031 | @table @b |
---|
| 1032 | @item ENOMEM |
---|
| 1033 | The is ???????????? |
---|
| 1034 | |
---|
| 1035 | @end table |
---|
| 1036 | |
---|
| 1037 | @subheading DESCRIPTION: |
---|
| 1038 | |
---|
[d1a859c] | 1039 | This function dynamically allocates memory for the @code{ld}, associates |
---|
[30cc2e0] | 1040 | a directory path to the @code{ld}, and provides access permissions to the |
---|
[d1a859c] | 1041 | @code{ld}. |
---|
[2a23c28] | 1042 | |
---|
| 1043 | @subheading NOTES: |
---|
| 1044 | |
---|
[d1a859c] | 1045 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 1046 | this service is available. |
---|
| 1047 | |
---|
[2a23c28] | 1048 | @page |
---|
| 1049 | @subsection log_sys_create - Creates a system log file |
---|
| 1050 | |
---|
| 1051 | @subheading CALLING SEQUENCE: |
---|
| 1052 | |
---|
| 1053 | @ifset is-C |
---|
| 1054 | @example |
---|
[30cc2e0] | 1055 | #include <evlog.h> |
---|
| 1056 | |
---|
[2a23c28] | 1057 | int log_sys_create(); |
---|
| 1058 | @end example |
---|
| 1059 | @end ifset |
---|
| 1060 | |
---|
| 1061 | @ifset is-Ada |
---|
| 1062 | @end ifset |
---|
| 1063 | |
---|
| 1064 | @subheading STATUS CODES: |
---|
| 1065 | |
---|
| 1066 | @table @b |
---|
| 1067 | @item EEXIST |
---|
| 1068 | The directory path to the system log already exist. |
---|
| 1069 | |
---|
| 1070 | @end table |
---|
| 1071 | |
---|
| 1072 | @subheading DESCRIPTION: |
---|
| 1073 | |
---|
[d1a859c] | 1074 | This function will create a predefined system log directory path and |
---|
| 1075 | system log file if they do not already exist. |
---|
[2a23c28] | 1076 | |
---|
| 1077 | @subheading NOTES: |
---|
| 1078 | |
---|
[d1a859c] | 1079 | The @code{_POSIX_LOGGING} feature flag is defined to indicate |
---|
| 1080 | this service is available. |
---|