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

4.104.114.84.95
Last change on this file since f8c5bad was f8c5bad, checked in by Wade A Smith <warm38@…>, on Sep 21, 1998 at 9:31:59 PM

Updated file based upon red-lines received.

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