source: rtems/doc/new_chapters/eventlog.t @ 251f8b1

4.104.114.84.95
Last change on this file since 251f8b1 was 251f8b1, checked in by Jennifer Averett <Jennifer.Averett@…>, on 09/02/98 at 14:22:40

Added text to describe System log, Non-system logs,facility, and severity.

  • Property mode set to 100644
File size: 28.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_create} - Create a log file
23@item @code{log_sys_create} - Create a system log file
24@item @code{log_write} - Write to the system Log
25@item @code{log_write_any} - Write to any log file
26@item @code{log_write_entry} - Write entry to any log file
27@item @code{log_open} - Open a log file
28@item @code{log_read} - Read from a log file
29@item @code{log_notify} - Notify Process of writes to the system log
30@item @code{log_close} - Close log descriptor
31@item @code{log_seek} - Reposition log file offset
32@item @code{log_severity_before} - Compare event record severities
33@item @code{log_facilityemptyset} - Manipulate log facility sets
34@item @code{log_facilityfillset} - Manipulate log facility sets
35@item @code{log_facilityaddset} - Manipulate log facility sets
36@item @code{log_facilitydelset} - Manipulate log facility sets
37@item @code{log_facilityismember} - Manipulate log facility sets
38@end itemize
39
40@section Background
41
42@subsection Log Files and Events
43
44The operating system uses a special log file named @code{XXX}. 
45This log file is called the system log and is automatically created and
46tracked by the operating system.  The system log is written to with
47the @code{log_write} function.  An alternative log file may be written
48using the @code{log_write_any} function.  It is possible to use @code{log_read}
49to query the system and @code{log_write_entry} to a non-system log file
50to produce a filtered version of the system log.  For example you could
51produce a log of all disk controller faults that have occurred. 
52
53A non-system log may be a special log file created by an application to
54describe application faults, or a subset of the system log created
55by the application. 
56
57A facility is an identification code for a subsystem, device, or
58other object about which information is being written to
59a log file.  Severity is a rating of the error that is being logged.   
60The facility identifier and the event severity are the basis for
61subsequent log query.  A log query is used as a filter to
62obtain a subset of a given log file.  The log file may be configured
63to send out an event ... ???
64
65XXX Events
66
67@subsection Queries
68
69@section Operations
70
71@subsection Creating and Writing a non-System Log
72
73Discuss creating and writing to a non-system log.
74
75@example
76  log_create
77  log_write loop
78@end example
79
80@subsection Reading a Log
81
82Discuss opening and reading from a log.
83
84@example
85  build a query
86  log_open
87  log_read loop
88@end example
89
90@section Directives
91
92This section details the event logging manager's directives.
93A subsection is dedicated to each of this manager's directives
94and describes the calling sequence, related constants, usage,
95and status codes.
96
97@page
98@subsection log_write - Write to the system Log
99
100@subheading CALLING SEQUENCE:
101
102@ifset is-C
103@example
104#include <evlog.h>
105
106int log_write(
107  const log_facility_t  facility,
108  const int             event_id,
109  const log_severity_t  severity,
110  const void           *buf,
111  const size_t          len
112);
113@end example
114@end ifset
115
116@ifset is-Ada
117@end ifset
118
119@subheading STATUS CODES:
120
121@table @b
122@item E2BIG
123This error indicates an inconsistency in the implementation.
124Report this as a bug.
125
126@item EINVAL
127The @code{facility} argument is not a valid log facility.
128
129@item EINVAL
130The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
131
132@item EINVAL
133The @code{len} argument exceeds @code{LOG_MAXIUM_BUFFER_SIZE}.
134
135@item EINVAL
136The @code{len} argument was non-zero and @code{buf} is NULL.
137
138@item ENOSPC
139The device which contains the log file has run out of space.
140
141@item EIO
142An I/O error occurred in writing to the log file.
143
144@end table
145
146@subheading DESCRIPTION:
147
148The @code{log_write_any} function writes an event record to the
149system log file.  The event record written consists of the
150event attributes specified by the @code{facility}, @code{event_id},
151and @code{severity} arguments as well as the data identified by the
152@code{buf} and @code{len} arguments.  The fields of the event record
153structure to be written are filled in as follows:
154
155@table @b
156@item log_recid
157This is set to a monotonically increasing log record id
158maintained by the system for this individual log file.
159
160@item log_size
161This is set to the value of the @code{len} argument.
162
163@item log_event_id
164This is set to the value of the @code{event_id} argument.
165
166@item log_facility
167This is set to the value of the @code{facility} argument.
168
169@item log_severity
170This is set to the value of the @code{severity} argument.
171
172@item log_uid
173This is set to the value returned by @code{geteuid}.
174
175@item log_gid
176This is set to the value returned by @code{getegid}.
177
178@item log_pid
179This is set to the value returned by @code{getpid}.
180
181@item log_pgrp
182This is set to the value returned by @code{getpgrp}.
183
184@item log_time
185This is set to the value returned by @code{clock_gettime} for the
186CLOCK_REALTIME clock source.
187
188@end table
189
190@subheading NOTES:
191
192The @code{_POSIX_LOGGING} feature flag is defined to indicate
193this service is available.
194
195This implementation can not return the @code{EPERM} error.
196
197@page
198@subsection log_write_any - Write to the any log file
199
200@subheading CALLING SEQUENCE:
201
202@ifset is-C
203@example
204#include <evlog.h>
205
206int log_write_any(
207  const logd_t          logdes,
208  const log_facility_t  facility,
209  const int             event_id,
210  const log_severity_t  severity,
211  const void           *buf,
212  const size_t          len
213);
214@end example
215@end ifset
216 
217@ifset is-Ada
218@end ifset
219
220@subheading STATUS CODES:
221
222@table @b
223@item E2BIG
224This error indicates an inconsistency in the implementation.
225Report this as a bug.
226
227@item EBADF
228The @code{logdes} argument is not a valid log descriptor.
229
230@item EINVAL
231The @code{facility} argument is not a valid log facility.
232
233@item EINVAL
234The @code{severity} argument exceeds @code{LOG_SEVERITY_MAX}.
235
236@item EINVAL
237The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
238
239@item EINVAL
240The @code{len} argument was non-zero and @code{buf} is NULL.
241
242@item ENOSPC
243The device which contains the log file has run out of space.
244
245@item EIO
246An I/O error occurred in writing to the log file.
247
248@end table
249
250@subheading DESCRIPTION:
251
252The @code{log_write_any} function writes an event record to the log file
253specified by @code{logdes}.  The event record written consists of the
254event attributes specified by the @code{facility}, @code{event_id},
255and @code{severity} arguments as well as the data identified by the
256@code{buf} and @code{len} arguments.  The fields of the event record
257structure to be written are filled in as follows:
258
259@table @b
260@item log_recid
261This is set to a monotonically increasing log record id
262maintained by the system for this individual log file.
263
264@item log_size
265This is set to the value of the @code{len} argument.
266
267@item log_event_id
268This is set to the value of the @code{event_id} argument.
269
270@item log_facility
271This is set to the value of the @code{facility} argument.
272
273@item log_severity
274This is set to the value of the @code{severity} argument.
275
276@item log_uid
277This is set to the value returned by @code{geteuid}.
278
279@item log_gid
280This is set to the value returned by @code{getegid}.
281
282@item log_pid
283This is set to the value returned by @code{getpid}.
284
285@item log_pgrp
286This is set to the value returned by @code{getpgrp}.
287
288@item log_time
289This is set to the value returned by @code{clock_gettime} for the
290CLOCK_REALTIME clock source.
291
292@end table
293
294@subheading NOTES:
295
296The @code{_POSIX_LOGGING} feature flag is defined to indicate
297this service is available.
298
299This implementation can not return the @code{EPERM} error.
300
301This function is not defined in the POSIX specification.  It is
302an extension provided by this implementation.
303
304@page
305@subsection log_write_entry - Write entry to any log file
306
307@subheading CALLING SEQUENCE:
308
309@ifset is-C
310@example
311#include <evlog.h>
312
313int log_write_entry(
314  const logd_t      logdes,
315  struct log_entry *entry,
316  const void       *buf,
317  const size_t      len
318);
319@end example
320@end ifset
321 
322@ifset is-Ada
323@end ifset
324
325@subheading STATUS CODES:
326
327@table @b
328@item E2BIG
329This error indicates an inconsistency in the implementation.
330Report this as a bug.
331
332@item EBADF
333The @code{logdes} argument is not a valid log descriptor.
334
335@item EFAULT
336The @code{entry} argument is not a valid pointer to a log entry.
337
338@item EINVAL
339The @code{facility} field in @code{entry} is not a valid log facility.
340
341@item EINVAL
342The @code{severity} field in @code{entry} exceeds @code{LOG_SEVERITY_MAX}.
343
344@item EINVAL
345The @code{len} argument exceeds @code{LOG_MAXIMUM_BUFFER_SIZE}.
346
347@item EINVAL
348The @code{len} argument was non-zero and @code{buf} is NULL.
349
350@item ENOSPC
351The device which contains the log file has run out of space.
352
353@item EIO
354An I/O error occurred in writing to the log file.
355
356@end table
357
358@subheading DESCRIPTION:
359
360The @code{log_write_entry} function writes an event record
361specified by the @code{entry}, @code{buf}, and @code{len} arguments.
362Most of the fields of the event record pointed to by @code{entry}
363are left intact.  The following fields are filled in as follows:
364
365@table @b
366@item log_recid
367This is set to a monotonically increasing log record id
368maintained by the system for this individual log file.
369
370@item log_size
371This is set to the value of the @code{len} argument.
372
373@end table
374
375This allows existing log entries from one log file to be written to
376another log file without destroying the logged information.
377
378@subheading NOTES:
379
380The @code{_POSIX_LOGGING} feature flag is defined to indicate
381this service is available.
382
383This implementation can not return the @code{EPERM} error.
384
385This function is not defined in the POSIX specification.  It is
386an extension provided by this implementation.
387
388@page
389@subsection log_open - Open a log file
390
391@subheading CALLING SEQUENCE:
392
393@ifset is-C
394@example
395#include <evlog.h>
396
397int log_open(
398  logd_t               *logdes,
399  const char           *path,
400  const log_query_t    *query
401);
402@end example
403@end ifset
404
405@ifset is-Ada
406@end ifset
407
408@subheading STATUS CODES:
409
410@table @b
411@item EACCES
412Search permission is denied on a component of the path prefix,
413or the log file exists and read permission is denied.
414
415@item  EINTR
416A signal interrupted the call to log_open().
417
418@item EINVAL
419The log_severity field of the query argument exceeds
420@code{LOG_SEVERITY_MAX}.
421
422@item EINVAL
423The path argument referred to a file that was not a log file.
424
425@item EMFILE
426Too many log file descriptors are currently in use by this
427process.
428
429@item ENAMETOOLONG
430The length of the path string exceeds @code{PATH_MAX}, or a pathname
431component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
432in effect.
433
434@item ENFILE
435Too many files are currently open in the system.
436
437@item ENOENT
438The file specified by the path argument does not exist.
439
440@item ENOTDIR
441A component of the path prefix is not a directory.
442
443@end table
444
445@subheading DESCRIPTION:
446
447The @code{log_open} function establishes the connection between a
448log file and a log file descriptor.  It creates an open log file
449descriptor that refers to this query stream on the specified log file
450The log file descriptor is used by the other log functions to refer
451to that log query stream.  The @code{path} argument points to a
452pathname for a log file.  A @code{path} argument of NULL specifies
453the current system log file. 
454
455The @code{query} argument is not NULL, then it points to a log query
456specification that is used to filter the records in the log file on
457subsequent @code{log_read} operations.  This restricts the set of
458event records read using the returned log file descriptor to those
459which match the query.  A query match occurs for a given record when
460that record's facility is a member of the query's facility set and
461the record's severity is greater than or equal to the severity specified
462in the query.
463
464If the value of the @code{query} argument is NULL, no query filter
465shall be applied.
466
467@subheading NOTES:
468
469The @code{_POSIX_LOGGING} feature flag is defined to indicate
470this service is available.
471
472POSIX specifies that @code{EINVAL} will be returned if the
473@code{log_facilities} field of the @code{query} argument is not
474a valid facility set.  In this implementation, this condition
475can never occur.
476
477Many error codes that POSIX specifies to be returned by @code{log_open}
478should actually be detected by @code{open} and passed back by the
479@code{log_open} implementation.  In this implementation, @code{EACCESS},
480@code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT},
481and @code{ENOTDIR} are detected in this manner.
482
483@page
484@subsection log_read - Read from a log file
485
486@subheading CALLING SEQUENCE:
487
488@ifset is-C
489@example
490#include <evlog.h>
491
492int log_read(
493  const logd_t      logdes,
494  struct log_entry *entry,
495  void             *log_buf,
496  const size_t      log_len,
497  const size_t     *log_sizeread
498);
499@end example
500@end ifset
501
502@ifset is-Ada
503@end ifset
504
505@subheading STATUS CODES:
506
507@table @b
508@item E2BIG
509This error indicates an inconsistency in the implementation.
510Report this as a bug.
511
512@item EBADF
513The @code{logdes} argument is not a valid log file descriptor.
514
515@item EFAULT
516The @code{entry} argument is not a valid pointer to a log entry structure.
517
518@item EFAULT
519The @code{log_sizeread} argument is not a valid pointer to a size_t.
520
521@item EBUSY
522No data available.  There are no unread event records remaining
523in this log file.
524
525@item EINTR
526A signal interrupted the call to log_read().
527
528@item EIO
529An I/O error occurred in reading from the event log.
530
531@item EINVAL
532The matching event record has data associated with it and
533@code{log_buf} was not a valid pointer.
534
535@item EINVAL
536The matching event record has data associated with it which is
537longer than @code{log_len}.
538
539@end table
540
541@subheading DESCRIPTION:
542
543The @code{log_read} function reads the @code{log_entry}
544structure and up to @code{log_len} bytes of data from the next
545event record of the log file associated with the open log file
546descriptor @code{logdes}.  The event record read is placed
547into the @code{log_entry} structure pointed to by
548@code{entry} and any data into the buffer pointed to by @code{log_buf}.
549The log record ID of the returned event record is be stored in the
550@code{log_recid} member of the @code{log_entry} structure for the event
551record.
552
553If the query attribute of the open log file description associated with
554the @code{logdes} is set, the event record read will match that query.
555
556If the @code{log_read} is successful the call stores the actual length
557of the data associated with the event record into the location specified by
558@code{log_sizeread}.  This number will be less than or equal to
559@code{log_len}.
560
561@subheading NOTES:
562
563The @code{_POSIX_LOGGING} feature flag is defined to indicate
564this service is available.
565
566When @code{EINVAL} is returned, then no data is returned although the
567event record is returned.  This is an extension to the POSIX specification.
568
569The POSIX specification specifically allows @code{log_read} to write
570greater than @code{log_len} bytes into @code{log_buf}.  This is highly
571undesirable and this implementation will NOT do this.
572
573@page
574@subsection log_notify - Notify Process of writes to the system log.
575
576@subheading CALLING SEQUENCE:
577
578@ifset is-C
579@example
580#include <evlog.h>
581
582int log_notify(
583  const logd_t           logdes,
584  const struct sigevent *notification
585);
586@end example
587@end ifset
588
589@ifset is-Ada
590@end ifset
591
592@subheading STATUS CODES:
593
594@table @b
595@item EBADF
596The logdes argument is not a valid log file descriptor.
597
598@item EINVAL
599The notification argument specifies an invalid signal.
600
601@item EINVAL
602The process has requested a notify on a log that will not be
603written to.
604
605@item ENOSYS
606The function log_notify() is not supported by this implementation.
607
608@end table
609
610@subheading DESCRIPTION:
611
612If the argument @code{notification} is not NULL this function registers
613the calling process to be notified of event records received by the system
614log, which match the query parameters associated with the open log descriptor
615specified by @code{logdes}.  The notification specified by the
616@code{notification} argument shall be sent to the process when an event
617record received by the system log is matched by the query attribute of the
618open log file description associated with the @code{logdes} log file
619descriptor.  If the calling process has already registered a notification
620for the @code{logdes} log file descriptor, the new notification shall
621replace the existing notification registration.
622
623If the @code{notification} argument is NULL and the calling process is
624currently registered to be notified for the @code{logdes} log file
625descriptor, the existing registration shall be removed.
626
627@subheading NOTES:
628
629The @code{_POSIX_LOGGING} feature flag is defined to indicate
630this service is available.
631
632@page
633@subsection log_close - Close log descriptor
634
635@subheading CALLING SEQUENCE:
636
637@ifset is-C
638@example
639#include <evlog.h>
640
641int log_close(
642  const logd_t   logdes
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 EBADF
654The logdes argument is not a valid log file descriptor.
655
656@end table
657
658@subheading DESCRIPTION:
659
660The @code{log_close} function deallocates the open log file descriptor
661indicated by @code{log_des}.
662
663When all log file descriptors associated with an open log file description
664have been closed, the open log file description is freed.
665
666If the link count of the log file is zero, when all log file descriptors
667have been closed, the space occupied by the log file is freed and the
668log file shall no longer be accessible.
669
670If the process has successfully registered a notification request for the
671log file descriptor, the registration is removed.
672
673@subheading NOTES:
674
675The @code{_POSIX_LOGGING} feature flag is defined to indicate
676this service is available.
677
678@page
679@subsection log_seek - Reposition log file offset
680
681@subheading CALLING SEQUENCE:
682
683@ifset is-C
684@example
685#include <evlog.h>
686
687int log_seek(
688  const logd_t    logdes,
689  log_recid_t     log_recid
690);
691@end example
692@end ifset
693
694@ifset is-Ada
695@end ifset
696
697@subheading STATUS CODES:
698
699@table @b
700@item EBADF
701The @code{logdes} argument is not a valid log file descriptor.
702
703@end table
704
705@subheading DESCRIPTION:
706
707The @code{log_seek} function sets the log file offset of the open
708log description associated with the @code{logdes} log file descriptor
709to the event record in the log file identified by @code{log_recid}. 
710The @code{log_recid} argument is either the record id of a valid event
711record or one of the following values, as defined in the header <evlog.h>:
712
713@table @b
714@item LOG_SEEK_START
715Set log file position to point at the first event
716record in the log file.
717
718@item LOG_SEEK_END
719Set log file position to point after the last event
720record in the log file.
721
722@end table
723
724@subheading NOTES:
725
726The @code{_POSIX_LOGGING} feature flag is defined to indicate
727this service is available.
728
729This implementation can not return @code{EINTR}.
730
731This implementation can not return @code{EINVAL} to indicate that
732the @code{log_recid} argument is not a valid record id.
733
734@page
735@subsection log_severity_before - Compare event record severities
736
737@subheading CALLING SEQUENCE:
738
739@ifset is-C
740@example
741#include <evlog.h>
742
743int log_severity_before(
744  log_severity_t  s1,
745  log_severity_t  s2
746);
747@end example
748@end ifset
749
750@ifset is-Ada
751@end ifset
752
753@subheading STATUS CODES:
754
755@table @b
756@item 0
757The severity of @code{s1} is less than that of @code{s2}.
758
759@item 1
760The severity of @code{s1} is greater than or equal that of @code{s2}.
761
762@item EINVAL
763The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
764
765@end table
766
767@subheading DESCRIPTION:
768
769The @code{log_severity_before} function compares the severity order
770of the @code{s1} and @code{s2} arguments.  If @code{s1} is of
771severity greater than or equal to that of @code{s2}, then this
772function returns 1.  Otherwise, it returns 0.
773
774If either @code{s1} or @code{s2} specify invalid severity values, the
775return value of @code{log_severity_before} is unspecified.
776
777@subheading NOTES:
778
779The @code{_POSIX_LOGGING} feature flag is defined to indicate
780this service is available.
781
782The POSIX specification of the return value for this function is ambiguous.
783If @code{EINVAL} is equal to 1 in an implementation, then the application
784can not distinguish between greater than and an error condition.
785
786@page
787@subsection log_facilityemptyset - Manipulate log facility sets
788
789@subheading CALLING SEQUENCE:
790
791@ifset is-C
792@example
793#include <evlog.h>
794
795int log_facilityemptyset(
796  log_facility_set_t  *set
797);
798@end example
799@end ifset
800
801@ifset is-Ada
802@end ifset
803
804@subheading STATUS CODES:
805
806@table @b
807@item EFAULT
808The @code{set} argument is an invalid pointer.
809
810@end table
811
812@subheading DESCRIPTION:
813
814The @code{log_facilityemptyset} function initializes the facility
815set pointed to by the argument @code{set}, such that all facilities
816are excluded.
817
818@subheading NOTES:
819
820The @code{_POSIX_LOGGING} feature flag is defined to indicate
821this service is available.
822
823Applications shall call either @code{log_facilityemptyset} or
824@code{log_facilityfillset} at least once for each object of type
825@code{log_facilityset_t} prior to any other use of that object.  If
826such an object is not initialized in this way, but is nonetheless
827supplied as an argument to any of the @code{log_facilityaddset},
828@code{logfacilitydelset}, @code{log_facilityismember} or
829@code{log_open} functions, the results are undefined.
830
831@page
832@subsection log_facilityfillset - Manipulate log facility sets
833
834@subheading CALLING SEQUENCE:
835
836@ifset is-C
837@example
838#include <evlog.h>
839
840int log_facilityfillset(
841  log_facility_set_t  *set
842);
843@end example
844@end ifset
845
846@ifset is-Ada
847@end ifset
848
849@subheading STATUS CODES:
850
851@table @b
852@item EFAULT
853The @code{set} argument is an invalid pointer.
854
855@end table
856
857@subheading DESCRIPTION:
858
859The @code{log_facilityfillset} function initializes the facility
860set pointed to by the argument @code{set}, such that all facilities
861are included.
862
863@subheading NOTES:
864
865The @code{_POSIX_LOGGING} feature flag is defined to indicate
866this service is available.
867
868Applications shall call either @code{log_facilityemptyset} or
869@code{log_facilityfillset} at least once for each object of type
870@code{log_facilityset_t} prior to any other use of that object.  If
871such an object is not initialized in this way, but is nonetheless
872supplied as an argument to any of the @code{log_facilityaddset},
873@code{logfacilitydelset}, @code{log_facilityismember} or
874@code{log_open} functions, the results are undefined.
875
876@page
877@subsection log_facilityaddset - Manipulate log facility sets
878
879@subheading CALLING SEQUENCE:
880
881@ifset is-C
882@example
883#include <evlog.h>
884
885int log_facilityaddset(
886  log_facility_set_t  *set,
887  log_facility_t       facilityno
888);
889@end example
890@end ifset
891
892@ifset is-Ada
893@end ifset
894
895@subheading STATUS CODES:
896
897@table @b
898@item EFAULT
899The @code{set} argument is an invalid pointer.
900
901@item EINVAL
902The @code{facilityno} argument is not a valid facility.
903
904@end table
905
906@subheading DESCRIPTION:
907
908The @code{log_facilityaddset} function adds the individual
909facility specified by the value of the argument @code{facilityno}
910to the facility set pointed to by the argument @code{set}.
911
912@subheading NOTES:
913
914The @code{_POSIX_LOGGING} feature flag is defined to indicate
915this service is available.
916
917Applications shall call either @code{log_facilityemptyset} or
918@code{log_facilityfillset} at least once for each object of type
919@code{log_facilityset_t} prior to any other use of that object.  If
920such an object is not initialized in this way, but is nonetheless
921supplied as an argument to any of the @code{log_facilityaddset},
922@code{logfacilitydelset}, @code{log_facilityismember} or
923@code{log_open} functions, the results are undefined.
924
925@page
926@subsection log_facilitydelset - Manipulate log facility sets
927
928@subheading CALLING SEQUENCE:
929
930@ifset is-C
931@example
932#include <evlog.h>
933
934int log_facilitydelset(
935  log_facility_set_t  *set,
936  log_facility_t       facilityno
937);
938@end example
939@end ifset
940
941@ifset is-Ada
942@end ifset
943
944@subheading STATUS CODES:
945
946@table @b
947@item EFAULT
948The @code{set} argument is an invalid pointer.
949
950@item EINVAL
951The @code{facilityno} argument is not a valid facility.
952
953@end table
954
955@subheading DESCRIPTION:
956
957The @code{log_facilitydelset} function deletes the individual
958facility specified by the value of the argument @code{facilityno}
959from the facility set pointed to by the argument @code{set}.
960
961@subheading NOTES:
962
963The @code{_POSIX_LOGGING} feature flag is defined to indicate
964this service is available.
965
966Applications shall call either @code{log_facilityemptyset} or
967@code{log_facilityfillset} at least once for each object of type
968@code{log_facilityset_t} prior to any other use of that object.  If
969such an object is not initialized in this way, but is nonetheless
970supplied as an argument to any of the @code{log_facilityaddset},
971@code{logfacilitydelset}, @code{log_facilityismember} or
972@code{log_open} functions, the results are undefined.
973
974@page
975@subsection log_facilityismember - Manipulate log facility sets
976
977@subheading CALLING SEQUENCE:
978
979@ifset is-C
980@example
981#include <evlog.h>
982
983int log_facilityismember(
984  const log_facility_set_t *set,
985  log_facility_t            facilityno,
986  const int                *member
987);
988@end example
989@end ifset
990
991@ifset is-Ada
992@end ifset
993
994@subheading STATUS CODES:
995
996@table @b
997@item EFAULT
998The @code{set} or @code{member} argument is an invalid pointer.
999
1000@item EINVAL
1001The @code{facilityno} argument is not a valid facility.
1002
1003@end table
1004
1005@subheading DESCRIPTION:
1006
1007The @code{log_facilityismember} function tests whether the facility
1008specified by the value of the argument @code{facilityno} is a member
1009of the set pointed to by the argument @code{set}.  Upon successful
1010completion, the @code{log_facilityismember} function either returns
1011a value of one to the location specified by @code{member} if the
1012specified facility is a member of the specified set or value of
1013zero to the location specified by @code{member} if the specified
1014facility is not a member of the specified set.
1015
1016@subheading NOTES:
1017
1018The @code{_POSIX_LOGGING} feature flag is defined to indicate
1019this service is available.
1020
1021Applications shall call either @code{log_facilityemptyset} or
1022@code{log_facilityfillset} at least once for each object of type
1023@code{log_facilityset_t} prior to any other use of that object.  If
1024such an object is not initialized in this way, but is nonetheless
1025supplied as an argument to any of the @code{log_facilityaddset},
1026@code{logfacilitydelset}, @code{log_facilityismember} or
1027@code{log_open} functions, the results are undefined.
1028
1029@page
1030@subsection log_create - Creates a log file
1031
1032@subheading CALLING SEQUENCE:
1033
1034@ifset is-C
1035@example
1036#include <evlog.h>
1037
1038int log_create(
1039  logd_t       *ld,
1040  const char   *path,
1041);
1042@end example
1043@end ifset
1044
1045@ifset is-Ada
1046@end ifset
1047
1048@subheading STATUS CODES:
1049
1050@table @b
1051
1052@item
1053EEXIST
1054The @code{path} already exists and O_CREAT and O_EXCL were used.
1055
1056@item
1057EISDIR
1058The @code{path} refers to a directory and the access requested involved
1059writing.
1060
1061@item
1062ETXTBSY
1063The @code{path} refers to an executable image which is currently being 
1064executed and write access was requested.
1065
1066@item
1067EFAULT
1068The @code{path} points outside your accessible address space.
1069
1070@item
1071EACCES
1072The requested access to the file is not allowed, or one of the
1073directories in @code{path} did not allow search (execute) permission.
1074
1075@item
1076ENAMETOOLONG
1077The @code{path} was too long.
1078
1079@item
1080ENOENT
1081A directory component in @code{path} does not exist or is a dangling symbolic
1082link.
1083
1084@item       
1085ENOTDIR
1086A component used as a directory in @code{path} is not, in fact, a directory.
1087
1088@item
1089EMFILE
1090The process already has the maximum number of files open.
1091
1092@item
1093ENFILE
1094The limit on the total number of files open on the system has been reached.
1095
1096@item
1097ENOMEM
1098Insufficient kernel memory was available.
1099
1100@item
1101EROFS
1102The @code{path} refers to a file on a read-only filesystem and write access
1103was requested.
1104
1105@item
1106ELOOP
1107The @code{path} contains a reference to a circular symbolic link, ie a
1108symbolic link whose expansion contains a reference to itself.
1109
1110@end table
1111
1112@subheading DESCRIPTION:
1113
1114This function attempts to create a file associated with the @code{logdes}
1115argument in the directory provided by the argument @code{path}.
1116
1117@subheading NOTES:
1118
1119The @code{_POSIX_LOGGING} feature flag is defined to indicate
1120this service is available.
1121
1122@page
1123@subsection log_sys_create - Creates a system log file
1124
1125@subheading CALLING SEQUENCE:
1126
1127@ifset is-C
1128@example
1129#include <evlog.h>
1130
1131int log_sys_create();
1132@end example
1133@end ifset
1134
1135@ifset is-Ada
1136@end ifset
1137
1138@subheading STATUS CODES:
1139
1140@table @b
1141@item EEXIST
1142The directory path to the system log already exist.
1143
1144@end table
1145
1146@subheading DESCRIPTION:
1147
1148This function will create a predefined system log directory path and
1149system log file if they do not already exist.
1150
1151@subheading NOTES:
1152
1153The @code{_POSIX_LOGGING} feature flag is defined to indicate
1154this service is available.
Note: See TracBrowser for help on using the repository browser.