Changeset 566669f5 in rtems


Ignore:
Timestamp:
Aug 28, 1998, 4:48:45 PM (21 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
82db2d3a
Parents:
b67f7946
Message:

Reviewed and corrected log_write(), log_write_any(), and log_write_entry().

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/eventlog.t

    rb67f7946 r566669f5  
    2020
    2121@itemize @bullet
    22 @item @code{log_write} - Write to the Log
     22@item @code{log_write} - Write to the system Log
    2323@item @code{log_write_any} - Write to any log file
     24@item @code{log_write_entry} - Write entry to any log file
    2425@item @code{log_open} - Open a log file
    2526@item @code{log_read} - Read from the system Log
    2627@item @code{log_notify} - Notify Process of writes to the system log
    2728@item @code{log_close} - Close log descriptor
    28 @item @code{log_copy} -
    2929@item @code{log_seek} - Reposition log file offset
    3030@item @code{log_severity_before} - Compare event record severities
     
    7777
    7878@page
    79 @subsection log_write - Write to the Log
     79@subsection log_write - Write to the system Log
    8080
    8181@subheading CALLING SEQUENCE:
     
    101101
    102102@table @b
    103 @item EINVAL
    104 The facility argument is not a valid log_facility.
    105 
    106 @item EINVAL
    107 The severity argument exceeds @code{LOG_SEVERITY_MAX}
    108 
    109 @item EINVAL
    110 The len argument exceeds @code{LOG_ENTRY_MAXLEN}
     103@item E2BIG
     104This error indicates an inconsistency in the implementation.
     105Report this as a bug.
     106
     107@item EINVAL
     108The @code{facility} argument is not a valid log facility.
     109
     110@item EINVAL
     111The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
     112
     113@item EINVAL
     114The @code{len} argument exceeds @code{LOG_MAXIUM_BUFFER_SIZE}.
     115
     116@item EINVAL
     117The @code{len} argument was non-zero and @code{buf} is NULL.
    111118
    112119@item ENOSPC
    113 The log file has run out of space on the device.
    114 
    115 @item EPERM
    116 The caller does not have appropriate permission for writing to
    117 the given facility.
     120The device which contains the log file has run out of space.
    118121
    119122@item EIO
    120 An I/O error occurred in writing to the system event log.
    121 
    122 @end table
    123 
    124 @subheading DESCRIPTION:
    125 
    126 The @code{log_write} function writes an event record, consisting
    127 of event attributes, and the data identified by the @code{buf}
    128 argument, to the system log.  The @code{len} argument specifies
    129 the length in bytes of the buffer pointed to by @code{buf}.  The
    130 @code{len} argument shall specify the value of the event record
    131 length attribute.  The value of @code{len} shall be less than or
    132 equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
    133 
    134 The @code{event_id} argument identifies the type of event record
    135 being written.  The @code{event_id} argument shall specify the value
    136 of the event ID attribute of the event record.
    137 
    138 The argument @code{facility} indicates the facility from which the
    139 event type is drawn.  The @code{facility} argument shall specify the
    140 value of the event record facility attribute.  The value of the
    141 @code{facility} argument shall be a valid log facility or the
    142 @code{log_write} function shall fail.
    143 
    144 The @code{severity} argument indicates the severity level of the
    145 event record.  The @code{severity} argument shall specify the value
    146 of the event record severity attribute.  The value of the
    147 @code{severity} argument shall be less than or equal to
    148 @code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
    149 
    150 The effective_UID of the calling process shall specify the event
    151 record UID attribute.  The effective-GID of the calling process
    152 shall specify the event record GID attribute.  The process ID
    153 of the calling process shall specify the event record process ID
    154 attribute.  The process group ID of the calling process shall
    155 specify the event record process group ID attribute.  The current
    156 value of the system clock shall specify the event record timestamp
    157 attribute.
    158 
    159 @subheading NOTES:
    160 
    161 The @code{_POSIX_LOGGING} feature flag is defined to indicate
    162 this service is available.
     123An I/O error occurred in writing to the log file.
     124
     125@end table
     126
     127@subheading DESCRIPTION:
     128
     129The @code{log_write_any} function writes an event record to the
     130system log file.  The event record written consists of the
     131event attributes specified by the @code{facility}, @code{event_id},
     132and @code{severity} arguments as well as the data identified by the
     133@code{buf} and @code{len} arguments.  The fields of the event record
     134structure to be written are filled in as follows:
     135
     136@table @b
     137@item log_recid
     138This is set to a monotonically increasing log record id
     139maintained by the system for this individual log file.
     140
     141@item log_size
     142This is set to the value of the @code{len} argument.
     143
     144@item log_event_id
     145This is set to the value of the @code{event_id} argument.
     146
     147@item log_facility
     148This is set to the value of the @code{facility} argument.
     149
     150@item log_severity
     151This is set to the value of the @code{severity} argument.
     152
     153@item log_uid
     154This is set to the value returned by @code{geteuid}.
     155
     156@item log_gid
     157This is set to the value returned by @code{getegid}.
     158
     159@item log_pid
     160This is set to the value returned by @code{getpid}.
     161
     162@item log_pgrp
     163This is set to the value returned by @code{getpgrp}.
     164
     165@item log_time
     166This is set to the value returned by @code{clock_gettime} for the
     167CLOCK_REALTIME clock source.
     168
     169@end table
     170
     171@subheading NOTES:
     172
     173The @code{_POSIX_LOGGING} feature flag is defined to indicate
     174this service is available.
     175
     176This implementation can not return the @code{EPERM} error.
    163177
    164178@page
     
    188202
    189203@table @b
    190 @item EINVAL
    191 The facility argument is not a valid log_facility.
    192 
    193 @item EINVAL
    194 The severity argument exceeds @code{LOG_SEVERITY_MAX}
    195 
    196 @item EINVAL
    197 The len argument exceeds @code{LOG_ENTRY_MAXLEN}
     204@item E2BIG
     205This error indicates an inconsistency in the implementation.
     206Report this as a bug.
     207
     208@item EBADF
     209The @code{logdes} argument is not a valid log descriptor.
     210
     211@item EINVAL
     212The @code{facility} argument is not a valid log facility.
     213
     214@item EINVAL
     215The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
     216
     217@item EINVAL
     218The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
     219
     220@item EINVAL
     221The @code{len} argument was non-zero and @code{buf} is NULL.
    198222
    199223@item ENOSPC
    200 The log file has run out of space on the device.
    201 
    202 @item EPERM
    203 The caller does not have appropriate permission for writing to
    204 the given facility.
     224The device which contains the log file has run out of space.
    205225
    206226@item EIO
    207 An I/O error occurred in writing to the system event log.
    208 
    209 @end table
    210 
    211 @subheading DESCRIPTION:
    212 
    213 The @code{log_write} function writes an event record, consisting
    214 of event attributes, and the data identified by the @code{buf}
    215 argument, to a log file.  The @code{len} argument specifies
    216 the length in bytes of the buffer pointed to by @code{buf}.  The
    217 @code{len} argument shall specify the value of the event record
    218 length attribute.  The value of @code{len} shall be less than or
    219 equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
    220 
    221 The @code{event_id} argument identifies the type of event record
    222 being written.  The @code{event_id} argument shall specify the value
    223 of the event ID attribute of the event record.
    224 
    225 The argument @code{facility} indicates the facility from which the
    226 event type is drawn.  The @code{facility} argument shall specify the
    227 value of the event record facility attribute.  The value of the
    228 @code{facility} argument shall be a valid log facility or the
    229 @code{log_write} function shall fail.
    230 
    231 The @code{severity} argument indicates the severity level of the
    232 event record.  The @code{severity} argument shall specify the value
    233 of the event record severity attribute.  The value of the
    234 @code{severity} argument shall be less than or equal to
    235 @code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
    236 
    237 The effective_UID of the calling process shall specify the event
    238 record UID attribute.  The effective-GID of the calling process
    239 shall specify the event record GID attribute.  The process ID
    240 of the calling process shall specify the event record process ID
    241 attribute.  The process group ID of the calling process shall
    242 specify the event record process group ID attribute.  The current
    243 value of the system clock shall specify the event record timestamp
    244 attribute.
    245 
    246 @subheading NOTES:
    247 
    248 The @code{_POSIX_LOGGING} feature flag is defined to indicate
    249 this service is available.
     227An I/O error occurred in writing to the log file.
     228
     229@end table
     230
     231@subheading DESCRIPTION:
     232
     233The @code{log_write_any} function writes an event record to the log file
     234specified by @code{logdes}.  The event record written consists of the
     235event attributes specified by the @code{facility}, @code{event_id},
     236and @code{severity} arguments as well as the data identified by the
     237@code{buf} and @code{len} arguments.  The fields of the event record
     238structure to be written are filled in as follows:
     239
     240@table @b
     241@item log_recid
     242This is set to a monotonically increasing log record id
     243maintained by the system for this individual log file.
     244
     245@item log_size
     246This is set to the value of the @code{len} argument.
     247
     248@item log_event_id
     249This is set to the value of the @code{event_id} argument.
     250
     251@item log_facility
     252This is set to the value of the @code{facility} argument.
     253
     254@item log_severity
     255This is set to the value of the @code{severity} argument.
     256
     257@item log_uid
     258This is set to the value returned by @code{geteuid}.
     259
     260@item log_gid
     261This is set to the value returned by @code{getegid}.
     262
     263@item log_pid
     264This is set to the value returned by @code{getpid}.
     265
     266@item log_pgrp
     267This is set to the value returned by @code{getpgrp}.
     268
     269@item log_time
     270This is set to the value returned by @code{clock_gettime} for the
     271CLOCK_REALTIME clock source.
     272
     273@end table
     274
     275@subheading NOTES:
     276
     277The @code{_POSIX_LOGGING} feature flag is defined to indicate
     278this service is available.
     279
     280This implementation can not return the @code{EPERM} error.
     281
     282This function is not defined in the POSIX specification.  It is
     283an extension provided by this implementation.
     284
     285@page
     286@subsection log_write_entry - Write entry to any log file
     287
     288@subheading CALLING SEQUENCE:
     289
     290@ifset is-C
     291@example
     292#include <evlog.h>
     293
     294int log_write_entry(
     295  const logd_t      logdes,
     296  struct log_entry *entry,
     297  const void       *buf,
     298  const size_t      len
     299);
     300@end example
     301@end ifset
     302 
     303@ifset is-Ada
     304@end ifset
     305
     306@subheading STATUS CODES:
     307
     308@table @b
     309@item E2BIG
     310This error indicates an inconsistency in the implementation.
     311Report this as a bug.
     312
     313@item EBADF
     314The @code{logdes} argument is not a valid log descriptor.
     315
     316@item EFAULT
     317The @code{entry} argument is not a valid pointer to a log entry.
     318
     319@item EINVAL
     320The @code{facility} field in @code{entry} is not a valid log facility.
     321
     322@item EINVAL
     323The @code{severity} field in @code{entry} exceeds @code{LOG_SEVERITY_MAX}.
     324
     325@item EINVAL
     326The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
     327
     328@item EINVAL
     329The @code{len} argument was non-zero and @code{buf} is NULL.
     330
     331@item ENOSPC
     332The device which contains the log file has run out of space.
     333
     334@item EIO
     335An I/O error occurred in writing to the log file.
     336
     337@end table
     338
     339@subheading DESCRIPTION:
     340
     341The @code{log_write_entry} function writes an event record
     342specified by the @code{entry}, @code{buf}, and @code{len} arguments.
     343Most of the fields of the event record pointed to by @code{entry}
     344are left intact.  The following fields are filled in as follows:
     345
     346@table @b
     347@item log_recid
     348This is set to a monotonically increasing log record id
     349maintained by the system for this individual log file.
     350
     351@item log_size
     352This is set to the value of the @code{len} argument.
     353
     354@end table
     355
     356This allows existing log entries from one log file to be written to
     357another log file without destroying the logged information.
     358
     359@subheading NOTES:
     360
     361The @code{_POSIX_LOGGING} feature flag is defined to indicate
     362this service is available.
     363
     364This implementation can not return the @code{EPERM} error.
     365
     366This function is not defined in the POSIX specification.  It is
     367an extension provided by this implementation.
    250368
    251369@page
Note: See TracChangeset for help on using the changeset viewer.