source: rtems/doc/new_chapters/eventlog.t @ 6520befe

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

Modified log_open() to reflect 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  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 logdes argument is not a valid log file descriptor.
456
457@item EINTR
458The log_seek() function was interrupted by a signal.
459
460@item EINVAL
461The log_recid argument is not a valid record id.
462
463@end table
464
465@subheading DESCRIPTION:
466
467The @code{log_seek} function shall set the log file offset of the open
468log description associated with the @code{logdes} log file descriptor
469to the event record in the log file identified by @code{log_recid}. 
470The @code{log_recid} argument is either the record id of a valid event
471record or one of the following values, as defined in the header <evlog.h>:
472
473@table @b
474@item LOG_SEEK_START
475Set log file position to point at the first event
476record in the log file
477
478@item LOG_SEEK_END
479Set log file position to point after the last event
480record in the log file
481
482@end table
483
484If the @code{log_seek} function is interrupted, the state of the open log
485file description associated with @code{logdes} is unspecified.
486
487@subheading NOTES:
488
489The @code{_POSIX_LOGGING} feature flag is defined to indicate
490this service is available.
491
492@page
493@subsection log_severity_before - Compare event record severities
494
495@subheading CALLING SEQUENCE:
496
497@ifset is-C
498@example
499#include <evlog.h>
500
501int log_severity_before(
502  log_severity_t  s1,
503  log_severity_t  s2
504);
505@end example
506@end ifset
507
508@ifset is-Ada
509@end ifset
510
511@subheading STATUS CODES:
512
513@table @b
514@item 0
515The severity of @code{s1} is less than that of @code{s2}.
516
517@item 1
518The severity of @code{s1} is greater than or equal that of @code{s2}.
519
520@item EINVAL
521The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
522
523@end table
524
525@subheading DESCRIPTION:
526
527The @code{log_severity_before} function compares the severity order
528of the @code{s1} and @code{s2} arguments.  If @code{s1} is of
529severity greater than or equal to that of @code{s2}, then this
530function returns 1.  Otherwise, it returns 0.
531
532If either @code{s1} or @code{s2} specify invalid severity values, the
533return value of @code{log_severity_before} is unspecified.
534
535@subheading NOTES:
536
537The @code{_POSIX_LOGGING} feature flag is defined to indicate
538this service is available.
539
540The POSIX specification of the return value for this function is ambiguous.
541If @code{EINVAL} is equal to 1 in an implementation, then the application
542can not distinguish between greater than and an error condition.
543
544@page
545@subsection log_facilityemptyset - Manipulate log facility sets
546
547@subheading CALLING SEQUENCE:
548
549@ifset is-C
550@example
551#include <evlog.h>
552
553int log_facilityemptyset(
554  log_facility_set_t  *set
555);
556@end example
557@end ifset
558
559@ifset is-Ada
560@end ifset
561
562@subheading STATUS CODES:
563
564@table @b
565@item EFAULT
566The @code{set} argument is an invalid pointer.
567
568@end table
569
570@subheading DESCRIPTION:
571
572The @code{log_facilityemptyset} function initializes the facility
573set pointed to by the argument @code{set}, such that all facilities
574are excluded.
575
576@subheading NOTES:
577
578The @code{_POSIX_LOGGING} feature flag is defined to indicate
579this service is available.
580
581Applications shall call either @code{log_facilityemptyset} or
582@code{log_facilityfillset} at least once for each object of type
583@code{log_facilityset_t} prior to any other use of that object.  If
584such an object is not initialized in this way, but is nonetheless
585supplied as an argument to any of the @code{log_facilityaddset},
586@code{logfacilitydelset}, @code{log_facilityismember} or
587@code{log_open} functions, the results are undefined.
588
589@page
590@subsection log_facilityfillset - Manipulate log facility sets
591
592@subheading CALLING SEQUENCE:
593
594@ifset is-C
595@example
596#include <evlog.h>
597
598int log_facilityfillset(
599  log_facility_set_t  *set
600);
601@end example
602@end ifset
603
604@ifset is-Ada
605@end ifset
606
607@subheading STATUS CODES:
608
609@table @b
610@item EFAULT
611The @code{set} argument is an invalid pointer.
612
613@end table
614
615@subheading DESCRIPTION:
616
617The @code{log_facilityfillset} function initializes the facility
618set pointed to by the argument @code{set}, such that all facilities
619are included.
620
621@subheading NOTES:
622
623The @code{_POSIX_LOGGING} feature flag is defined to indicate
624this service is available.
625
626Applications shall call either @code{log_facilityemptyset} or
627@code{log_facilityfillset} at least once for each object of type
628@code{log_facilityset_t} prior to any other use of that object.  If
629such an object is not initialized in this way, but is nonetheless
630supplied as an argument to any of the @code{log_facilityaddset},
631@code{logfacilitydelset}, @code{log_facilityismember} or
632@code{log_open} functions, the results are undefined.
633
634@page
635@subsection log_facilityaddset - Manipulate log facility sets
636
637@subheading CALLING SEQUENCE:
638
639@ifset is-C
640@example
641#include <evlog.h>
642
643int log_facilityaddset(
644  log_facility_set_t  *set,
645  log_facility_t       facilityno
646);
647@end example
648@end ifset
649
650@ifset is-Ada
651@end ifset
652
653@subheading STATUS CODES:
654
655@table @b
656@item EFAULT
657The @code{set} argument is an invalid pointer.
658
659@item EINVAL
660The @code{facilityno} argument is not a valid facility.
661
662@end table
663
664@subheading DESCRIPTION:
665
666The @code{log_facilityaddset} function adds the individual
667facility specified by the value of the argument @code{facilityno}
668to the facility set pointed to by the argument @code{set}.
669
670@subheading NOTES:
671
672The @code{_POSIX_LOGGING} feature flag is defined to indicate
673this service is available.
674
675Applications shall call either @code{log_facilityemptyset} or
676@code{log_facilityfillset} at least once for each object of type
677@code{log_facilityset_t} prior to any other use of that object.  If
678such an object is not initialized in this way, but is nonetheless
679supplied as an argument to any of the @code{log_facilityaddset},
680@code{logfacilitydelset}, @code{log_facilityismember} or
681@code{log_open} functions, the results are undefined.
682
683@page
684@subsection log_facilitydelset - Manipulate log facility sets
685
686@subheading CALLING SEQUENCE:
687
688@ifset is-C
689@example
690#include <evlog.h>
691
692int log_facilitydelset(
693  log_facility_set_t  *set,
694  log_facility_t       facilityno
695);
696@end example
697@end ifset
698
699@ifset is-Ada
700@end ifset
701
702@subheading STATUS CODES:
703
704@table @b
705@item EFAULT
706The @code{set} argument is an invalid pointer.
707
708@item EINVAL
709The @code{facilityno} argument is not a valid facility.
710
711@end table
712
713@subheading DESCRIPTION:
714
715The @code{log_facilitydelset} function deletes the individual
716facility specified by the value of the argument @code{facilityno}
717from the facility set pointed to by the argument @code{set}.
718
719@subheading NOTES:
720
721The @code{_POSIX_LOGGING} feature flag is defined to indicate
722this service is available.
723
724Applications shall call either @code{log_facilityemptyset} or
725@code{log_facilityfillset} at least once for each object of type
726@code{log_facilityset_t} prior to any other use of that object.  If
727such an object is not initialized in this way, but is nonetheless
728supplied as an argument to any of the @code{log_facilityaddset},
729@code{logfacilitydelset}, @code{log_facilityismember} or
730@code{log_open} functions, the results are undefined.
731
732@page
733@subsection log_facilityismember - Manipulate log facility sets
734
735@subheading CALLING SEQUENCE:
736
737@ifset is-C
738@example
739#include <evlog.h>
740
741int log_facilityismember(
742  const log_facility_set_t *set,
743  log_facility_t            facilityno,
744  const int                *member
745);
746@end example
747@end ifset
748
749@ifset is-Ada
750@end ifset
751
752@subheading STATUS CODES:
753
754@table @b
755@item EFAULT
756The @code{set} or @code{member} argument is an invalid pointer.
757
758@item EINVAL
759The @code{facilityno} argument is not a valid facility.
760
761@end table
762
763@subheading DESCRIPTION:
764
765The @code{log_facilityismember} function tests whether the facility
766specified by the value of the argument @code{facilityno} is a member
767of the set pointed to by the argument @code{set}.  Upon successful
768completion, the @code{log_facilityismember} function either returns
769a value of one to the location specified by @code{member} if the
770specified facility is a member of the specified set or value of
771zero to the location specified by @code{member} if the specified
772facility is not a member of the specified set.
773
774@subheading NOTES:
775
776The @code{_POSIX_LOGGING} feature flag is defined to indicate
777this service is available.
778
779Applications shall call either @code{log_facilityemptyset} or
780@code{log_facilityfillset} at least once for each object of type
781@code{log_facilityset_t} prior to any other use of that object.  If
782such an object is not initialized in this way, but is nonetheless
783supplied as an argument to any of the @code{log_facilityaddset},
784@code{logfacilitydelset}, @code{log_facilityismember} or
785@code{log_open} functions, the results are undefined.
786
787@page
788@subsection log_create - Creates a log file
789
790@subheading CALLING SEQUENCE:
791
792@ifset is-C
793@example
794#include <evlog.h>
795
796int log_create(
797  logd_t       *ld,
798  const char   *path,
799);
800@end example
801@end ifset
802
803@ifset is-Ada
804@end ifset
805
806@subheading STATUS CODES:
807
808@table @b
809@item ENOMEM
810The is ????????????
811
812@end table
813
814@subheading DESCRIPTION:
815
816This function dynamically allocates memory for the @code{ld}, associates
817a directory path to the @code{ld}, and provides access permissions to the
818@code{ld}.
819
820@subheading NOTES:
821
822The @code{_POSIX_LOGGING} feature flag is defined to indicate
823this service is available.
824
825@page
826@subsection log_sys_create - Creates a system log file
827
828@subheading CALLING SEQUENCE:
829
830@ifset is-C
831@example
832#include <evlog.h>
833
834int log_sys_create();
835@end example
836@end ifset
837
838@ifset is-Ada
839@end ifset
840
841@subheading STATUS CODES:
842
843@table @b
844@item EEXIST
845The directory path to the system log already exist.
846
847@end table
848
849@subheading DESCRIPTION:
850
851This function will create a predefined system log directory path and
852system log file if they do not already exist.
853
854@subheading NOTES:
855
856The @code{_POSIX_LOGGING} feature flag is defined to indicate
857this service is available.
Note: See TracBrowser for help on using the repository browser.