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

4.104.114.84.95
Last change on this file since b67f7946 was b67f7946, checked in by Joel Sherrill <joel.sherrill@…>, on 08/28/98 at 14:32:01

Added log_write_any and part of log_copy.

Reviewed log_close.

  • Property mode set to 100644
File size: 24.4 KB
RevLine 
[832e33c]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
[d1a859c]13The event logging manager provides a portable method for logging
[a99ea16]14system and application events and subsequent processing of those
[d1a859c]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}.
[832e33c]18
19The directives provided by the event logging manager are:
20
21@itemize @bullet
[ebc67925]22@item @code{log_write} - Write to the Log
[b67f7946]23@item @code{log_write_any} - Write to any log file
[ebc67925]24@item @code{log_open} - Open a log file
25@item @code{log_read} - Read from the system Log
26@item @code{log_notify} - Notify Process of writes to the system log
27@item @code{log_close} - Close log descriptor
[b67f7946]28@item @code{log_copy} -
[ebc67925]29@item @code{log_seek} - Reposition log file offset
30@item @code{log_severity_before} - Compare event record severities
31@item @code{log_facilityemptyset} - Manipulate log facility sets
32@item @code{log_facilityfillset} - Manipulate log facility sets
33@item @code{log_facilityaddset} - Manipulate log facility sets
34@item @code{log_facilitydelset} - Manipulate log facility sets
35@item @code{log_facilityismember} - Manipulate log facility sets
[832e33c]36@end itemize
37
38@section Background
39
[d1a859c]40@subsection Log Files and Events
41
42System log
43
44Non-system logs
45
46Events, facility, severity
47
48@subsection Queries
49
[832e33c]50@section Operations
51
[d1a859c]52@subsection Creating and Writing a non-System Log
53
54Discuss creating and writing to a non-system log.
55
56@example
57  log_create
58  log_write loop
59@end example
60
61@subsection Reading a Log
62
63Discuss opening and reading from a log.
64
65@example
66  build a query
67  log_open
68  log_read loop
69@end example
70
[832e33c]71@section Directives
72
73This section details the event logging manager's directives.
74A subsection is dedicated to each of this manager's directives
75and describes the calling sequence, related constants, usage,
76and status codes.
77
78@page
[ebc67925]79@subsection log_write - Write to the Log
[832e33c]80
81@subheading CALLING SEQUENCE:
82
83@ifset is-C
84@example
[30cc2e0]85#include <evlog.h>
86
[832e33c]87int log_write(
[ebc67925]88  const log_facility_t  facility,
89  const int             event_id,
90  const log_severity_t  severity,
91  const void           *buf,
92  const size_t          len
[832e33c]93);
94@end example
95@end ifset
96
97@ifset is-Ada
98@end ifset
99
100@subheading STATUS CODES:
101
[16bed8a]102@table @b
[ebc67925]103@item EINVAL
104The facility argument is not a valid log_facility.
[d1a859c]105
[ebc67925]106@item EINVAL
[d5ef5bd1]107The severity argument exceeds @code{LOG_SEVERITY_MAX}
[d1a859c]108
[ebc67925]109@item EINVAL
[d5ef5bd1]110The len argument exceeds @code{LOG_ENTRY_MAXLEN}
[d1a859c]111
[ebc67925]112@item ENOSPC
113The log file has run out of space on the device.
[d1a859c]114
[ebc67925]115@item EPERM
116The caller does not have appropriate permission for writing to
117the given facility.
[d1a859c]118
[ebc67925]119@item EIO
120An I/O error occurred in writing to the system event log.
[16bed8a]121
122@end table
123
[832e33c]124@subheading DESCRIPTION:
125
[d1a859c]126The @code{log_write} function writes an event record, consisting
127of event attributes, and the data identified by the @code{buf}
128argument, to the system log.  The @code{len} argument specifies
129the length in bytes of the buffer pointed to by @code{buf}.  The
130@code{len} argument shall specify the value of the event record
131length attribute.  The value of @code{len} shall be less than or
132equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
133
134The @code{event_id} argument identifies the type of event record
135being written.  The @code{event_id} argument shall specify the value
136of the event ID attribute of the event record.
137
138The argument @code{facility} indicates the facility from which the
[a99ea16]139event type is drawn.  The @code{facility} argument shall specify the
[d1a859c]140value of the event record facility attribute.  The value of the
141@code{facility} argument shall be a valid log facility or the
142@code{log_write} function shall fail.
143
144The @code{severity} argument indicates the severity level of the
145event record.  The @code{severity} argument shall specify the value
146of the event record severity attribute.  The value of the
147@code{severity} argument shall be less than or equal to
148@code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
149
150The effective_UID of the calling process shall specify the event
[a99ea16]151record UID attribute.  The effective-GID of the calling process
[d1a859c]152shall specify the event record GID attribute.  The process ID
153of the calling process shall specify the event record process ID
154attribute.  The process group ID of the calling process shall
155specify the event record process group ID attribute.  The current
156value of the system clock shall specify the event record timestamp
157attribute.
[ebc67925]158
[832e33c]159@subheading NOTES:
160
[d1a859c]161The @code{_POSIX_LOGGING} feature flag is defined to indicate
162this service is available.
163
[b67f7946]164@page
165@subsection log_write_any - Write to the any log file
166
167@subheading CALLING SEQUENCE:
168
169@ifset is-C
170@example
171#include <evlog.h>
172
173int log_write_any(
174  const logd_t          logdes,
175  const log_facility_t  facility,
176  const int             event_id,
177  const log_severity_t  severity,
178  const void           *buf,
179  const size_t          len
180);
181@end example
182@end ifset
183 
184@ifset is-Ada
185@end ifset
186
187@subheading STATUS CODES:
188
189@table @b
190@item EINVAL
191The facility argument is not a valid log_facility.
192
193@item EINVAL
194The severity argument exceeds @code{LOG_SEVERITY_MAX}
195
196@item EINVAL
197The len argument exceeds @code{LOG_ENTRY_MAXLEN}
198
199@item ENOSPC
200The log file has run out of space on the device.
201
202@item EPERM
203The caller does not have appropriate permission for writing to
204the given facility.
205
206@item EIO
207An I/O error occurred in writing to the system event log.
208
209@end table
210
211@subheading DESCRIPTION:
212
213The @code{log_write} function writes an event record, consisting
214of event attributes, and the data identified by the @code{buf}
215argument, to a log file.  The @code{len} argument specifies
216the length in bytes of the buffer pointed to by @code{buf}.  The
217@code{len} argument shall specify the value of the event record
218length attribute.  The value of @code{len} shall be less than or
219equal to @code{LOG_ENTRY_MAXLEN} or the @code{log_write} shall fail.
220
221The @code{event_id} argument identifies the type of event record
222being written.  The @code{event_id} argument shall specify the value
223of the event ID attribute of the event record.
224
225The argument @code{facility} indicates the facility from which the
226event type is drawn.  The @code{facility} argument shall specify the
227value of the event record facility attribute.  The value of the
228@code{facility} argument shall be a valid log facility or the
229@code{log_write} function shall fail.
230
231The @code{severity} argument indicates the severity level of the
232event record.  The @code{severity} argument shall specify the value
233of the event record severity attribute.  The value of the
234@code{severity} argument shall be less than or equal to
235@code{LOG_SEVERITY_MAX} or the @code{log_write} function shall fail. 
236
237The effective_UID of the calling process shall specify the event
238record UID attribute.  The effective-GID of the calling process
239shall specify the event record GID attribute.  The process ID
240of the calling process shall specify the event record process ID
241attribute.  The process group ID of the calling process shall
242specify the event record process group ID attribute.  The current
243value of the system clock shall specify the event record timestamp
244attribute.
245
246@subheading NOTES:
247
248The @code{_POSIX_LOGGING} feature flag is defined to indicate
249this service is available.
250
[832e33c]251@page
[ebc67925]252@subsection log_open - Open a log file
[832e33c]253
254@subheading CALLING SEQUENCE:
255
256@ifset is-C
257@example
[30cc2e0]258#include <evlog.h>
259
[832e33c]260int log_open(
[6520befe]261  logd_t               *logdes,
[ebc67925]262  const char           *path,
263  const log_query_t    *query
[832e33c]264);
265@end example
266@end ifset
267
268@ifset is-Ada
269@end ifset
270
271@subheading STATUS CODES:
272
[16bed8a]273@table @b
[ebc67925]274@item EACCES
275Search permission is denied on a component of the path prefix,
276or the log file exists and read permission is denied.
[d1a859c]277
[ebc67925]278@item  EINTR
279A signal interrupted the call to log_open().
[d1a859c]280
[ebc67925]281@item EINVAL
282The log_severity field of the query argument exceeds
[d5ef5bd1]283@code{LOG_SEVERITY_MAX}.
[d1a859c]284
[ebc67925]285@item EINVAL
286The path argument referred to a file that was not a log file.
[d1a859c]287
[ebc67925]288@item EMFILE
289Too many log file descriptors are currently in use by this
290process.
[d1a859c]291
[ebc67925]292@item ENAMETOOLONG
[d5ef5bd1]293The length of the path string exceeds @code{PATH_MAX}, or a pathname
294component is longer than @code{NAME_MAX} while @code{_POSIX_NO_TRUNC} is
[ebc67925]295in effect.
[d1a859c]296
[ebc67925]297@item ENFILE
298Too many files are currently open in the system.
[d1a859c]299
[ebc67925]300@item ENOENT
301The file specified by the path argument does not exist.
[d1a859c]302
[ebc67925]303@item ENOTDIR
304A component of the path prefix is not a directory.
[16bed8a]305
306@end table
307
[832e33c]308@subheading DESCRIPTION:
309
[d1a859c]310The @code{log_open} function establishes the connection between a
311log file and a log file descriptor.  It creates an open log file
[6520befe]312descriptor that refers to this query stream on the specified log file
313The log file descriptor is used by the other log functions to refer
314to that log query stream.  The @code{path} argument points to a
315pathname for a log file.  A @code{path} argument of NULL specifies
316the current system log file. 
317
318The @code{query} argument is not NULL, then it points to a log query
319specification that is used to filter the records in the log file on
320subsequent @code{log_read} operations.  This restricts the set of
321event records read using the returned log file descriptor to those
322which match the query.  A query match occurs for a given record when
323that record's facility is a member of the query's facility set and
324the record's severity is greater than or equal to the severity specified
325in the query.
326
327If the value of the @code{query} argument is NULL, no query filter
328shall be applied.
[ebc67925]329
[832e33c]330@subheading NOTES:
331
[d1a859c]332The @code{_POSIX_LOGGING} feature flag is defined to indicate
333this service is available.
334
[6520befe]335POSIX specifies that @code{EINVAL} will be returned if the
336@code{log_facilities} field of the @code{query} argument is not
337a valid facility set.  In this implementation, this condition
338can never occur.
339
340Many error codes that POSIX specifies to be returned by @code{log_open}
341should actually be detected by @code{open} and passed back by the
342@code{log_open} implementation.  In this implementation, @code{EACCESS},
343@code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT},
344and @code{ENOTDIR} are detected in this manner.
345
[832e33c]346@page
[ebc67925]347@subsection log_read - Read from the system Log
[832e33c]348
349@subheading CALLING SEQUENCE:
350
351@ifset is-C
352@example
[30cc2e0]353#include <evlog.h>
354
[832e33c]355int log_read(
[af5a571]356  const logd_t      logdes,
[ebc67925]357  struct log_entry *entry,
358  void             *log_buf,
359  const size_t      log_len,
360  const size_t     *log_sizeread
[832e33c]361);
362@end example
363@end ifset
364
365@ifset is-Ada
366@end ifset
367
368@subheading STATUS CODES:
369
[16bed8a]370@table @b
[ebc67925]371@item EBADF
372The logdes argument is not a valid log file descriptor.
[d1a859c]373
[ebc67925]374@item EBUSY
375No data available.  The open log file descriptor references
376the current system log.  and there are no unread event records
377remaining.
[d1a859c]378
[ebc67925]379@item EINTR
380A signal interrupted the call to log_read().
[d1a859c]381
[ebc67925]382@item EIO
383An I/O error occurred in reading from the event log.
[16bed8a]384
385@end table
386
[832e33c]387@subheading DESCRIPTION:
388
[d1a859c]389The @code{log_read} function shall attempt to read the @code{log_entry}
390structure and @code{log_len} bytes of data from the next event record
391of the log file associated with the open log file descriptor @code{logdes},
392placing the @code{log_entry} structure into the buffer pointed to by
393@code{entry}, and the data into the buffer pointed to by @code{log_buf}.
394The log record ID of the returned event record shall be stored in the
[a99ea16]395@code{log_recid} member of the @code{log_entry} structure for the event
[d1a859c]396record.
397
398If the query attribute of the open log file description associated with
399the @code{logdes} is set, the event record read shall match that query.
400If the @code{entry} argument is not NULL it will point to a @code{log_entry}
[a99ea16]401structure which shall be filled with the creation information for this log
[d1a859c]402entry.  If the argument @code{log_buf} is not NULL the data written with the
403log entry will be placed in the buffer.  The size of the buffer is specified
404by the argument @code{log_len}.
405
406If the @code{log_read} is successful the call shall store the actual length
407of the data associated with the event record into the location specified by
408@code{log_sizeread}.  This number may be smaller or greater than
409@code{log_len}.
[ebc67925]410
[832e33c]411@subheading NOTES:
412
[d1a859c]413The @code{_POSIX_LOGGING} feature flag is defined to indicate
414this service is available.
415
[832e33c]416@page
[ebc67925]417@subsection log_notify - Notify Process of writes to the system log.
[832e33c]418
419@subheading CALLING SEQUENCE:
420
421@ifset is-C
422@example
[30cc2e0]423#include <evlog.h>
424
[832e33c]425int log_notify(
[ebc67925]426  const logd_t           logdes,
427  const struct sigevent *notification
[832e33c]428);
429@end example
430@end ifset
431
432@ifset is-Ada
433@end ifset
434
435@subheading STATUS CODES:
436
[16bed8a]437@table @b
[ebc67925]438@item EBADF
[a99ea16]439The logdes argument is not a valid log file descriptor.
[d1a859c]440
[ebc67925]441@item EINVAL
442The notification argument specifies an invalid signal.
[d1a859c]443
[ebc67925]444@item EINVAL
445The process has requested a notify on a log that will not be
446written to.
[d1a859c]447
[30cc2e0]448@item ENOSYS
[ebc67925]449The function log_notify() is not supported by this implementation.
[16bed8a]450
451@end table
452
[832e33c]453@subheading DESCRIPTION:
454
[d1a859c]455If the argument @code{notification} is not NULL this function registers
456the calling process to be notified of event records received by the system
457log, which match the query parameters associated with the open log descriptor
458specified by @code{logdes}.  The notification specified by the
459@code{notification} argument shall be sent to the process when an event
460record received by the system log is matched by the query attribute of the
461open log file description associated with the @code{logdes} log file
462descriptor.  If the calling process has already registered a notification
463for the @code{logdes} log file descriptor, the new notification shall
464replace the existing notification registration.
465
466If the @code{notification} argument is NULL and the calling process is
467currently registered to be notified for the @code{logdes} log file
468descriptor, the existing registration shall be removed.
[09470e0]469
[832e33c]470@subheading NOTES:
471
[d1a859c]472The @code{_POSIX_LOGGING} feature flag is defined to indicate
473this service is available.
474
[832e33c]475@page
[ebc67925]476@subsection log_close - Close log descriptor
[832e33c]477
478@subheading CALLING SEQUENCE:
479
480@ifset is-C
481@example
[30cc2e0]482#include <evlog.h>
483
[832e33c]484int log_close(
[ebc67925]485  const logd_t   logdes
[832e33c]486);
487@end example
488@end ifset
489
490@ifset is-Ada
491@end ifset
492
493@subheading STATUS CODES:
494
[16bed8a]495@table @b
[ebc67925]496@item EBADF
497The logdes argument is not a valid log file descriptor.
[16bed8a]498
499@end table
500
[832e33c]501@subheading DESCRIPTION:
502
[d1a859c]503The @code{log_close} function deallocates the open log file descriptor
504indicated by @code{log_des}.
[2dd561a3]505
[d1a859c]506When all log file descriptors associated with an open log file description
[b67f7946]507have been closed, the open log file description is freed.
[2dd561a3]508
[d1a859c]509If the link count of the log file is zero, when all log file descriptors
[b67f7946]510have been closed, the space occupied by the log file is freed and the
[d1a859c]511log file shall no longer be accessible.
[2dd561a3]512
[d1a859c]513If the process has successfully registered a notification request for the
[b67f7946]514log file descriptor, the registration is removed.
[ebc67925]515
[832e33c]516@subheading NOTES:
517
[d1a859c]518The @code{_POSIX_LOGGING} feature flag is defined to indicate
519this service is available.
520
[832e33c]521@page
[ebc67925]522@subsection log_seek - Reposition log file offset
[832e33c]523
524@subheading CALLING SEQUENCE:
525
526@ifset is-C
527@example
[30cc2e0]528#include <evlog.h>
529
[832e33c]530int log_seek(
[ebc67925]531  const logd_t    logdes,
532  log_recid_t     log_recid
[832e33c]533);
534@end example
535@end ifset
536
537@ifset is-Ada
538@end ifset
539
540@subheading STATUS CODES:
541
[16bed8a]542@table @b
[ebc67925]543@item EBADF
[af5a571]544The @code{logdes} argument is not a valid log file descriptor.
[16bed8a]545
546@end table
547
[832e33c]548@subheading DESCRIPTION:
549
[af5a571]550The @code{log_seek} function sets the log file offset of the open
[a99ea16]551log description associated with the @code{logdes} log file descriptor
[d1a859c]552to the event record in the log file identified by @code{log_recid}. 
553The @code{log_recid} argument is either the record id of a valid event
554record or one of the following values, as defined in the header <evlog.h>:
555
556@table @b
557@item LOG_SEEK_START
558Set log file position to point at the first event
[af5a571]559record in the log file.
[2dd561a3]560
[d1a859c]561@item LOG_SEEK_END
562Set log file position to point after the last event
[af5a571]563record in the log file.
[2dd561a3]564
[d1a859c]565@end table
[2dd561a3]566
[832e33c]567@subheading NOTES:
568
[d1a859c]569The @code{_POSIX_LOGGING} feature flag is defined to indicate
570this service is available.
571
[af5a571]572This implementation can not return @code{EINTR}.
573
574This implementation can not return @code{EINVAL} to indicate that
575the @code{log_recid} argument is not a valid record id.
576
[832e33c]577@page
[ebc67925]578@subsection log_severity_before - Compare event record severities
[832e33c]579
580@subheading CALLING SEQUENCE:
581
582@ifset is-C
583@example
[30cc2e0]584#include <evlog.h>
585
[832e33c]586int log_severity_before(
[ebc67925]587  log_severity_t  s1,
588  log_severity_t  s2
[832e33c]589);
590@end example
591@end ifset
592
593@ifset is-Ada
594@end ifset
595
596@subheading STATUS CODES:
597
[16bed8a]598@table @b
[c5568160]599@item 0
600The severity of @code{s1} is less than that of @code{s2}.
601
602@item 1
603The severity of @code{s1} is greater than or equal that of @code{s2}.
604
[ebc67925]605@item EINVAL
[d5ef5bd1]606The value of either s1 or s2 exceeds @code{LOG_SEVERITY_MAX}.
[16bed8a]607
608@end table
609
[832e33c]610@subheading DESCRIPTION:
611
[c5568160]612The @code{log_severity_before} function compares the severity order
613of the @code{s1} and @code{s2} arguments.  If @code{s1} is of
614severity greater than or equal to that of @code{s2}, then this
615function returns 1.  Otherwise, it returns 0.
[2dd561a3]616
[c5568160]617If either @code{s1} or @code{s2} specify invalid severity values, the
618return value of @code{log_severity_before} is unspecified.
[ebc67925]619
[832e33c]620@subheading NOTES:
621
[d1a859c]622The @code{_POSIX_LOGGING} feature flag is defined to indicate
623this service is available.
624
[c5568160]625The POSIX specification of the return value for this function is ambiguous.
626If @code{EINVAL} is equal to 1 in an implementation, then the application
627can not distinguish between greater than and an error condition.
628
[832e33c]629@page
[ebc67925]630@subsection log_facilityemptyset - Manipulate log facility sets
[832e33c]631
632@subheading CALLING SEQUENCE:
633
634@ifset is-C
635@example
[30cc2e0]636#include <evlog.h>
637
[832e33c]638int log_facilityemptyset(
[ebc67925]639  log_facility_set_t  *set
[832e33c]640);
641@end example
642@end ifset
643
644@ifset is-Ada
645@end ifset
646
647@subheading STATUS CODES:
648
[16bed8a]649@table @b
[d65d22a0]650@item EFAULT
651The @code{set} argument is an invalid pointer.
[16bed8a]652
653@end table
654
[832e33c]655@subheading DESCRIPTION:
656
[d1a859c]657The @code{log_facilityemptyset} function initializes the facility
[a99ea16]658set pointed to by the argument @code{set}, such that all facilities
[d65d22a0]659are excluded.
660
661@subheading NOTES:
662
663The @code{_POSIX_LOGGING} feature flag is defined to indicate
664this service is available.
[d1a859c]665
666Applications shall call either @code{log_facilityemptyset} or
667@code{log_facilityfillset} at least once for each object of type
668@code{log_facilityset_t} prior to any other use of that object.  If
669such an object is not initialized in this way, but is nonetheless
[d65d22a0]670supplied as an argument to any of the @code{log_facilityaddset},
[d1a859c]671@code{logfacilitydelset}, @code{log_facilityismember} or
672@code{log_open} functions, the results are undefined.
673
[832e33c]674@page
[ebc67925]675@subsection log_facilityfillset - Manipulate log facility sets
[832e33c]676
677@subheading CALLING SEQUENCE:
678
679@ifset is-C
680@example
[30cc2e0]681#include <evlog.h>
682
[832e33c]683int log_facilityfillset(
[ebc67925]684  log_facility_set_t  *set
[832e33c]685);
686@end example
687@end ifset
688
689@ifset is-Ada
690@end ifset
691
692@subheading STATUS CODES:
693
[16bed8a]694@table @b
[d65d22a0]695@item EFAULT
696The @code{set} argument is an invalid pointer.
[16bed8a]697
698@end table
699
[832e33c]700@subheading DESCRIPTION:
701
[d65d22a0]702The @code{log_facilityfillset} function initializes the facility
[a99ea16]703set pointed to by the argument @code{set}, such that all facilities
[d1a859c]704are included.
705
[d65d22a0]706@subheading NOTES:
707
708The @code{_POSIX_LOGGING} feature flag is defined to indicate
709this service is available.
710
[d1a859c]711Applications shall call either @code{log_facilityemptyset} or
712@code{log_facilityfillset} at least once for each object of type
713@code{log_facilityset_t} prior to any other use of that object.  If
714such an object is not initialized in this way, but is nonetheless
[d65d22a0]715supplied as an argument to any of the @code{log_facilityaddset},
[d1a859c]716@code{logfacilitydelset}, @code{log_facilityismember} or
717@code{log_open} functions, the results are undefined.
718
[832e33c]719@page
[ebc67925]720@subsection log_facilityaddset - Manipulate log facility sets
[832e33c]721
722@subheading CALLING SEQUENCE:
723
724@ifset is-C
725@example
[30cc2e0]726#include <evlog.h>
727
[832e33c]728int log_facilityaddset(
[ebc67925]729  log_facility_set_t  *set,
[d65d22a0]730  log_facility_t       facilityno
[832e33c]731);
732@end example
733@end ifset
734
735@ifset is-Ada
736@end ifset
737
738@subheading STATUS CODES:
739
[16bed8a]740@table @b
[d65d22a0]741@item EFAULT
742The @code{set} argument is an invalid pointer.
743
[ebc67925]744@item EINVAL
[d65d22a0]745The @code{facilityno} argument is not a valid facility.
[16bed8a]746
747@end table
748
[832e33c]749@subheading DESCRIPTION:
750
[d65d22a0]751The @code{log_facilityaddset} function adds the individual
752facility specified by the value of the argument @code{facilityno}
753to the facility set pointed to by the argument @code{set}.
[d1a859c]754
[d65d22a0]755@subheading NOTES:
756
757The @code{_POSIX_LOGGING} feature flag is defined to indicate
758this service is available.
[d1a859c]759
760Applications shall call either @code{log_facilityemptyset} or
761@code{log_facilityfillset} at least once for each object of type
762@code{log_facilityset_t} prior to any other use of that object.  If
763such an object is not initialized in this way, but is nonetheless
[d65d22a0]764supplied as an argument to any of the @code{log_facilityaddset},
[d1a859c]765@code{logfacilitydelset}, @code{log_facilityismember} or
766@code{log_open} functions, the results are undefined.
767
[832e33c]768@page
[ebc67925]769@subsection log_facilitydelset - Manipulate log facility sets
[832e33c]770
771@subheading CALLING SEQUENCE:
772
773@ifset is-C
774@example
[30cc2e0]775#include <evlog.h>
776
[832e33c]777int log_facilitydelset(
[ebc67925]778  log_facility_set_t  *set,
[d65d22a0]779  log_facility_t       facilityno
[832e33c]780);
781@end example
782@end ifset
783
784@ifset is-Ada
785@end ifset
786
787@subheading STATUS CODES:
788
[16bed8a]789@table @b
[d65d22a0]790@item EFAULT
791The @code{set} argument is an invalid pointer.
792
[ebc67925]793@item EINVAL
[d65d22a0]794The @code{facilityno} argument is not a valid facility.
[16bed8a]795
796@end table
797
[832e33c]798@subheading DESCRIPTION:
799
[d65d22a0]800The @code{log_facilitydelset} function deletes the individual
801facility specified by the value of the argument @code{facilityno}
802from the facility set pointed to by the argument @code{set}.
[d1a859c]803
[d65d22a0]804@subheading NOTES:
805
806The @code{_POSIX_LOGGING} feature flag is defined to indicate
807this service is available.
[d1a859c]808
809Applications shall call either @code{log_facilityemptyset} or
810@code{log_facilityfillset} at least once for each object of type
811@code{log_facilityset_t} prior to any other use of that object.  If
812such an object is not initialized in this way, but is nonetheless
[d65d22a0]813supplied as an argument to any of the @code{log_facilityaddset},
[d1a859c]814@code{logfacilitydelset}, @code{log_facilityismember} or
815@code{log_open} functions, the results are undefined.
816
[832e33c]817@page
[ebc67925]818@subsection log_facilityismember - Manipulate log facility sets
[832e33c]819
820@subheading CALLING SEQUENCE:
821
822@ifset is-C
823@example
[30cc2e0]824#include <evlog.h>
825
[832e33c]826int log_facilityismember(
[ebc67925]827  const log_facility_set_t *set,
828  log_facility_t            facilityno,
829  const int                *member
[832e33c]830);
831@end example
832@end ifset
833
834@ifset is-Ada
835@end ifset
836
837@subheading STATUS CODES:
838
[16bed8a]839@table @b
[d65d22a0]840@item EFAULT
841The @code{set} or @code{member} argument is an invalid pointer.
842
[ebc67925]843@item EINVAL
[d65d22a0]844The @code{facilityno} argument is not a valid facility.
[16bed8a]845
846@end table
847
[832e33c]848@subheading DESCRIPTION:
849
[d1a859c]850The @code{log_facilityismember} function tests whether the facility
851specified by the value of the argument @code{facilityno} is a member
852of the set pointed to by the argument @code{set}.  Upon successful
853completion, the @code{log_facilityismember} function either returns
854a value of one to the location specified by @code{member} if the
[d65d22a0]855specified facility is a member of the specified set or value of
856zero to the location specified by @code{member} if the specified
857facility is not a member of the specified set.
[2dd561a3]858
[832e33c]859@subheading NOTES:
860
[d1a859c]861The @code{_POSIX_LOGGING} feature flag is defined to indicate
862this service is available.
863
[d65d22a0]864Applications shall call either @code{log_facilityemptyset} or
865@code{log_facilityfillset} at least once for each object of type
866@code{log_facilityset_t} prior to any other use of that object.  If
867such an object is not initialized in this way, but is nonetheless
868supplied as an argument to any of the @code{log_facilityaddset},
869@code{logfacilitydelset}, @code{log_facilityismember} or
870@code{log_open} functions, the results are undefined.
871
[2a23c28]872@page
873@subsection log_create - Creates a log file
874
875@subheading CALLING SEQUENCE:
876
877@ifset is-C
878@example
[30cc2e0]879#include <evlog.h>
880
[2a23c28]881int log_create(
882  logd_t       *ld,
883  const char   *path,
884);
885@end example
886@end ifset
887
888@ifset is-Ada
889@end ifset
890
891@subheading STATUS CODES:
892
893@table @b
894@item ENOMEM
895The is ????????????
896
897@end table
898
899@subheading DESCRIPTION:
900
[d1a859c]901This function dynamically allocates memory for the @code{ld}, associates
[30cc2e0]902a directory path to the @code{ld}, and provides access permissions to the
[d1a859c]903@code{ld}.
[2a23c28]904
905@subheading NOTES:
906
[d1a859c]907The @code{_POSIX_LOGGING} feature flag is defined to indicate
908this service is available.
909
[2a23c28]910@page
911@subsection log_sys_create - Creates a system log file
912
913@subheading CALLING SEQUENCE:
914
915@ifset is-C
916@example
[30cc2e0]917#include <evlog.h>
918
[2a23c28]919int log_sys_create();
920@end example
921@end ifset
922
923@ifset is-Ada
924@end ifset
925
926@subheading STATUS CODES:
927
928@table @b
929@item EEXIST
930The directory path to the system log already exist.
931
932@end table
933
934@subheading DESCRIPTION:
935
[d1a859c]936This function will create a predefined system log directory path and
937system log file if they do not already exist.
[2a23c28]938
939@subheading NOTES:
940
[d1a859c]941The @code{_POSIX_LOGGING} feature flag is defined to indicate
942this service is available.
Note: See TracBrowser for help on using the repository browser.