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

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

Corrected descriptions of log facility set manipulation routines as
part of the review.

  • Property mode set to 100644
File size: 21.8 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  const 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_facility field of the query argument is not a valid
194facility set.
195
196@item EINVAL
197The log_severity field of the query argument exceeds
198@code{LOG_SEVERITY_MAX}.
199
200@item EINVAL
201The path argument referred to a file that was not a log file.
202
203@item EMFILE
204Too many log file descriptors are currently in use by this
205process.
206
207@item ENAMETOOLONG
208The length of the path string exceeds @code{PATH_MAX}, or a pathname
209component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
210in effect.
211
212@item ENFILE
213Too many files are currently open in the system.
214
215@item ENOENT
216The file specified by the path argument does not exist.
217
218@item ENOTDIR
219A component of the path prefix is not a directory.
220
221@end table
222
223@subheading DESCRIPTION:
224
225The @code{log_open} function establishes the connection between a
226log file and a log file descriptor.  It creates an open log file
227description that refers to a log file and a log file descriptor that
228refers to that open log file description.  The log file descriptor is
229used by other log functions to refer to that log file.  The @code{path}
230argument points to a pathname naming a log file.  A @code{path}
231argument of NULL specifies the current system log file. 
232
233The @code{query} argument points to a log query specification that
234restricts log operations using the returned log file descriptor to
235to event records from the log file which match the query.  The
236predicate which determines the success of the match operation is the
237logical AND of the individual comparison predicates for each member
238of the log query specification.  The query attribute of the open file
239description is set to filter as specified by the @code{query} argument.
240If the value of the query argument is not NULL, the value of the
241@code{log_facility} member of the @code{query} specification shall be
242a set of valid log facilities or the @code{log_open} shall fail.  If
243the value of the @code{query} argument is not NULL, the value of the
244@code{log_severity} member of the @code{query} specification shall be
245less than or equal to @code{LOG_SEVERITY_MAX} or the @code{log_open}
246shall fail.  If the value of the @code{query} argument is NULL, no
247query filter shall be applied.
248
249@subheading NOTES:
250
251The @code{_POSIX_LOGGING} feature flag is defined to indicate
252this service is available.
253
254@page
255@subsection log_read - Read from the system Log
256
257@subheading CALLING SEQUENCE:
258
259@ifset is-C
260@example
261#include <evlog.h>
262
263int log_read(
264  const logd_t logdes,
265  struct log_entry *entry,
266  void             *log_buf,
267  const size_t      log_len,
268  const size_t     *log_sizeread
269);
270@end example
271@end ifset
272
273@ifset is-Ada
274@end ifset
275
276@subheading STATUS CODES:
277
278@table @b
279@item EBADF
280The logdes argument is not a valid log file descriptor.
281
282@item EBUSY
283No data available.  The open log file descriptor references
284the current system log.  and there are no unread event records
285remaining.
286
287@item EINTR
288A signal interrupted the call to log_read().
289
290@item EIO
291An I/O error occurred in reading from the event log.
292
293@end table
294
295@subheading DESCRIPTION:
296
297The @code{log_read} function shall attempt to read the @code{log_entry}
298structure and @code{log_len} bytes of data from the next event record
299of the log file associated with the open log file descriptor @code{logdes},
300placing the @code{log_entry} structure into the buffer pointed to by
301@code{entry}, and the data into the buffer pointed to by @code{log_buf}.
302The log record ID of the returned event record shall be stored in the
303@code{log_recid} member of the @code{log_entry} structure for the event
304record.
305
306If the query attribute of the open log file description associated with
307the @code{logdes} is set, the event record read shall match that query.
308If the @code{entry} argument is not NULL it will point to a @code{log_entry}
309structure which shall be filled with the creation information for this log
310entry.  If the argument @code{log_buf} is not NULL the data written with the
311log entry will be placed in the buffer.  The size of the buffer is specified
312by the argument @code{log_len}.
313
314If the @code{log_read} is successful the call shall store the actual length
315of the data associated with the event record into the location specified by
316@code{log_sizeread}.  This number may be smaller or greater than
317@code{log_len}.
318
319@subheading NOTES:
320
321The @code{_POSIX_LOGGING} feature flag is defined to indicate
322this service is available.
323
324@page
325@subsection log_notify - Notify Process of writes to the system log.
326
327@subheading CALLING SEQUENCE:
328
329@ifset is-C
330@example
331#include <evlog.h>
332
333int log_notify(
334  const logd_t           logdes,
335  const struct sigevent *notification
336);
337@end example
338@end ifset
339
340@ifset is-Ada
341@end ifset
342
343@subheading STATUS CODES:
344
345@table @b
346@item EBADF
347The logdes argument is not a valid log file descriptor.
348
349@item EINVAL
350The notification argument specifies an invalid signal.
351
352@item EINVAL
353The process has requested a notify on a log that will not be
354written to.
355
356@item ENOSYS
357The function log_notify() is not supported by this implementation.
358
359@end table
360
361@subheading DESCRIPTION:
362
363If the argument @code{notification} is not NULL this function registers
364the calling process to be notified of event records received by the system
365log, which match the query parameters associated with the open log descriptor
366specified by @code{logdes}.  The notification specified by the
367@code{notification} argument shall be sent to the process when an event
368record received by the system log is matched by the query attribute of the
369open log file description associated with the @code{logdes} log file
370descriptor.  If the calling process has already registered a notification
371for the @code{logdes} log file descriptor, the new notification shall
372replace the existing notification registration.
373
374If the @code{notification} argument is NULL and the calling process is
375currently registered to be notified for the @code{logdes} log file
376descriptor, the existing registration shall be removed.
377
378@subheading NOTES:
379
380The @code{_POSIX_LOGGING} feature flag is defined to indicate
381this service is available.
382
383@page
384@subsection log_close - Close log descriptor
385
386@subheading CALLING SEQUENCE:
387
388@ifset is-C
389@example
390#include <evlog.h>
391
392int log_close(
393  const logd_t   logdes
394);
395@end example
396@end ifset
397
398@ifset is-Ada
399@end ifset
400
401@subheading STATUS CODES:
402
403@table @b
404@item EBADF
405The logdes argument is not a valid log file descriptor.
406
407@end table
408
409@subheading DESCRIPTION:
410
411The @code{log_close} function deallocates the open log file descriptor
412indicated by @code{log_des}.
413
414When all log file descriptors associated with an open log file description
415have been closed, the open log file description shall be freed.
416
417If the link count of the log file is zero, when all log file descriptors
418have been closed, the space occupied by the log file shall be freed and the
419log file shall no longer be accessible.
420
421If the process has successfully registered a notification request for the
422log file descriptor, the registration shall be removed.
423
424@subheading NOTES:
425
426The @code{_POSIX_LOGGING} feature flag is defined to indicate
427this service is available.
428
429@page
430@subsection log_seek - Reposition log file offset
431
432@subheading CALLING SEQUENCE:
433
434@ifset is-C
435@example
436#include <evlog.h>
437
438int log_seek(
439  const logd_t    logdes,
440  log_recid_t     log_recid
441);
442@end example
443@end ifset
444
445@ifset is-Ada
446@end ifset
447
448@subheading STATUS CODES:
449
450@table @b
451@item EBADF
452The logdes argument is not a valid log file descriptor.
453
454@item EINTR
455The log_seek() function was interrupted by a signal.
456
457@item EINVAL
458The log_recid argument is not a valid record id.
459
460@end table
461
462@subheading DESCRIPTION:
463
464The @code{log_seek} function shall set the log file offset of the open
465log description associated with the @code{logdes} log file descriptor
466to the event record in the log file identified by @code{log_recid}. 
467The @code{log_recid} argument is either the record id of a valid event
468record or one of the following values, as defined in the header <evlog.h>:
469
470@table @b
471@item LOG_SEEK_START
472Set log file position to point at the first event
473record in the log file
474
475@item LOG_SEEK_END
476Set log file position to point after the last event
477record in the log file
478
479@end table
480
481If the @code{log_seek} function is interrupted, the state of the open log
482file description associated with @code{logdes} is unspecified.
483
484@subheading NOTES:
485
486The @code{_POSIX_LOGGING} feature flag is defined to indicate
487this service is available.
488
489@page
490@subsection log_severity_before - Compare event record severities
491
492@subheading CALLING SEQUENCE:
493
494@ifset is-C
495@example
496#include <evlog.h>
497
498int log_severity_before(
499  log_severity_t  s1,
500  log_severity_t  s2
501);
502@end example
503@end ifset
504
505@ifset is-Ada
506@end ifset
507
508@subheading STATUS CODES:
509
510@table @b
511@item 0
512The severity of @code{s1} is less than that of @code{s2}.
513
514@item 1
515The severity of @code{s1} is greater than or equal that of @code{s2}.
516
517@item EINVAL
518The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
519
520@end table
521
522@subheading DESCRIPTION:
523
524The @code{log_severity_before} function compares the severity order
525of the @code{s1} and @code{s2} arguments.  If @code{s1} is of
526severity greater than or equal to that of @code{s2}, then this
527function returns 1.  Otherwise, it returns 0.
528
529If either @code{s1} or @code{s2} specify invalid severity values, the
530return value of @code{log_severity_before} is unspecified.
531
532@subheading NOTES:
533
534The @code{_POSIX_LOGGING} feature flag is defined to indicate
535this service is available.
536
537The POSIX specification of the return value for this function is ambiguous.
538If @code{EINVAL} is equal to 1 in an implementation, then the application
539can not distinguish between greater than and an error condition.
540
541@page
542@subsection log_facilityemptyset - Manipulate log facility sets
543
544@subheading CALLING SEQUENCE:
545
546@ifset is-C
547@example
548#include <evlog.h>
549
550int log_facilityemptyset(
551  log_facility_set_t  *set
552);
553@end example
554@end ifset
555
556@ifset is-Ada
557@end ifset
558
559@subheading STATUS CODES:
560
561@table @b
562@item EFAULT
563The @code{set} argument is an invalid pointer.
564
565@end table
566
567@subheading DESCRIPTION:
568
569The @code{log_facilityemptyset} function initializes the facility
570set pointed to by the argument @code{set}, such that all facilities
571are excluded.
572
573@subheading NOTES:
574
575The @code{_POSIX_LOGGING} feature flag is defined to indicate
576this service is available.
577
578Applications shall call either @code{log_facilityemptyset} or
579@code{log_facilityfillset} at least once for each object of type
580@code{log_facilityset_t} prior to any other use of that object.  If
581such an object is not initialized in this way, but is nonetheless
582supplied as an argument to any of the @code{log_facilityaddset},
583@code{logfacilitydelset}, @code{log_facilityismember} or
584@code{log_open} functions, the results are undefined.
585
586@page
587@subsection log_facilityfillset - Manipulate log facility sets
588
589@subheading CALLING SEQUENCE:
590
591@ifset is-C
592@example
593#include <evlog.h>
594
595int log_facilityfillset(
596  log_facility_set_t  *set
597);
598@end example
599@end ifset
600
601@ifset is-Ada
602@end ifset
603
604@subheading STATUS CODES:
605
606@table @b
607@item EFAULT
608The @code{set} argument is an invalid pointer.
609
610@end table
611
612@subheading DESCRIPTION:
613
614The @code{log_facilityfillset} function initializes the facility
615set pointed to by the argument @code{set}, such that all facilities
616are included.
617
618@subheading NOTES:
619
620The @code{_POSIX_LOGGING} feature flag is defined to indicate
621this service is available.
622
623Applications shall call either @code{log_facilityemptyset} or
624@code{log_facilityfillset} at least once for each object of type
625@code{log_facilityset_t} prior to any other use of that object.  If
626such an object is not initialized in this way, but is nonetheless
627supplied as an argument to any of the @code{log_facilityaddset},
628@code{logfacilitydelset}, @code{log_facilityismember} or
629@code{log_open} functions, the results are undefined.
630
631@page
632@subsection log_facilityaddset - Manipulate log facility sets
633
634@subheading CALLING SEQUENCE:
635
636@ifset is-C
637@example
638#include <evlog.h>
639
640int log_facilityaddset(
641  log_facility_set_t  *set,
642  log_facility_t       facilityno
643);
644@end example
645@end ifset
646
647@ifset is-Ada
648@end ifset
649
650@subheading STATUS CODES:
651
652@table @b
653@item EFAULT
654The @code{set} argument is an invalid pointer.
655
656@item EINVAL
657The @code{facilityno} argument is not a valid facility.
658
659@end table
660
661@subheading DESCRIPTION:
662
663The @code{log_facilityaddset} function adds the individual
664facility specified by the value of the argument @code{facilityno}
665to the facility set pointed to by the argument @code{set}.
666
667@subheading NOTES:
668
669The @code{_POSIX_LOGGING} feature flag is defined to indicate
670this service is available.
671
672Applications shall call either @code{log_facilityemptyset} or
673@code{log_facilityfillset} at least once for each object of type
674@code{log_facilityset_t} prior to any other use of that object.  If
675such an object is not initialized in this way, but is nonetheless
676supplied as an argument to any of the @code{log_facilityaddset},
677@code{logfacilitydelset}, @code{log_facilityismember} or
678@code{log_open} functions, the results are undefined.
679
680@page
681@subsection log_facilitydelset - Manipulate log facility sets
682
683@subheading CALLING SEQUENCE:
684
685@ifset is-C
686@example
687#include <evlog.h>
688
689int log_facilitydelset(
690  log_facility_set_t  *set,
691  log_facility_t       facilityno
692);
693@end example
694@end ifset
695
696@ifset is-Ada
697@end ifset
698
699@subheading STATUS CODES:
700
701@table @b
702@item EFAULT
703The @code{set} argument is an invalid pointer.
704
705@item EINVAL
706The @code{facilityno} argument is not a valid facility.
707
708@end table
709
710@subheading DESCRIPTION:
711
712The @code{log_facilitydelset} function deletes the individual
713facility specified by the value of the argument @code{facilityno}
714from the facility set pointed to by the argument @code{set}.
715
716@subheading NOTES:
717
718The @code{_POSIX_LOGGING} feature flag is defined to indicate
719this service is available.
720
721Applications shall call either @code{log_facilityemptyset} or
722@code{log_facilityfillset} at least once for each object of type
723@code{log_facilityset_t} prior to any other use of that object.  If
724such an object is not initialized in this way, but is nonetheless
725supplied as an argument to any of the @code{log_facilityaddset},
726@code{logfacilitydelset}, @code{log_facilityismember} or
727@code{log_open} functions, the results are undefined.
728
729@page
730@subsection log_facilityismember - Manipulate log facility sets
731
732@subheading CALLING SEQUENCE:
733
734@ifset is-C
735@example
736#include <evlog.h>
737
738int log_facilityismember(
739  const log_facility_set_t *set,
740  log_facility_t            facilityno,
741  const int                *member
742);
743@end example
744@end ifset
745
746@ifset is-Ada
747@end ifset
748
749@subheading STATUS CODES:
750
751@table @b
752@item EFAULT
753The @code{set} or @code{member} argument is an invalid pointer.
754
755@item EINVAL
756The @code{facilityno} argument is not a valid facility.
757
758@end table
759
760@subheading DESCRIPTION:
761
762The @code{log_facilityismember} function tests whether the facility
763specified by the value of the argument @code{facilityno} is a member
764of the set pointed to by the argument @code{set}.  Upon successful
765completion, the @code{log_facilityismember} function either returns
766a value of one to the location specified by @code{member} if the
767specified facility is a member of the specified set or value of
768zero to the location specified by @code{member} if the specified
769facility is not a member of the specified set.
770
771@subheading NOTES:
772
773The @code{_POSIX_LOGGING} feature flag is defined to indicate
774this service is available.
775
776Applications shall call either @code{log_facilityemptyset} or
777@code{log_facilityfillset} at least once for each object of type
778@code{log_facilityset_t} prior to any other use of that object.  If
779such an object is not initialized in this way, but is nonetheless
780supplied as an argument to any of the @code{log_facilityaddset},
781@code{logfacilitydelset}, @code{log_facilityismember} or
782@code{log_open} functions, the results are undefined.
783
784@page
785@subsection log_create - Creates a log file
786
787@subheading CALLING SEQUENCE:
788
789@ifset is-C
790@example
791#include <evlog.h>
792
793int log_create(
794  logd_t       *ld,
795  const char   *path,
796);
797@end example
798@end ifset
799
800@ifset is-Ada
801@end ifset
802
803@subheading STATUS CODES:
804
805@table @b
806@item ENOMEM
807The is ????????????
808
809@end table
810
811@subheading DESCRIPTION:
812
813This function dynamically allocates memory for the @code{ld}, associates
814a directory path to the @code{ld}, and provides access permissions to the
815@code{ld}.
816
817@subheading NOTES:
818
819The @code{_POSIX_LOGGING} feature flag is defined to indicate
820this service is available.
821
822@page
823@subsection log_sys_create - Creates a system log file
824
825@subheading CALLING SEQUENCE:
826
827@ifset is-C
828@example
829#include <evlog.h>
830
831int log_sys_create();
832@end example
833@end ifset
834
835@ifset is-Ada
836@end ifset
837
838@subheading STATUS CODES:
839
840@table @b
841@item EEXIST
842The directory path to the system log already exist.
843
844@end table
845
846@subheading DESCRIPTION:
847
848This function will create a predefined system log directory path and
849system log file if they do not already exist.
850
851@subheading NOTES:
852
853The @code{_POSIX_LOGGING} feature flag is defined to indicate
854this service is available.
Note: See TracBrowser for help on using the repository browser.