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

4.104.114.84.9
Last change on this file since af5a571 was af5a571, checked in by Joel Sherrill <joel.sherrill@…>, on Aug 27, 1998 at 8:53:21 PM

Updated log_seek() per review.

  • Property mode set to 100644
File size: 21.7 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-1998.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Event Logging Manager
10
11@section Introduction
12
13The event logging manager provides a portable method for logging
14system and application events and subsequent processing of those
15events.  The capabilities in this manager were defined in the POSIX
161003.1h/D3 proposed standard titled @b{Services for Reliable,
17Available, and Serviceable Systems}.
18
19The directives provided by the event logging manager are:
20
21@itemize @bullet
22@item @code{log_write} - Write to the Log
23@item @code{log_open} - Open a log file
24@item @code{log_read} - Read from the system Log
25@item @code{log_notify} - Notify Process of writes to the system log
26@item @code{log_close} - Close log descriptor
27@item @code{log_seek} - Reposition log file offset
28@item @code{log_severity_before} - Compare event record severities
29@item @code{log_facilityemptyset} - Manipulate log facility sets
30@item @code{log_facilityfillset} - Manipulate log facility sets
31@item @code{log_facilityaddset} - Manipulate log facility sets
32@item @code{log_facilitydelset} - Manipulate log facility sets
33@item @code{log_facilityismember} - Manipulate log facility sets
34@end itemize
35
36@section Background
37
38@subsection Log Files and Events
39
40System log
41
42Non-system logs
43
44Events, facility, severity
45
46@subsection Queries
47
48@section Operations
49
50@subsection Creating and Writing a non-System Log
51
52Discuss creating and writing to a non-system log.
53
54@example
55  log_create
56  log_write loop
57@end example
58
59@subsection Reading a Log
60
61Discuss opening and reading from a log.
62
63@example
64  build a query
65  log_open
66  log_read loop
67@end example
68
69@section Directives
70
71This section details the event logging manager's directives.
72A subsection is dedicated to each of this manager's directives
73and describes the calling sequence, related constants, usage,
74and status codes.
75
76@page
77@subsection log_write - Write to the Log
78
79@subheading CALLING SEQUENCE:
80
81@ifset is-C
82@example
83#include <evlog.h>
84
85int log_write(
86  const log_facility_t  facility,
87  const int             event_id,
88  const log_severity_t  severity,
89  const void           *buf,
90  const size_t          len
91);
92@end example
93@end ifset
94
95@ifset is-Ada
96@end ifset
97
98@subheading STATUS CODES:
99
100@table @b
101@item EINVAL
102The facility argument is not a valid log_facility.
103
104@item EINVAL
105The severity argument exceeds @code{LOG_SEVERITY_MAX}
106
107@item EINVAL
108The len argument exceeds @code{LOG_ENTRY_MAXLEN}
109
110@item ENOSPC
111The log file has run out of space on the device.
112
113@item EPERM
114The caller does not have appropriate permission for writing to
115the given facility.
116
117@item EIO
118An I/O error occurred in writing to the system event log.
119
120@end table
121
122@subheading DESCRIPTION:
123
124The @code{log_write} function writes an event record, consisting
125of event attributes, and the data identified by the @code{buf}
126argument, to the system log.  The @code{len} argument specifies
127the length in bytes of the buffer pointed to by @code{buf}.  The
128@code{len} argument shall specify the value of the event record
129length attribute.  The value of @code{len} shall be less than or
130equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
131
132The @code{event_id} argument identifies the type of event record
133being written.  The @code{event_id} argument shall specify the value
134of the event ID attribute of the event record.
135
136The argument @code{facility} indicates the facility from which the
137event type is drawn.  The @code{facility} argument shall specify the
138value of the event record facility attribute.  The value of the
139@code{facility} argument shall be a valid log facility or the
140@code{log_write} function shall fail.
141
142The @code{severity} argument indicates the severity level of the
143event record.  The @code{severity} argument shall specify the value
144of the event record severity attribute.  The value of the
145@code{severity} argument shall be less than or equal to
146@code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
147
148The effective_UID of the calling process shall specify the event
149record UID attribute.  The effective-GID of the calling process
150shall specify the event record GID attribute.  The process ID
151of the calling process shall specify the event record process ID
152attribute.  The process group ID of the calling process shall
153specify the event record process group ID attribute.  The current
154value of the system clock shall specify the event record timestamp
155attribute.
156
157@subheading NOTES:
158
159The @code{_POSIX_LOGGING} feature flag is defined to indicate
160this service is available.
161
162@page
163@subsection log_open - Open a log file
164
165@subheading CALLING SEQUENCE:
166
167@ifset is-C
168@example
169#include <evlog.h>
170
171int log_open(
172  logd_t               *logdes,
173  const char           *path,
174  const log_query_t    *query
175);
176@end example
177@end ifset
178
179@ifset is-Ada
180@end ifset
181
182@subheading STATUS CODES:
183
184@table @b
185@item EACCES
186Search permission is denied on a component of the path prefix,
187or the log file exists and read permission is denied.
188
189@item  EINTR
190A signal interrupted the call to log_open().
191
192@item EINVAL
193The log_severity field of the query argument exceeds
194@code{LOG_SEVERITY_MAX}.
195
196@item EINVAL
197The path argument referred to a file that was not a log file.
198
199@item EMFILE
200Too many log file descriptors are currently in use by this
201process.
202
203@item ENAMETOOLONG
204The length of the path string exceeds @code{PATH_MAX}, or a pathname
205component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
206in effect.
207
208@item ENFILE
209Too many files are currently open in the system.
210
211@item ENOENT
212The file specified by the path argument does not exist.
213
214@item ENOTDIR
215A component of the path prefix is not a directory.
216
217@end table
218
219@subheading DESCRIPTION:
220
221The @code{log_open} function establishes the connection between a
222log file and a log file descriptor.  It creates an open log file
223descriptor that refers to this query stream on the specified log file
224The log file descriptor is used by the other log functions to refer
225to that log query stream.  The @code{path} argument points to a
226pathname for a log file.  A @code{path} argument of NULL specifies
227the current system log file. 
228
229The @code{query} argument is not NULL, then it points to a log query
230specification that is used to filter the records in the log file on
231subsequent @code{log_read} operations.  This restricts the set of
232event records read using the returned log file descriptor to those
233which match the query.  A query match occurs for a given record when
234that record's facility is a member of the query's facility set and
235the record's severity is greater than or equal to the severity specified
236in the query.
237
238If the value of the @code{query} argument is NULL, no query filter
239shall be applied.
240
241@subheading NOTES:
242
243The @code{_POSIX_LOGGING} feature flag is defined to indicate
244this service is available.
245
246POSIX specifies that @code{EINVAL} will be returned if the
247@code{log_facilities} field of the @code{query} argument is not
248a valid facility set.  In this implementation, this condition
249can never occur.
250
251Many error codes that POSIX specifies to be returned by @code{log_open}
252should actually be detected by @code{open} and passed back by the
253@code{log_open} implementation.  In this implementation, @code{EACCESS},
254@code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT},
255and @code{ENOTDIR} are detected in this manner.
256
257@page
258@subsection log_read - Read from the system Log
259
260@subheading CALLING SEQUENCE:
261
262@ifset is-C
263@example
264#include <evlog.h>
265
266int log_read(
267  const logd_t      logdes,
268  struct log_entry *entry,
269  void             *log_buf,
270  const size_t      log_len,
271  const size_t     *log_sizeread
272);
273@end example
274@end ifset
275
276@ifset is-Ada
277@end ifset
278
279@subheading STATUS CODES:
280
281@table @b
282@item EBADF
283The logdes argument is not a valid log file descriptor.
284
285@item EBUSY
286No data available.  The open log file descriptor references
287the current system log.  and there are no unread event records
288remaining.
289
290@item EINTR
291A signal interrupted the call to log_read().
292
293@item EIO
294An I/O error occurred in reading from the event log.
295
296@end table
297
298@subheading DESCRIPTION:
299
300The @code{log_read} function shall attempt to read the @code{log_entry}
301structure and @code{log_len} bytes of data from the next event record
302of the log file associated with the open log file descriptor @code{logdes},
303placing the @code{log_entry} structure into the buffer pointed to by
304@code{entry}, and the data into the buffer pointed to by @code{log_buf}.
305The log record ID of the returned event record shall be stored in the
306@code{log_recid} member of the @code{log_entry} structure for the event
307record.
308
309If the query attribute of the open log file description associated with
310the @code{logdes} is set, the event record read shall match that query.
311If the @code{entry} argument is not NULL it will point to a @code{log_entry}
312structure which shall be filled with the creation information for this log
313entry.  If the argument @code{log_buf} is not NULL the data written with the
314log entry will be placed in the buffer.  The size of the buffer is specified
315by the argument @code{log_len}.
316
317If the @code{log_read} is successful the call shall store the actual length
318of the data associated with the event record into the location specified by
319@code{log_sizeread}.  This number may be smaller or greater than
320@code{log_len}.
321
322@subheading NOTES:
323
324The @code{_POSIX_LOGGING} feature flag is defined to indicate
325this service is available.
326
327@page
328@subsection log_notify - Notify Process of writes to the system log.
329
330@subheading CALLING SEQUENCE:
331
332@ifset is-C
333@example
334#include <evlog.h>
335
336int log_notify(
337  const logd_t           logdes,
338  const struct sigevent *notification
339);
340@end example
341@end ifset
342
343@ifset is-Ada
344@end ifset
345
346@subheading STATUS CODES:
347
348@table @b
349@item EBADF
350The logdes argument is not a valid log file descriptor.
351
352@item EINVAL
353The notification argument specifies an invalid signal.
354
355@item EINVAL
356The process has requested a notify on a log that will not be
357written to.
358
359@item ENOSYS
360The function log_notify() is not supported by this implementation.
361
362@end table
363
364@subheading DESCRIPTION:
365
366If the argument @code{notification} is not NULL this function registers
367the calling process to be notified of event records received by the system
368log, which match the query parameters associated with the open log descriptor
369specified by @code{logdes}.  The notification specified by the
370@code{notification} argument shall be sent to the process when an event
371record received by the system log is matched by the query attribute of the
372open log file description associated with the @code{logdes} log file
373descriptor.  If the calling process has already registered a notification
374for the @code{logdes} log file descriptor, the new notification shall
375replace the existing notification registration.
376
377If the @code{notification} argument is NULL and the calling process is
378currently registered to be notified for the @code{logdes} log file
379descriptor, the existing registration shall be removed.
380
381@subheading NOTES:
382
383The @code{_POSIX_LOGGING} feature flag is defined to indicate
384this service is available.
385
386@page
387@subsection log_close - Close log descriptor
388
389@subheading CALLING SEQUENCE:
390
391@ifset is-C
392@example
393#include <evlog.h>
394
395int log_close(
396  const logd_t   logdes
397);
398@end example
399@end ifset
400
401@ifset is-Ada
402@end ifset
403
404@subheading STATUS CODES:
405
406@table @b
407@item EBADF
408The logdes argument is not a valid log file descriptor.
409
410@end table
411
412@subheading DESCRIPTION:
413
414The @code{log_close} function deallocates the open log file descriptor
415indicated by @code{log_des}.
416
417When all log file descriptors associated with an open log file description
418have been closed, the open log file description shall be freed.
419
420If the link count of the log file is zero, when all log file descriptors
421have been closed, the space occupied by the log file shall be freed and the
422log file shall no longer be accessible.
423
424If the process has successfully registered a notification request for the
425log file descriptor, the registration shall be removed.
426
427@subheading NOTES:
428
429The @code{_POSIX_LOGGING} feature flag is defined to indicate
430this service is available.
431
432@page
433@subsection log_seek - Reposition log file offset
434
435@subheading CALLING SEQUENCE:
436
437@ifset is-C
438@example
439#include <evlog.h>
440
441int log_seek(
442  const logd_t    logdes,
443  log_recid_t     log_recid
444);
445@end example
446@end ifset
447
448@ifset is-Ada
449@end ifset
450
451@subheading STATUS CODES:
452
453@table @b
454@item EBADF
455The @code{logdes} argument is not a valid log file descriptor.
456
457@end table
458
459@subheading DESCRIPTION:
460
461The @code{log_seek} function sets the log file offset of the open
462log description associated with the @code{logdes} log file descriptor
463to the event record in the log file identified by @code{log_recid}. 
464The @code{log_recid} argument is either the record id of a valid event
465record or one of the following values, as defined in the header <evlog.h>:
466
467@table @b
468@item LOG_SEEK_START
469Set log file position to point at the first event
470record in the log file.
471
472@item LOG_SEEK_END
473Set log file position to point after the last event
474record in the log file.
475
476@end table
477
478@subheading NOTES:
479
480The @code{_POSIX_LOGGING} feature flag is defined to indicate
481this service is available.
482
483This implementation can not return @code{EINTR}.
484
485This implementation can not return @code{EINVAL} to indicate that
486the @code{log_recid} argument is not a valid record id.
487
488@page
489@subsection log_severity_before - Compare event record severities
490
491@subheading CALLING SEQUENCE:
492
493@ifset is-C
494@example
495#include <evlog.h>
496
497int log_severity_before(
498  log_severity_t  s1,
499  log_severity_t  s2
500);
501@end example
502@end ifset
503
504@ifset is-Ada
505@end ifset
506
507@subheading STATUS CODES:
508
509@table @b
510@item 0
511The severity of @code{s1} is less than that of @code{s2}.
512
513@item 1
514The severity of @code{s1} is greater than or equal that of @code{s2}.
515
516@item EINVAL
517The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
518
519@end table
520
521@subheading DESCRIPTION:
522
523The @code{log_severity_before} function compares the severity order
524of the @code{s1} and @code{s2} arguments.  If @code{s1} is of
525severity greater than or equal to that of @code{s2}, then this
526function returns 1.  Otherwise, it returns 0.
527
528If either @code{s1} or @code{s2} specify invalid severity values, the
529return value of @code{log_severity_before} is unspecified.
530
531@subheading NOTES:
532
533The @code{_POSIX_LOGGING} feature flag is defined to indicate
534this service is available.
535
536The POSIX specification of the return value for this function is ambiguous.
537If @code{EINVAL} is equal to 1 in an implementation, then the application
538can not distinguish between greater than and an error condition.
539
540@page
541@subsection log_facilityemptyset - Manipulate log facility sets
542
543@subheading CALLING SEQUENCE:
544
545@ifset is-C
546@example
547#include <evlog.h>
548
549int log_facilityemptyset(
550  log_facility_set_t  *set
551);
552@end example
553@end ifset
554
555@ifset is-Ada
556@end ifset
557
558@subheading STATUS CODES:
559
560@table @b
561@item EFAULT
562The @code{set} argument is an invalid pointer.
563
564@end table
565
566@subheading DESCRIPTION:
567
568The @code{log_facilityemptyset} function initializes the facility
569set pointed to by the argument @code{set}, such that all facilities
570are excluded.
571
572@subheading NOTES:
573
574The @code{_POSIX_LOGGING} feature flag is defined to indicate
575this service is available.
576
577Applications shall call either @code{log_facilityemptyset} or
578@code{log_facilityfillset} at least once for each object of type
579@code{log_facilityset_t} prior to any other use of that object.  If
580such an object is not initialized in this way, but is nonetheless
581supplied as an argument to any of the @code{log_facilityaddset},
582@code{logfacilitydelset}, @code{log_facilityismember} or
583@code{log_open} functions, the results are undefined.
584
585@page
586@subsection log_facilityfillset - Manipulate log facility sets
587
588@subheading CALLING SEQUENCE:
589
590@ifset is-C
591@example
592#include <evlog.h>
593
594int log_facilityfillset(
595  log_facility_set_t  *set
596);
597@end example
598@end ifset
599
600@ifset is-Ada
601@end ifset
602
603@subheading STATUS CODES:
604
605@table @b
606@item EFAULT
607The @code{set} argument is an invalid pointer.
608
609@end table
610
611@subheading DESCRIPTION:
612
613The @code{log_facilityfillset} function initializes the facility
614set pointed to by the argument @code{set}, such that all facilities
615are included.
616
617@subheading NOTES:
618
619The @code{_POSIX_LOGGING} feature flag is defined to indicate
620this service is available.
621
622Applications shall call either @code{log_facilityemptyset} or
623@code{log_facilityfillset} at least once for each object of type
624@code{log_facilityset_t} prior to any other use of that object.  If
625such an object is not initialized in this way, but is nonetheless
626supplied as an argument to any of the @code{log_facilityaddset},
627@code{logfacilitydelset}, @code{log_facilityismember} or
628@code{log_open} functions, the results are undefined.
629
630@page
631@subsection log_facilityaddset - Manipulate log facility sets
632
633@subheading CALLING SEQUENCE:
634
635@ifset is-C
636@example
637#include <evlog.h>
638
639int log_facilityaddset(
640  log_facility_set_t  *set,
641  log_facility_t       facilityno
642);
643@end example
644@end ifset
645
646@ifset is-Ada
647@end ifset
648
649@subheading STATUS CODES:
650
651@table @b
652@item EFAULT
653The @code{set} argument is an invalid pointer.
654
655@item EINVAL
656The @code{facilityno} argument is not a valid facility.
657
658@end table
659
660@subheading DESCRIPTION:
661
662The @code{log_facilityaddset} function adds the individual
663facility specified by the value of the argument @code{facilityno}
664to the facility set pointed to by the argument @code{set}.
665
666@subheading NOTES:
667
668The @code{_POSIX_LOGGING} feature flag is defined to indicate
669this service is available.
670
671Applications shall call either @code{log_facilityemptyset} or
672@code{log_facilityfillset} at least once for each object of type
673@code{log_facilityset_t} prior to any other use of that object.  If
674such an object is not initialized in this way, but is nonetheless
675supplied as an argument to any of the @code{log_facilityaddset},
676@code{logfacilitydelset}, @code{log_facilityismember} or
677@code{log_open} functions, the results are undefined.
678
679@page
680@subsection log_facilitydelset - Manipulate log facility sets
681
682@subheading CALLING SEQUENCE:
683
684@ifset is-C
685@example
686#include <evlog.h>
687
688int log_facilitydelset(
689  log_facility_set_t  *set,
690  log_facility_t       facilityno
691);
692@end example
693@end ifset
694
695@ifset is-Ada
696@end ifset
697
698@subheading STATUS CODES:
699
700@table @b
701@item EFAULT
702The @code{set} argument is an invalid pointer.
703
704@item EINVAL
705The @code{facilityno} argument is not a valid facility.
706
707@end table
708
709@subheading DESCRIPTION:
710
711The @code{log_facilitydelset} function deletes the individual
712facility specified by the value of the argument @code{facilityno}
713from the facility set pointed to by the argument @code{set}.
714
715@subheading NOTES:
716
717The @code{_POSIX_LOGGING} feature flag is defined to indicate
718this service is available.
719
720Applications shall call either @code{log_facilityemptyset} or
721@code{log_facilityfillset} at least once for each object of type
722@code{log_facilityset_t} prior to any other use of that object.  If
723such an object is not initialized in this way, but is nonetheless
724supplied as an argument to any of the @code{log_facilityaddset},
725@code{logfacilitydelset}, @code{log_facilityismember} or
726@code{log_open} functions, the results are undefined.
727
728@page
729@subsection log_facilityismember - Manipulate log facility sets
730
731@subheading CALLING SEQUENCE:
732
733@ifset is-C
734@example
735#include <evlog.h>
736
737int log_facilityismember(
738  const log_facility_set_t *set,
739  log_facility_t            facilityno,
740  const int                *member
741);
742@end example
743@end ifset
744
745@ifset is-Ada
746@end ifset
747
748@subheading STATUS CODES:
749
750@table @b
751@item EFAULT
752The @code{set} or @code{member} argument is an invalid pointer.
753
754@item EINVAL
755The @code{facilityno} argument is not a valid facility.
756
757@end table
758
759@subheading DESCRIPTION:
760
761The @code{log_facilityismember} function tests whether the facility
762specified by the value of the argument @code{facilityno} is a member
763of the set pointed to by the argument @code{set}.  Upon successful
764completion, the @code{log_facilityismember} function either returns
765a value of one to the location specified by @code{member} if the
766specified facility is a member of the specified set or value of
767zero to the location specified by @code{member} if the specified
768facility is not a member of the specified set.
769
770@subheading NOTES:
771
772The @code{_POSIX_LOGGING} feature flag is defined to indicate
773this service is available.
774
775Applications shall call either @code{log_facilityemptyset} or
776@code{log_facilityfillset} at least once for each object of type
777@code{log_facilityset_t} prior to any other use of that object.  If
778such an object is not initialized in this way, but is nonetheless
779supplied as an argument to any of the @code{log_facilityaddset},
780@code{logfacilitydelset}, @code{log_facilityismember} or
781@code{log_open} functions, the results are undefined.
782
783@page
784@subsection log_create - Creates a log file
785
786@subheading CALLING SEQUENCE:
787
788@ifset is-C
789@example
790#include <evlog.h>
791
792int log_create(
793  logd_t       *ld,
794  const char   *path,
795);
796@end example
797@end ifset
798
799@ifset is-Ada
800@end ifset
801
802@subheading STATUS CODES:
803
804@table @b
805@item ENOMEM
806The is ????????????
807
808@end table
809
810@subheading DESCRIPTION:
811
812This function dynamically allocates memory for the @code{ld}, associates
813a directory path to the @code{ld}, and provides access permissions to the
814@code{ld}.
815
816@subheading NOTES:
817
818The @code{_POSIX_LOGGING} feature flag is defined to indicate
819this service is available.
820
821@page
822@subsection log_sys_create - Creates a system log file
823
824@subheading CALLING SEQUENCE:
825
826@ifset is-C
827@example
828#include <evlog.h>
829
830int log_sys_create();
831@end example
832@end ifset
833
834@ifset is-Ada
835@end ifset
836
837@subheading STATUS CODES:
838
839@table @b
840@item EEXIST
841The directory path to the system log already exist.
842
843@end table
844
845@subheading DESCRIPTION:
846
847This function will create a predefined system log directory path and
848system log file if they do not already exist.
849
850@subheading NOTES:
851
852The @code{_POSIX_LOGGING} feature flag is defined to indicate
853this service is available.
Note: See TracBrowser for help on using the repository browser.