From ebc67925f5e5f56a7e9945ce7baffa3b371a8810 Mon Sep 17 00:00:00 2001 From: Wade A Smith Date: Mon, 10 Aug 1998 14:53:01 +0000 Subject: Documented the following Event Logging routines: log_write, log_open, log_read, log_notify, log_close, log_seek, log_severity_before, log_facilityemptyset, log_facilityfillset, log_facilityaddset, log_facilitydelset, and log_facilityismember --- doc/new_chapters/eventlog.t | 220 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 172 insertions(+), 48 deletions(-) (limited to 'doc') diff --git a/doc/new_chapters/eventlog.t b/doc/new_chapters/eventlog.t index de736d7297..d8ee2cc9c2 100644 --- a/doc/new_chapters/eventlog.t +++ b/doc/new_chapters/eventlog.t @@ -16,18 +16,18 @@ event logging manager is ... The directives provided by the event logging manager are: @itemize @bullet -@item @code{log_write} - -@item @code{log_open} - -@item @code{log_read} - -@item @code{log_notify} - -@item @code{log_close} - -@item @code{log_seek} - -@item @code{log_severity_before} - -@item @code{log_facilityemptyset} - -@item @code{log_facilityfillset} - -@item @code{log_facilityaddset} - -@item @code{log_facilitydelset} - -@item @code{log_facilityismember} - +@item @code{log_write} - Write to the Log +@item @code{log_open} - Open a log file +@item @code{log_read} - Read from the system Log +@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 @end itemize @section Background @@ -42,13 +42,18 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@subsection log_write - +@subsection log_write - Write to the Log @subheading CALLING SEQUENCE: @ifset is-C @example 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 @@ -59,23 +64,43 @@ int log_write( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The facility argument is not a valid log_facility. +@item EINVAL +The severity argument exceeds {LOG_SEVERITY_MAX} +@item EINVAL +The len argument exceeds {LOG_ENTRY_MAXLEN} +@item ENOSPC +The log file has run out of space on the device. +@item ENOSYS +The function log_write() is not supported by this implementation. +@item EPERM +The caller does not have appropriate permission for writing to +the given facility. +@item EIO +An I/O error occurred in writing to the system event log. @end table @subheading DESCRIPTION: +The @code{log_write} function writes an event record, consisting +of event attributes, and the data identified by the @code{buf} +argument, to the system log. + @subheading NOTES: @page -@subsection log_open - +@subsection log_open - Open a log file @subheading CALLING SEQUENCE: @ifset is-C @example int log_open( + const logd_t *logdes, + const char *path, + const log_query_t *query ); @end example @end ifset @@ -86,23 +111,57 @@ int log_open( @subheading STATUS CODES: @table @b -@item E -The +@item EACCES +Search permission is denied on a component of the path prefix, +or the log file exists and read permission is denied. +@item EINTR +A signal interrupted the call to log_open(). +@item EINVAL +The log_facility field of the query argument is not a valid +facility set. +@item EINVAL +The log_severity field of the query argument exceeds +{LOG_SEVERITY_MAX}. +@item EINVAL +The 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 {PATH_MAX}, or a pathname +component is longer than {NAME_MAX} while {_POSIX_NO_TRUNC} is +in effect. +@item ENFILE +Too many files are currently open in the system. +@item ENOENT +The file specified by the path argument does not exist. +@item ENOTDIR +A component of the path prefix is not a directory. +@item ENOSYS +The function log_open() is not supported by this implementation. @end table @subheading DESCRIPTION: +The @code{log_open} function establishes the connection between a +log file and a log file descriptor. + @subheading NOTES: @page -@subsection log_read - +@subsection log_read - Read from the system Log @subheading CALLING SEQUENCE: @ifset is-C @example 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 @@ -113,23 +172,36 @@ int log_read( @subheading STATUS CODES: @table @b -@item E -The +@item EBADF +The logdes argument is not a valid log file descriptor. +@item EBUSY +No data available. The open log file descriptor references +the current system log. and there are no unread event records +remaining. +@item EINTR +A signal interrupted the call to log_read(). +@item ENOSYS +The function log_read() is not supported by this implementation. +@item EIO +An I/O error occurred in reading from the event log. @end table @subheading DESCRIPTION: + @subheading NOTES: @page -@subsection log_notify - +@subsection log_notify - Notify Process of writes to the system log. @subheading CALLING SEQUENCE: @ifset is-C @example int log_notify( + const logd_t logdes, + const struct sigevent *notification ); @end example @end ifset @@ -140,8 +212,15 @@ int log_notify( @subheading STATUS CODES: @table @b -@item E -The +@item EBADF +The logdes arfument 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 ENOSY +The function log_notify() is not supported by this implementation. @end table @@ -150,13 +229,14 @@ The @subheading NOTES: @page -@subsection log_close - +@subsection log_close - Close log descriptor @subheading CALLING SEQUENCE: @ifset is-C @example int log_close( + const logd_t logdes ); @end example @end ifset @@ -167,23 +247,30 @@ int log_close( @subheading STATUS CODES: @table @b -@item E -The +@item EBADF +The logdes argument is not a valid log file descriptor. +@item ENOSYS +The function log_close() is not supported by t his implementation. @end table @subheading DESCRIPTION: +The @code{log_close} function deallocates the open log file +descriptor indicated by @code{log_des}. + @subheading NOTES: @page -@subsection log_seek - +@subsection log_seek - Reposition log file offset @subheading CALLING SEQUENCE: @ifset is-C @example int log_seek( + const logd_t logdes, + log_recid_t log_recid ); @end example @end ifset @@ -194,23 +281,35 @@ int log_seek( @subheading STATUS CODES: @table @b -@item E -The +@item EBADF +The logdes argument is not a valid log file descriptor. +@item EINTR +The log_seek() function was interrupted by a signal. +@item EINVAL +The log_recid argument is not a valid record id. +@item ENOSYS +The function log_seek() is not supported by this implementation. @end table @subheading DESCRIPTION: +The @code{log_seek} function shall set the log file offset of the open +log descriptioin associated with the @code{logdes} log file descriptor to the +event record in the log file identified by @code{log_recid}. + @subheading NOTES: @page -@subsection log_severity_before - +@subsection log_severity_before - Compare event record severities @subheading CALLING SEQUENCE: @ifset is-C @example int log_severity_before( + log_severity_t s1, + log_severity_t s2 ); @end example @end ifset @@ -221,23 +320,30 @@ int log_severity_before( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The value of either s1 or s2 exceeds {LOG_SEVERITY_MAX}. +@item ENOSYS +The function log_severity_before() is not supported by this +implementation. @end table @subheading DESCRIPTION: +The @code{log_severity_before} function shall compare the severity order +of the @code{s1} and @code{s2} arguments. + @subheading NOTES: @page -@subsection log_facilityemptyset - +@subsection log_facilityemptyset - Manipulate log facility sets @subheading CALLING SEQUENCE: @ifset is-C @example int log_facilityemptyset( + log_facility_set_t *set ); @end example @end ifset @@ -248,8 +354,10 @@ int log_facilityemptyset( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The facilityno argument is not a valid facility. +@item ENOSYS +The function is not supported by this implementation. @end table @@ -258,13 +366,14 @@ The @subheading NOTES: @page -@subsection log_facilityfillset - +@subsection log_facilityfillset - Manipulate log facility sets @subheading CALLING SEQUENCE: @ifset is-C @example int log_facilityfillset( + log_facility_set_t *set ); @end example @end ifset @@ -275,8 +384,10 @@ int log_facilityfillset( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The facilityno argument is not a valid facility. +@item ENOSYS +The function is not supported by this implementation. @end table @@ -285,13 +396,15 @@ The @subheading NOTES: @page -@subsection log_facilityaddset - +@subsection log_facilityaddset - Manipulate log facility sets @subheading CALLING SEQUENCE: @ifset is-C @example int log_facilityaddset( + log_facility_set_t *set, + log_facility_t facilityno ); @end example @end ifset @@ -302,8 +415,10 @@ int log_facilityaddset( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The facilityno argument is not a valid facility. +@item ENOSYS +The function is not supported by this implementation. @end table @@ -312,13 +427,15 @@ The @subheading NOTES: @page -@subsection log_facilitydelset - +@subsection log_facilitydelset - Manipulate log facility sets @subheading CALLING SEQUENCE: @ifset is-C @example int log_facilitydelset( + log_facility_set_t *set, + log_facility_t facilityno ); @end example @end ifset @@ -329,8 +446,10 @@ int log_facilitydelset( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The facilityno argument is not a valid facility. +@item ENOSYS +The function is not supported by this implementation. @end table @@ -339,13 +458,16 @@ The @subheading NOTES: @page -@subsection log_facilityismember - +@subsection log_facilityismember - Manipulate log facility sets @subheading CALLING SEQUENCE: @ifset is-C @example int log_facilityismember( + const log_facility_set_t *set, + log_facility_t facilityno, + const int *member ); @end example @end ifset @@ -356,8 +478,10 @@ int log_facilityismember( @subheading STATUS CODES: @table @b -@item E -The +@item EINVAL +The facilityno argument is not a valid facility. +@item ENOSYS +The function is not supported by this implementation. @end table -- cgit v1.2.3