mirror of
https://gitlab.rtems.org/rtems/rtos/rtems.git
synced 2025-12-05 15:15:44 +00:00
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
This commit is contained in:
Wade A Smith
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user