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