source: rtems/doc/new_chapters/eventlog.t @ 23f014a

4.104.114.84.95
Last change on this file since 23f014a was 23f014a, checked in by Wade A Smith <warm38@…>, on Sep 11, 1998 at 7:21:41 PM

Added documentation for the log_facilityisvalid routine and add thew
status code EINVAL to the log_seek routine.

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