summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters
diff options
context:
space:
mode:
authorRalf Corsepius <ralf.corsepius@rtems.org>2006-01-19 06:54:51 +0000
committerRalf Corsepius <ralf.corsepius@rtems.org>2006-01-19 06:54:51 +0000
commit653c295560571fbbc38d9360091639814cbabba8 (patch)
treeafc58d9ef3b2a28e78a66527dfbbfc9965cae07e /doc/new_chapters
parent3ed72613484435cba91569ed40dfb3db256de48f (diff)
downloadrtems-653c295560571fbbc38d9360091639814cbabba8.tar.bz2
Remove
Diffstat (limited to 'doc/new_chapters')
-rw-r--r--doc/new_chapters/eventlog.t1265
1 files changed, 0 insertions, 1265 deletions
diff --git a/doc/new_chapters/eventlog.t b/doc/new_chapters/eventlog.t
deleted file mode 100644
index f502d81ed2..0000000000
--- a/doc/new_chapters/eventlog.t
+++ /dev/null
@@ -1,1265 +0,0 @@
-@c
-@c COPYRIGHT (c) 1988-2002.
-@c On-Line Applications Research Corporation (OAR).
-@c All rights reserved.
-@c
-@c $Id$
-@c
-
-@chapter Event Logging Manager
-
-@section Introduction
-
-The event logging manager provides a portable method for logging
-system and application events and subsequent processing of those
-events. The capabilities in this manager were defined in the POSIX
-1003.1h/D3 proposed standard titled @b{Services for Reliable,
-Available, and Serviceable Systems}.
-
-The directives provided by the event logging manager are:
-
-@itemize @bullet
-@item @code{log_create} - Create a log file
-@item @code{log_sys_create} - Create a system log file
-@item @code{log_write} - Write to the system Log
-@item @code{log_write_any} - Write to any log file
-@item @code{log_write_entry} - Write entry to any log file
-@item @code{log_open} - Open a log file
-@item @code{log_read} - Read from a log file
-@item @code{log_notify} - Notify Process of writes to the system log
-@item @code{log_close} - Close log descriptor
-@item @code{log_seek} - Reposition log file offset
-@item @code{log_severity_before} - Compare event record severities
-@item @code{log_facilityemptyset} - Manipulate log facility sets
-@item @code{log_facilityfillset} - Manipulate log facility sets
-@item @code{log_facilityaddset} - Manipulate log facility sets
-@item @code{log_facilitydelset} - Manipulate log facility sets
-@item @code{log_facilityismember} - Manipulate log facility sets
-@item @code{log_facilityisvalid} - Manipulate log facility sets
-@end itemize
-
-@section Background
-
-@subsection Log Files and Events
-
-The operating system uses a special log file named @code{syslog}.
-This log file is called the system log and is automatically created and
-tracked by the operating system. The system log is written with
-the @code{log_write()} function. An alternative log file may be written
-using the @code{log_write_any()} function. It is possible to use @code{log_read()}
-to query the system log and and write the records to a non-system log file
-using @code{log_write_entry()} to produce a filtered version of the
-system log. For example you could produce a log of all disk controller
-faults that have occurred.
-
-A non-system log may be a special log file created by an application to
-describe application faults, or a subset of the system log created
-by the application.
-
-
-
-@subsection Facilities
-
-A facility is an identification code for a subsystem, device, or
-other object about which information is being written to
-a log file.
-
-A facility set is a collection of facilities.
-
-@subsection Severity
-
-Severity is a rating of the error that is being logged.
-
-@subsection Queries
-
-
-The facility identifier and the event severity are the basis for
-subsequent log query. A log query is used as a filter to
-obtain a subset of a given log file. The log file may be configured
-to send out an event.
-
-@section Operations
-
-@subsection Creating and Writing a non-System Log
-
-The following code fragment create a non-System log file at /temp/.
-A real filename previously read entry and buffer @code{log_buf} of size
-@code{readsize} are written into the log. See the discussion on opening
-and reading a log for how the entry is created.
-
-@example
-#include <evlog.h>
- :
- logd_t *outlog = NULL;
- char *path = "/temp/";
-
- log_create( outlog, path );
- :
- log_write_entry( outlog, &entry, log_buf, readsize );
-
-@end example
-
-@subsection Reading a Log
-
-Discuss opening and reading from a log.
-
-@example
- build a query
- log_open
- log_read loop
-@end example
-
-@section Directives
-
-This section details the event logging manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
-
-@page
-@subsection log_write - Write to the system Log
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_write(
- const log_facility_t facility,
- const int event_id,
- const log_severity_t severity,
- const void *buf,
- const size_t len
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_write()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item E2BIG
-This error indicates an inconsistency in the implementation.
-Report this as a bug.
-
-@item EINVAL
-The @code{facility} argument is not a valid log facility.
-
-@item EINVAL
-The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
-
-@item EINVAL
-The @code{len} argument exceeds @code{LOG_MAXIUM_BUFFER_SIZE}.
-
-@item EINVAL
-The @code{len} argument was non-zero and @code{buf} is @code{NULL}.
-
-@item ENOSPC
-The device which contains the log file has run out of space.
-
-@item EIO
-An I/O error occurred in writing to the log file.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_write} function writes an event record to the
-system log file. The event record written consists of the
-event attributes specified by the @code{facility}, @code{event_id},
-and @code{severity} arguments as well as the data identified by the
-@code{buf} and @code{len} arguments. The fields of the event record
-structure to be written are filled in as follows:
-
-@table @b
-@item log_recid
-This is set to a monotonically increasing log record id
-maintained by the system for this individual log file.
-
-@item log_size
-This is set to the value of the @code{len} argument.
-
-@item log_event_id
-This is set to the value of the @code{event_id} argument.
-
-@item log_facility
-This is set to the value of the @code{facility} argument.
-
-@item log_severity
-This is set to the value of the @code{severity} argument.
-
-@item log_uid
-This is set to the value returned by @code{geteuid()}.
-
-@item log_gid
-This is set to the value returned by @code{getegid()}.
-
-@item log_pid
-This is set to the value returned by @code{getpid()}.
-
-@item log_pgrp
-This is set to the value returned by @code{getpgrp()}.
-
-@item log_time
-This is set to the value returned by @code{clock_gettime()} for the
-@code{CLOCK_REALTIME clock} source.
-
-@end table
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-This implementation can not return the @code{EPERM} error.
-
-@page
-@subsection log_write_any - Write to the any log file
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_write_any(
- const logd_t logdes,
- const log_facility_t facility,
- const int event_id,
- const log_severity_t severity,
- const void *buf,
- const size_t len
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_write_any()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item E2BIG
-This error indicates an inconsistency in the implementation.
-Report this as a bug.
-
-@item EBADF
-The @code{logdes} argument is not a valid log descriptor.
-
-@item EINVAL
-The @code{facility} argument is not a valid log facility.
-
-@item EINVAL
-The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
-
-@item EINVAL
-The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
-
-@item EINVAL
-The @code{len} argument was non-zero and @code{buf} is @code{NULL}.
-
-@item ENOSPC
-The device which contains the log file has run out of space.
-
-@item EIO
-An I/O error occurred in writing to the log file.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_write_any()} function writes an event record to the log file
-specified by @code{logdes}. The event record written consists of the
-event attributes specified by the @code{facility}, @code{event_id},
-and @code{severity} arguments as well as the data identified by the
-@code{buf} and @code{len} arguments. The fields of the event record
-structure to be written are filled in as follows:
-
-@table @b
-@item log_recid
-This is set to a monotonically increasing log record id
-maintained by the system for this individual log file.
-
-@item log_size
-This is set to the value of the @code{len} argument.
-
-@item log_event_id
-This is set to the value of the @code{event_id} argument.
-
-@item log_facility
-This is set to the value of the @code{facility} argument.
-
-@item log_severity
-This is set to the value of the @code{severity} argument.
-
-@item log_uid
-This is set to the value returned by @code{geteuid()}.
-
-@item log_gid
-This is set to the value returned by @code{getegid()}.
-
-@item log_pid
-This is set to the value returned by @code{getpid()}.
-
-@item log_pgrp
-This is set to the value returned by @code{getpgrp()}.
-
-@item log_time
-This is set to the value returned by @code{clock_gettime()} for the
-@code{CLOCK_REALTIME} clock source.
-
-@end table
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-This implementation can not return the @code{EPERM} error.
-
-This function is not defined in the POSIX specification. It is
-an extension provided by this implementation.
-
-@page
-@subsection log_write_entry - Write entry to any log file
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_write_entry(
- const logd_t logdes,
- struct log_entry *entry,
- const void *buf,
- const size_t len
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_write_entry()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item E2BIG
-This error indicates an inconsistency in the implementation.
-Report this as a bug.
-
-@item EBADF
-The @code{logdes} argument is not a valid log descriptor.
-
-@item EFAULT
-The @code{entry} argument is not a valid pointer to a log entry.
-
-@item EINVAL
-The @code{facility} field in @code{entry} is not a valid log facility.
-
-@item EINVAL
-The @code{severity} field in @code{entry} exceeds @code{LOG_SEVERITY_MAX}.
-
-@item EINVAL
-The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
-
-@item EINVAL
-The @code{len} argument was non-zero and @code{buf} is NULL.
-
-@item ENOSPC
-The device which contains the log file has run out of space.
-
-@item EIO
-An I/O error occurred in writing to the log file.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_write_entry()} function writes an event record
-specified by the @code{entry}, @code{buf}, and @code{len} arguments.
-Most of the fields of the event record pointed to by @code{entry}
-are left intact. The following fields are filled in as follows:
-
-@table @b
-@item log_recid
-This is set to a monotonically increasing log record id
-maintained by the system for this individual log file.
-
-@item log_size
-This is set to the value of the @code{len} argument.
-
-@end table
-
-This allows existing log entries from one log file to be written to
-another log file without destroying the logged information.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-This implementation can not return the @code{EPERM} error.
-
-This function is not defined in the POSIX specification. It is
-an extension provided by this implementation.
-
-@page
-@subsection log_open - Open a log file
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_open(
- logd_t *logdes,
- const char *path,
- const log_query_t *query
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_open()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EACCES
-Search permission is denied on a component of the @code{path} prefix,
-or the log file exists and read permission is denied.
-
-@item EINTR
-A signal interrupted the call to @code{log_open()}.
-
-@item EINVAL
-The log_severity field of the query argument exceeds
-@code{LOG_SEVERITY_MAX}.
-
-@item EINVAL
-The @code{path} argument referred to a file that was not a log file.
-
-@item EMFILE
-Too many log file descriptors are currently in use by this
-process.
-
-@item ENAMETOOLONG
-The length of the path string exceeds @code{PATH_MAX}, or a pathname
-component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
-in effect.
-
-@item ENFILE
-Too many files are currently open in the system.
-
-@item ENOENT
-The file specified by the @code{path} argument does not exist.
-
-@item ENOTDIR
-A component of the @code{path} prefix is not a directory.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_open()} function establishes the connection between a
-log file and a log file descriptor. It creates an open log file
-descriptor that refers to this query stream on the specified log file
-The log file descriptor is used by the other log functions to refer
-to that log query stream. The @code{path} argument points to a
-pathname for a log file. A @code{path} argument of @code{NULL} specifies
-the current system log file.
-
-The @code{query} argument is not @code{NULL}, then it points to a log query
-specification that is used to filter the records in the log file on
-subsequent @code{log_read()} operations. This restricts the set of
-event records read using the returned log file descriptor to those
-which match the query. A query match occurs for a given record when
-that record's facility is a member of the query's facility set and
-the record's severity is greater than or equal to the severity specified
-in the query.
-
-If the value of the @code{query} argument is @code{NULL}, no query filter
-shall be applied.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-POSIX specifies that @code{EINVAL} will be returned if the
-@code{log_facilities} field of the @code{query} argument is not
-a valid facility set. In this implementation, this condition
-can never occur.
-
-Many error codes that POSIX specifies to be returned by @code{log_open()}
-should actually be detected by @code{open()} and passed back by the
-@code{log_open()} implementation. In this implementation, @code{EACCESS},
-@code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT},
-and @code{ENOTDIR} are detected in this manner.
-
-@page
-@subsection log_read - Read from a log file
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_read(
- const logd_t logdes,
- struct log_entry *entry,
- void *log_buf,
- const size_t log_len,
- const size_t *log_sizeread
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_read()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item E2BIG
-This error indicates an inconsistency in the implementation.
-Report this as a bug.
-
-@item EBADF
-The @code{logdes} argument is not a valid log file descriptor.
-
-@item EFAULT
-The @code{entry} argument is not a valid pointer to a log entry structure.
-
-@item EFAULT
-The @code{log_sizeread} argument is not a valid pointer to a size_t.
-
-@item EBUSY
-No data available. There are no unread event records remaining
-in this log file.
-
-@item EINTR
-A signal interrupted the call to @code{log_read()}.
-
-@item EIO
-An I/O error occurred in reading from the event log.
-
-@item EINVAL
-The matching event record has data associated with it and
-@code{log_buf} was not a valid pointer.
-
-@item EINVAL
-The matching event record has data associated with it which is
-longer than @code{log_len}.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_read()} function reads the @code{log_entry}
-structure and up to @code{log_len} bytes of data from the next
-event record of the log file associated with the open log file
-descriptor @code{logdes}. The event record read is placed
-into the @code{log_entry} structure pointed to by
-@code{entry} and any data into the buffer pointed to by @code{log_buf}.
-The log record ID of the returned event record is be stored in the
-@code{log_recid} member of the @code{log_entry} structure for the event
-record.
-
-If the query attribute of the open log file description associated with
-the @code{logdes} is set, the event record read will match that query.
-
-If the @code{log_read()} is successful the call stores the actual length
-of the data associated with the event record into the location specified by
-@code{log_sizeread}. This number will be less than or equal to
-@code{log_len}.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-When @code{EINVAL} is returned, then no data is returned although the
-event record is returned. This is an extension to the POSIX specification.
-
-The POSIX specification specifically allows @code{log_read()} to write
-greater than @code{log_len} bytes into @code{log_buf}. This is highly
-undesirable and this implementation will NOT do this.
-
-@page
-@subsection log_notify - Notify Process of writes to the system log.
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_notify(
- const logd_t logdes,
- const struct sigevent *notification
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_notify()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EBADF
-The logdes argument is not a valid log file descriptor.
-
-@item EINVAL
-The notification argument specifies an invalid signal.
-
-@item EINVAL
-The process has requested a notify on a log that will not be
-written to.
-
-@item ENOSYS
-The function @code{log_notify()} is not supported by this implementation.
-
-@end table
-
-@subheading DESCRIPTION:
-
-If the argument @code{notification} is not @code{NULL} this function registers
-the calling process to be notified of event records received by the system
-log, which match the query parameters associated with the open log descriptor
-specified by @code{logdes}. The notification specified by the
-@code{notification} argument shall be sent to the process when an event
-record received by the system log is matched by the query attribute of the
-open log file description associated with the @code{logdes} log file
-descriptor. If the calling process has already registered a notification
-for the @code{logdes} log file descriptor, the new notification shall
-replace the existing notification registration.
-
-If the @code{notification} argument is @code{NULL} and the calling process is
-currently registered to be notified for the @code{logdes} log file
-descriptor, the existing registration shall be removed.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-@page
-@subsection log_close - Close log descriptor
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_close(
- const logd_t logdes
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_close()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EBADF
-The logdes argument is not a valid log file descriptor.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_close()} function deallocates the open log file descriptor
-indicated by @code{log_des}.
-
-When all log file descriptors associated with an open log file description
-have been closed, the open log file description is freed.
-
-If the link count of the log file is zero, when all log file descriptors
-have been closed, the space occupied by the log file is freed and the
-log file shall no longer be accessible.
-
-If the process has successfully registered a notification request for the
-log file descriptor, the registration is removed.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-@page
-@subsection log_seek - Reposition log file offset
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_seek(
- const logd_t logdes,
- log_recid_t log_recid
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_seek()} returns a value of zero
-and an unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EBADF
-The @code{logdes} argument is not a valid log file descriptor.
-@item EINVAL
-The @code{log_recid} argument is not a valid record id.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_seek()} function sets the log file offset of the open
-log description associated with the @code{logdes} log file descriptor
-to the event record in the log file identified by @code{log_recid}.
-The @code{log_recid} argument is either the record id of a valid event
-record or one of the following values, as defined in the header file
-@code{<evlog.h>:}
-
-@table @b
-@item LOG_SEEK_START
-Set log file position to point at the first event
-record in the log file.
-
-@item LOG_SEEK_END
-Set log file position to point after the last event
-record in the log file.
-
-@end table
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-This implementation can not return EINTR.
-
-This implementation can not return EINVAL to indicate that
-the @code{log_recid} argument is not a valid record id.
-
-@page
-@subsection log_severity_before - Compare event record severities
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_severity_before(
- log_severity_t s1,
- log_severity_t s2
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-@table @b
-@item 0
-The severity of @code{s1} is less than that of @code{s2}.
-
-@item 1
-The severity of @code{s1} is greater than or equal that of @code{s2}.
-
-@item EINVAL
-The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_severity_before()} function compares the severity order
-of the @code{s1} and @code{s2} arguments. If @code{s1} is of
-severity greater than or equal to that of @code{s2}, then this
-function returns 1. Otherwise, it returns 0.
-
-If either @code{s1} or @code{s2} specify invalid severity values, the
-return value of @code{log_severity_before()} is unspecified.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-The POSIX specification of the return value for this function is ambiguous.
-If EINVAL is equal to 1 in an implementation, then the application
-can not distinguish between greater than and an error condition.
-
-@page
-@subsection log_facilityemptyset - Manipulate log facility sets
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_facilityemptyset(
- log_facility_set_t *set
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_facilityemptyset()} returns a value of zero
-and a unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EFAULT
-The @code{set} argument is an invalid pointer.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_facilityemptyset()} function initializes the facility
-set pointed to by the argument @code{set}, such that all facilities
-are excluded.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-Applications shall call either @code{log_facilityemptyset()} or
-@code{log_facilityfillset()} at least once for each object of type
-@code{log_facilityset_t} prior to any other use of that object. If
-such an object is not initialized in this way, but is nonetheless
-supplied as an argument to any of the @code{log_facilityaddset()},
-@code{logfacilitydelset()}, @code{log_facilityismember()} or
-@code{log_open()} functions, the results are undefined.
-
-@page
-@subsection log_facilityfillset - Manipulate log facility sets
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_facilityfillset(
- log_facility_set_t *set
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_facilityfillset()} returns a value of zero
-and a unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EFAULT
-The @code{set} argument is an invalid pointer.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_facilityfillset()} function initializes the facility
-set pointed to by the argument @code{set}, such that all facilities
-are included.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-Applications shall call either @code{log_facilityemptyset()} or
-@code{log_facilityfillset()} at least once for each object of type
-@code{log_facilityset_t} prior to any other use of that object. If
-such an object is not initialized in this way, but is nonetheless
-supplied as an argument to any of the @code{log_facilityaddset()},
-@code{logfacilitydelset()}, @code{log_facilityismember()} or
-@code{log_open()} functions, the results are undefined.
-
-@page
-@subsection log_facilityaddset - Manipulate log facility sets
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_facilityaddset(
- log_facility_set_t *set,
- log_facility_t facilityno
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_facilityaddset()} returns a value of zero
-and a unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EFAULT
-The @code{set} argument is an invalid pointer.
-
-@item EINVAL
-The @code{facilityno} argument is not a valid facility.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_facilityaddset()} function adds the individual
-facility specified by the value of the argument @code{facilityno}
-to the facility set pointed to by the argument @code{set}.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-Applications shall call either @code{log_facilityemptyset()} or
-@code{log_facilityfillset()} at least once for each object of type
-@code{log_facilityset_t} prior to any other use of that object. If
-such an object is not initialized in this way, but is nonetheless
-supplied as an argument to any of the @code{log_facilityaddset()},
-@code{logfacilitydelset()}, @code{log_facilityismember()} or
-@code{log_open()} functions, the results are undefined.
-
-@page
-@subsection log_facilitydelset - Manipulate log facility sets
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_facilitydelset(
- log_facility_set_t *set,
- log_facility_t facilityno
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_facilitydelset()} returns a value of zero
-and a unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EFAULT
-The @code{set} argument is an invalid pointer.
-
-@item EINVAL
-The @code{facilityno} argument is not a valid facility.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_facilitydelset()} function deletes the individual
-facility specified by the value of the argument @code{facilityno}
-from the facility set pointed to by the argument @code{set}.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-Applications shall call either @code{log_facilityemptyset()} or
-@code{log_facilityfillset()} at least once for each object of type
-@code{log_facilityset_t} prior to any other use of that object. If
-such an object is not initialized in this way, but is nonetheless
-supplied as an argument to any of the @code{log_facilityaddset()},
-@code{logfacilitydelset()}, @code{log_facilityismember()} or
-@code{log_open()} functions, the results are undefined.
-
-@page
-@subsection log_facilityismember - Manipulate log facility sets
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_facilityismember(
- const log_facility_set_t *set,
- log_facility_t facilityno,
- const int *member
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_facilityismember()} returns a value
-of zero and a unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EFAULT
-The @code{set} or @code{member} argument is an invalid pointer.
-
-@item EINVAL
-The @code{facilityno} argument is not a valid facility.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_facilityismember()} function tests whether the facility
-specified by the value of the argument @code{facilityno} is a member
-of the set pointed to by the argument @code{set}. Upon successful
-completion, the @code{log_facilityismember()} function either returns
-a value of one to the location specified by @code{member} if the
-specified facility is a member of the specified set or value of
-zero to the location specified by @code{member} if the specified
-facility is not a member of the specified set.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-Applications shall call either @code{log_facilityemptyset()} or
-@code{log_facilityfillset()} at least once for each object of type
-@code{log_facilityset_t} prior to any other use of that object. If
-such an object is not initialized in this way, but is nonetheless
-supplied as an argument to any of the @code{log_facilityaddset()},
-@code{logfacilitydelset()}, @code{log_facilityismember()} or
-@code{log_open()} functions, the results are undefined.
-
-@page
-@subsection log_facilityisvalid - Manipulate log facility sets
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_facilityisvalid(
- log_facility_t facilityno
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A return value of zero indicates that the @code{facilityno} is valid and
-a return value other than zero represents an @code{errno}.
-
-@table @b
-@item EFAULT
-The @code{set} or @code{member} argument is an invalid pointer.
-
-@item EINVAL
-The @code{facilityno} argument is not a valid facility.
-
-@end table
-
-@subheading DESCRIPTION:
-
-The @code{log_facilityisvalid()} function tests whether the facility
-specified by the value of the argument @code{facilityno} is a valid
-facility number. Upon successful completion, the
-the @code{log_facilityisvalid()} function either returns a value of
-0 if the specified facility is a valid facility or value of EINVAL
-if the specified facility is not a valid facility.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-Applications shall call either @code{log_facilityemptyset()} or
-@code{log_facilityfillset()} at least once for each object of type
-@code{log_facilityset_t} prior to any other use of that object. If
-such an object is not initialized in this way, but is nonetheless
-supplied as an argument to any of the @code{log_facilityaddset()},
-@code{logfacilitydelset()}, @code{log_facilityismember()} or
-@code{log_open()} functions, the results are undefined.
-
-@page
-@subsection log_create - Creates a log file
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_create(
- logd_t *ld,
- const char *path,
-);
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_create()} returns a value
-of zero and a unsuccessful call returns the @code{errno}.
-
-@table @b
-
-@item EEXIST
-The @code{path} already exists and O_CREAT and O_EXCL were used.
-
-@item EISDIR
-The @code{path} refers to a directory and the access requested involved
-writing.
-
-@item ETXTBSY
-The @code{path} refers to an executable image which is currently being
-executed and write access was requested.
-
-@item EFAULT
-The @code{path} points outside your accessible address space.
-
-@item EACCES
-The requested access to the file is not allowed, or one of the
-directories in @code{path} did not allow search (execute) permission.
-
-@item ENAMETOOLONG
-The @code{path} was too long.
-
-@item ENOENT
-A directory component in @code{path} does not exist or is a dangling symbolic
-link.
-
-@item ENOTDIR
-A component used as a directory in @code{path} is not, in fact, a directory.
-
-@item EMFILE
-The process already has the maximum number of files open.
-
-@item ENFILE
-The limit on the total number of files open on the system has been reached.
-
-@item ENOMEM
-Insufficient kernel memory was available.
-
-@item EROFS
-The @code{path} refers to a file on a read-only filesystem and write access
-was requested.
-
-@item ELOOP
-The @code{path} contains a reference to a circular symbolic link, ie a
-symbolic link whose expansion contains a reference to itself.
-
-@end table
-
-@subheading DESCRIPTION:
-
-This function attempts to create a file associated with the @code{logdes}
-argument in the directory provided by the argument @code{path}.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.
-
-@page
-@subsection log_sys_create - Creates a system log file
-
-@subheading CALLING SEQUENCE:
-
-@ifset is-C
-@example
-#include <evlog.h>
-
-int log_sys_create();
-@end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
-
-@subheading STATUS CODES:
-
-A successful call to @code{log_sys_create()} returns a value
-of zero and a unsuccessful call returns the @code{errno}.
-
-@table @b
-@item EEXIST
-The directory path to the system log already exist.
-
-@end table
-
-@subheading DESCRIPTION:
-
-This function will create a predefined system log directory path and
-system log file if they do not already exist.
-
-@subheading NOTES:
-
-The @code{_POSIX_LOGGING} feature flag is defined to indicate
-this service is available.