source: rtems/doc/new_chapters/eventlog.t @ ebc67925

@c
@c  COPYRIGHT (c) 1988-1998.
@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 is ...

The directives provided by the event logging manager are:

@itemize @bullet
@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

@section Operations

@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 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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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 - 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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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 - 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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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 - 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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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

@subheading DESCRIPTION:

@subheading NOTES:

@page
@subsection log_close - Close log descriptor

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int log_close(
  const logd_t   logdes
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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 - 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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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 - 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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@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 - Manipulate log facility sets

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int log_facilityemptyset(
  log_facility_set_t  *set
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The facilityno argument is not a valid facility.
@item ENOSYS
The function is not supported by this implementation.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The facilityno argument is not a valid facility.
@item ENOSYS
The function is not supported by this implementation.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The facilityno argument is not a valid facility.
@item ENOSYS
The function is not supported by this implementation.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The facilityno argument is not a valid facility.
@item ENOSYS
The function is not supported by this implementation.

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EINVAL
The facilityno argument is not a valid facility.
@item ENOSYS
The function is not supported by this implementation.

@end table

@subheading DESCRIPTION:

@subheading NOTES: