Changeset f8c5bad in rtems


Ignore:
Timestamp:
Sep 21, 1998, 9:31:59 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
98bdf7a
Parents:
af973e57
Message:

Updated file based upon red-lines received.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/eventlog.t

    raf973e57 rf8c5bad  
    4343@subsection Log Files and Events
    4444
    45 The operating system uses a special log file named @code{XXX}. 
     45The operating system uses a special log file named @code{syslog}. 
    4646This log file is called the system log and is automatically created and
    47 tracked by the operating system.  The system log is written to with
    48 the @code{log_write} function.  An alternative log file may be written
    49 using the @code{log_write_any} function.  It is possible to use @code{log_read}
    50 to query the system and @code{log_write_entry} to a non-system log file
    51 to produce a filtered version of the system log.  For example you could
    52 produce a log of all disk controller faults that have occurred. 
     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. 
    5354
    5455A non-system log may be a special log file created by an application to
    5556describe application faults, or a subset of the system log created
    5657by the application. 
     58
     59
     60
     61@subsection Facilities, Severity, & Queries
    5762
    5863A facility is an identification code for a subsystem, device, or
     
    6267subsequent log query.  A log query is used as a filter to
    6368obtain a subset of a given log file.  The log file may be configured
    64 to send out an event ... ???
    65 
    66 XXX Events
    67 
    68 @subsection Queries
     69to send out an event.
    6970
    7071@section Operations
     
    7273@subsection Creating and Writing a non-System Log
    7374
    74 The following snips of code create a non-System log file at /temp/.
    75 A previously read entry and buffer (log_buf) of size readsize are written
    76 into the log.  See the dicussion on opening and reading a log for
    77 how the entry is created.
     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.
    7879
    7980@example
     
    145146
    146147@item EINVAL
    147 The @code{len} argument was non-zero and @code{buf} is NULL.
     148The @code{len} argument was non-zero and @code{buf} is @code{NULL}.
    148149
    149150@item ENOSPC
     
    157158@subheading DESCRIPTION:
    158159
    159 The @code{log_write_any} function writes an event record to the
     160The @code{log_write} function writes an event record to the
    160161system log file.  The event record written consists of the
    161162event attributes specified by the @code{facility}, @code{event_id},
     
    182183
    183184@item log_uid
    184 This is set to the value returned by @code{geteuid}.
     185This is set to the value returned by @code{geteuid()}.
    185186
    186187@item log_gid
    187 This is set to the value returned by @code{getegid}.
     188This is set to the value returned by @code{getegid()}.
    188189
    189190@item log_pid
    190 This is set to the value returned by @code{getpid}.
     191This is set to the value returned by @code{getpid()}.
    191192
    192193@item log_pgrp
    193 This is set to the value returned by @code{getpgrp}.
     194This is set to the value returned by @code{getpgrp()}.
    194195
    195196@item log_time
    196 This is set to the value returned by @code{clock_gettime} for the
    197 CLOCK_REALTIME clock source.
     197This is set to the value returned by @code{clock_gettime()} for the
     198@code{CLOCK_REALTIME clock} source.
    198199
    199200@end table
     
    249250
    250251@item EINVAL
    251 The @code{len} argument was non-zero and @code{buf} is NULL.
     252The @code{len} argument was non-zero and @code{buf} is @code{NULL}.
    252253
    253254@item ENOSPC
     
    261262@subheading DESCRIPTION:
    262263
    263 The @code{log_write_any} function writes an event record to the log file
     264The @code{log_write_any()} function writes an event record to the log file
    264265specified by @code{logdes}.  The event record written consists of the
    265266event attributes specified by the @code{facility}, @code{event_id},
     
    286287
    287288@item log_uid
    288 This is set to the value returned by @code{geteuid}.
     289This is set to the value returned by @code{geteuid()}.
    289290
    290291@item log_gid
    291 This is set to the value returned by @code{getegid}.
     292This is set to the value returned by @code{getegid()}.
    292293
    293294@item log_pid
    294 This is set to the value returned by @code{getpid}.
     295This is set to the value returned by @code{getpid()}.
    295296
    296297@item log_pgrp
    297 This is set to the value returned by @code{getpgrp}.
     298This is set to the value returned by @code{getpgrp()}.
    298299
    299300@item log_time
    300 This is set to the value returned by @code{clock_gettime} for the
    301 CLOCK_REALTIME clock source.
     301This is set to the value returned by @code{clock_gettime()} for the
     302@code{CLOCK_REALTIME} clock source.
    302303
    303304@end table
     
    369370@subheading DESCRIPTION:
    370371
    371 The @code{log_write_entry} function writes an event record
     372The @code{log_write_entry()} function writes an event record
    372373specified by the @code{entry}, @code{buf}, and @code{len} arguments.
    373374Most of the fields of the event record pointed to by @code{entry}
     
    425426
    426427@item  EINTR
    427 A signal interrupted the call to log_open().
     428A signal interrupted the call to @code{log_open()}.
    428429
    429430@item EINVAL
     
    456457@subheading DESCRIPTION:
    457458
    458 The @code{log_open} function establishes the connection between a
     459The @code{log_open()} function establishes the connection between a
    459460log file and a log file descriptor.  It creates an open log file
    460461descriptor that refers to this query stream on the specified log file
    461462The log file descriptor is used by the other log functions to refer
    462463to that log query stream.  The @code{path} argument points to a
    463 pathname for a log file.  A @code{path} argument of NULL specifies
     464pathname for a log file.  A @code{path} argument of @code{NULL} specifies
    464465the current system log file. 
    465466
    466 The @code{query} argument is not NULL, then it points to a log query
     467The @code{query} argument is not @code{NULL}, then it points to a log query
    467468specification that is used to filter the records in the log file on
    468 subsequent @code{log_read} operations.  This restricts the set of
     469subsequent @code{log_read()} operations.  This restricts the set of
    469470event records read using the returned log file descriptor to those
    470471which match the query.  A query match occurs for a given record when
     
    473474in the query.
    474475
    475 If the value of the @code{query} argument is NULL, no query filter
     476If the value of the @code{query} argument is @code{NULL}, no query filter
    476477shall be applied.
    477478
     
    486487can never occur.
    487488
    488 Many error codes that POSIX specifies to be returned by @code{log_open}
    489 should actually be detected by @code{open} and passed back by the
    490 @code{log_open} implementation.  In this implementation, @code{EACCESS},
     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},
    491492@code{EMFILE}, @code{ENAMETOOLONG}, @code{ENFILE}, @code{ENOENT},
    492493and @code{ENOTDIR} are detected in this manner.
     
    552553@subheading DESCRIPTION:
    553554
    554 The @code{log_read} function reads the @code{log_entry}
     555The @code{log_read()} function reads the @code{log_entry}
    555556structure and up to @code{log_len} bytes of data from the next
    556557event record of the log file associated with the open log file
     
    565566the @code{logdes} is set, the event record read will match that query.
    566567
    567 If the @code{log_read} is successful the call stores the actual length
     568If the @code{log_read()} is successful the call stores the actual length
    568569of the data associated with the event record into the location specified by
    569570@code{log_sizeread}.  This number will be less than or equal to
     
    578579event record is returned.  This is an extension to the POSIX specification.
    579580
    580 The POSIX specification specifically allows @code{log_read} to write
     581The POSIX specification specifically allows @code{log_read()} to write
    581582greater than @code{log_len} bytes into @code{log_buf}.  This is highly
    582583undesirable and this implementation will NOT do this.
     
    621622@subheading DESCRIPTION:
    622623
    623 If the argument @code{notification} is not NULL this function registers
     624If the argument @code{notification} is not @code{NULL} this function registers
    624625the calling process to be notified of event records received by the system
    625626log, which match the query parameters associated with the open log descriptor
     
    632633replace the existing notification registration.
    633634
    634 If the @code{notification} argument is NULL and the calling process is
     635If the @code{notification} argument is @code{NULL} and the calling process is
    635636currently registered to be notified for the @code{logdes} log file
    636637descriptor, the existing registration shall be removed.
     
    669670@subheading DESCRIPTION:
    670671
    671 The @code{log_close} function deallocates the open log file descriptor
     672The @code{log_close()} function deallocates the open log file descriptor
    672673indicated by @code{log_des}.
    673674
     
    718719@subheading DESCRIPTION:
    719720
    720 The @code{log_seek} function sets the log file offset of the open
     721The @code{log_seek()} function sets the log file offset of the open
    721722log description associated with the @code{logdes} log file descriptor
    722723to the event record in the log file identified by @code{log_recid}. 
    723724The @code{log_recid} argument is either the record id of a valid event
    724 record or one of the following values, as defined in the header <evlog.h>:
     725record or one of the following values, as defined in the header file
     726@code{<evlog.h>:}
    725727
    726728@table @b
     
    740742this service is available.
    741743
    742 This implementation can not return @code{EINTR}.
    743 
    744 This implementation can not return @code{EINVAL} to indicate that
     744This implementation can not return EINTR.
     745
     746This implementation can not return EINVAL to indicate that
    745747the @code{log_recid} argument is not a valid record id.
    746748
     
    780782@subheading DESCRIPTION:
    781783
    782 The @code{log_severity_before} function compares the severity order
     784The @code{log_severity_before()} function compares the severity order
    783785of the @code{s1} and @code{s2} arguments.  If @code{s1} is of
    784786severity greater than or equal to that of @code{s2}, then this
     
    786788
    787789If either @code{s1} or @code{s2} specify invalid severity values, the
    788 return value of @code{log_severity_before} is unspecified.
     790return value of @code{log_severity_before()} is unspecified.
    789791
    790792@subheading NOTES:
     
    794796
    795797The POSIX specification of the return value for this function is ambiguous.
    796 If @code{EINVAL} is equal to 1 in an implementation, then the application
     798If EINVAL is equal to 1 in an implementation, then the application
    797799can not distinguish between greater than and an error condition.
    798800
     
    825827@subheading DESCRIPTION:
    826828
    827 The @code{log_facilityemptyset} function initializes the facility
     829The @code{log_facilityemptyset()} function initializes the facility
    828830set pointed to by the argument @code{set}, such that all facilities
    829831are excluded.
     
    834836this service is available.
    835837
    836 Applications shall call either @code{log_facilityemptyset} or
    837 @code{log_facilityfillset} at least once for each object of type
     838Applications shall call either @code{log_facilityemptyset()} or
     839@code{log_facilityfillset()} at least once for each object of type
    838840@code{log_facilityset_t} prior to any other use of that object.  If
    839841such an object is not initialized in this way, but is nonetheless
    840 supplied 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.
     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.
    843845
    844846@page
     
    870872@subheading DESCRIPTION:
    871873
    872 The @code{log_facilityfillset} function initializes the facility
     874The @code{log_facilityfillset()} function initializes the facility
    873875set pointed to by the argument @code{set}, such that all facilities
    874876are included.
     
    879881this service is available.
    880882
    881 Applications shall call either @code{log_facilityemptyset} or
    882 @code{log_facilityfillset} at least once for each object of type
     883Applications shall call either @code{log_facilityemptyset()} or
     884@code{log_facilityfillset()} at least once for each object of type
    883885@code{log_facilityset_t} prior to any other use of that object.  If
    884886such an object is not initialized in this way, but is nonetheless
    885 supplied 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.
     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.
    888890
    889891@page
     
    919921@subheading DESCRIPTION:
    920922
    921 The @code{log_facilityaddset} function adds the individual
     923The @code{log_facilityaddset()} function adds the individual
    922924facility specified by the value of the argument @code{facilityno}
    923925to the facility set pointed to by the argument @code{set}.
     
    928930this service is available.
    929931
    930 Applications shall call either @code{log_facilityemptyset} or
    931 @code{log_facilityfillset} at least once for each object of type
     932Applications shall call either @code{log_facilityemptyset()} or
     933@code{log_facilityfillset()} at least once for each object of type
    932934@code{log_facilityset_t} prior to any other use of that object.  If
    933935such an object is not initialized in this way, but is nonetheless
    934 supplied 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.
     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.
    937939
    938940@page
     
    968970@subheading DESCRIPTION:
    969971
    970 The @code{log_facilitydelset} function deletes the individual
     972The @code{log_facilitydelset()} function deletes the individual
    971973facility specified by the value of the argument @code{facilityno}
    972974from the facility set pointed to by the argument @code{set}.
     
    977979this service is available.
    978980
    979 Applications shall call either @code{log_facilityemptyset} or
    980 @code{log_facilityfillset} at least once for each object of type
     981Applications shall call either @code{log_facilityemptyset()} or
     982@code{log_facilityfillset()} at least once for each object of type
    981983@code{log_facilityset_t} prior to any other use of that object.  If
    982984such an object is not initialized in this way, but is nonetheless
    983 supplied 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.
     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.
    986988
    987989@page
     
    10181020@subheading DESCRIPTION:
    10191021
    1020 The @code{log_facilityismember} function tests whether the facility
     1022The @code{log_facilityismember()} function tests whether the facility
    10211023specified by the value of the argument @code{facilityno} is a member
    10221024of the set pointed to by the argument @code{set}.  Upon successful
    1023 completion, the @code{log_facilityismember} function either returns
     1025completion, the @code{log_facilityismember()} function either returns
    10241026a value of one to the location specified by @code{member} if the
    10251027specified facility is a member of the specified set or value of
     
    10321034this service is available.
    10331035
    1034 Applications shall call either @code{log_facilityemptyset} or
    1035 @code{log_facilityfillset} at least once for each object of type
     1036Applications shall call either @code{log_facilityemptyset()} or
     1037@code{log_facilityfillset()} at least once for each object of type
    10361038@code{log_facilityset_t} prior to any other use of that object.  If
    10371039such an object is not initialized in this way, but is nonetheless
    1038 supplied 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
     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
    10441046
    10451047@subheading CALLING SEQUENCE:
     
    10711073@subheading DESCRIPTION:
    10721074
    1073 The @code{log_facilityisvalid} function tests whether the facility
     1075The @code{log_facilityisvalid()} function tests whether the facility
    10741076specified by the value of the argument @code{facilityno} is a valid
    1075 facility number which is less than 32.  Upon successful completion,
    1076 the @code{log_facilityisvalid} function either returns a value of
     1077facility number.  Upon successful completion, the
     1078the @code{log_facilityisvalid()} function either returns a value of
    107710790 if the specified facility is a valid facility or value of EINVAL
    10781080if the specified facility is not a valid facility.
     
    10831085this service is available.
    10841086
    1085 Applications shall call either @code{log_facilityemptyset} or
    1086 @code{log_facilityfillset} at least once for each object of type
     1087Applications shall call either @code{log_facilityemptyset()} or
     1088@code{log_facilityfillset()} at least once for each object of type
    10871089@code{log_facilityset_t} prior to any other use of that object.  If
    10881090such an object is not initialized in this way, but is nonetheless
    1089 supplied 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.
     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.
    10921094
    10931095@page
     
    11141116@table @b
    11151117
    1116 @item
    1117 EEXIST
     1118@item EEXIST
    11181119The @code{path} already exists and O_CREAT and O_EXCL were used.
    11191120
    1120 @item
    1121 EISDIR
     1121@item EISDIR
    11221122The @code{path} refers to a directory and the access requested involved
    11231123writing.
    11241124
    1125 @item
    1126 ETXTBSY
     1125@item ETXTBSY
    11271126The @code{path} refers to an executable image which is currently being 
    11281127executed and write access was requested.
    11291128
    1130 @item
    1131 EFAULT
     1129@item EFAULT
    11321130The @code{path} points outside your accessible address space.
    11331131
    1134 @item
    1135 EACCES
     1132@item EACCES
    11361133The requested access to the file is not allowed, or one of the
    11371134directories in @code{path} did not allow search (execute) permission.
    11381135
    1139 @item
    1140 ENAMETOOLONG
     1136@item ENAMETOOLONG
    11411137The @code{path} was too long.
    11421138
    1143 @item
    1144 ENOENT
     1139@item ENOENT
    11451140A directory component in @code{path} does not exist or is a dangling symbolic
    11461141link.
    11471142
    1148 @item       
    1149 ENOTDIR
     1143@item ENOTDIR
    11501144A component used as a directory in @code{path} is not, in fact, a directory.
    11511145
    1152 @item
    1153 EMFILE
     1146@item EMFILE
    11541147The process already has the maximum number of files open.
    11551148
    1156 @item
    1157 ENFILE
     1149@item ENFILE
    11581150The limit on the total number of files open on the system has been reached.
    11591151
    1160 @item
    1161 ENOMEM
     1152@item ENOMEM
    11621153Insufficient kernel memory was available.
    11631154
    1164 @item
    1165 EROFS
     1155@item EROFS
    11661156The @code{path} refers to a file on a read-only filesystem and write access
    11671157was requested.
    11681158
    1169 @item
    1170 ELOOP
     1159@item ELOOP
    11711160The @code{path} contains a reference to a circular symbolic link, ie a
    11721161symbolic link whose expansion contains a reference to itself.
Note: See TracChangeset for help on using the changeset viewer.