1045 lines
25 KiB
Plaintext
1045 lines
25 KiB
Plaintext
.\" $Id: logging.mdoc,v 8.2 1998/02/06 01:54:34 halley Exp $
|
|
.\"
|
|
.\"Copyright (c) 1995, 1996, 1997, 1998 by Internet Software Consortium
|
|
.\"
|
|
.\"Permission to use, copy, modify, and distribute this software for any
|
|
.\"purpose with or without fee is hereby granted, provided that the above
|
|
.\"copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\"THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM DISCLAIMS
|
|
.\"ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
|
|
.\"OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL INTERNET SOFTWARE
|
|
.\"CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
|
|
.\"DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
|
|
.\"PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
|
|
.\"ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
|
|
.\"SOFTWARE.
|
|
.\"
|
|
.\" The following six UNCOMMENTED lines are required.
|
|
.Dd January 1, 1996
|
|
.\"Os OPERATING_SYSTEM [version/release]
|
|
.Os BSD 4
|
|
.\"Dt DOCUMENT_TITLE [section number] [volume]
|
|
.Dt LOGGING @SYSCALL_EXT@
|
|
.Sh NAME
|
|
.Nm log_open_stream ,
|
|
.Nm log_close_stream ,
|
|
.Nm log_get_stream ,
|
|
.Nm log_get_filename ,
|
|
.Nm log_vwrite ,
|
|
.Nm log_write ,
|
|
.Nm log_new_context ,
|
|
.Nm log_free_context ,
|
|
.Nm log_add_channel ,
|
|
.Nm log_remove_channel ,
|
|
.Nm log_option ,
|
|
.Nm log_category_is_active ,
|
|
.Nm log_new_syslog_channel ,
|
|
.Nm log_new_file_channel ,
|
|
.Nm log_new_null_channel ,
|
|
.Nm log_inc_references ,
|
|
.Nm log_dec_references ,
|
|
.Nm log_free_channel
|
|
.Nd logging system
|
|
.Sh SYNOPSIS
|
|
.Fd #include <isc/logging.h>
|
|
.Ft FILE *
|
|
.Fn log_open_stream "log_channel chan"
|
|
.Ft int
|
|
.Fn log_close_stream "log_channel chan"
|
|
.Ft FILE *
|
|
.Fn log_get_stream "log_channel chan"
|
|
.Ft char *
|
|
.Fn log_get_filename "log_channel chan"
|
|
.Ft void
|
|
.Fn log_vwrite "log_context lc" "int category" "int level" \
|
|
"const char *format" va_list args"
|
|
.Ft void
|
|
.Fn log_write "log_context lc" "int category" "int level" \
|
|
"const char *format" "..."
|
|
.Ft int
|
|
.Fn log_check_channel "log_context lc" "int level" "log_channel chan"
|
|
.Ft int
|
|
.Fn log_check "log_context lc" "int category" "int level"
|
|
.Ft int
|
|
.Fn log_new_context "int num_categories" "char **category_names" \
|
|
"log_context *lc"
|
|
.Ft void
|
|
.Fn log_free_context "log_context lc"
|
|
.Ft int
|
|
.Fn log_add_channel "log_context lc" "int category" "log_channel chan"
|
|
.Ft int
|
|
.Fn log_remove_channel "log_context lc" "int category" "log_channel chan"
|
|
.Ft int
|
|
.Fn log_option "log_context lc" "int option" "int value"
|
|
.Ft int
|
|
.Fn log_category_is_active "log_context lc" "int category"
|
|
.Ft log_channel
|
|
.Fn log_new_syslog_channel "unsigned int flags" "int level" "int facility"
|
|
.Ft log_channel
|
|
.Fn log_new_file_channel "unsigned int flags" "int level" \
|
|
"char *name" "FILE *stream" "unsigned int versions" \
|
|
"unsigned long max_size"
|
|
.Ft log_channel
|
|
.Fn log_new_null_channel "void"
|
|
.Ft int
|
|
.Fn log_inc_references "log_channel chan"
|
|
.Ft int
|
|
.Fn log_dec_references "log_channel chan"
|
|
.Ft int
|
|
.Fn log_free_channel "log_channel chan"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Sy ISC
|
|
.Nm logging library
|
|
is flexible logging system which is based upon a set of concepts:
|
|
.Nm logging channels ,
|
|
.Nm categories ,
|
|
and
|
|
.Nm logging contexts .
|
|
.Pp
|
|
The basic building block is the
|
|
.Dq Nm logging channel ,
|
|
which includes a
|
|
.Nm priority
|
|
(logging level), which type of logging is to occur, and other
|
|
flags and information associated with technical aspects of the logging.
|
|
The set of priorities which are supported is shown below, in the section
|
|
.Sx Message Priorities .
|
|
A priority sets a threshold for message logging; a logging channel will
|
|
.Em only
|
|
log those messages which are
|
|
.Em at least as important
|
|
as its priority indicates. (The fact that
|
|
.Dq more important
|
|
means
|
|
.Dq more negative ,
|
|
under the current scheme, is an implementation detail; if a channel has
|
|
a priority of
|
|
.Dv log_error ,
|
|
then it will
|
|
.Em not
|
|
log messages with the
|
|
.Dv log_warning
|
|
priority, but it
|
|
.Em will
|
|
log messages with the
|
|
.Dv log_error
|
|
or
|
|
.Dv log_critical
|
|
priority.)
|
|
.Pp
|
|
The
|
|
.Nm logging channel
|
|
also has an indication of the type of logging performed. Currently,
|
|
the supported
|
|
.Nm logging types
|
|
include (see also
|
|
.Sx Logging Types ,
|
|
below):
|
|
.Bl -tag -width "log_syslog" -compact -offset indent
|
|
.It Dv log_syslog
|
|
for
|
|
.Xr syslog 3 Ns -style
|
|
logging
|
|
.It Dv log_file
|
|
for use of a file
|
|
.It Dv log_null
|
|
for
|
|
.Em no
|
|
logging
|
|
.El
|
|
A new logging channel is created by calling either
|
|
.Fn log_new_syslog_channel ,
|
|
.Fn log_new_file_channel ,
|
|
or
|
|
.Fn log_new_null_channel ,
|
|
respectively.
|
|
When a channel is no longer to be used, it can be freed using
|
|
.Fn log_free_channel .
|
|
.Pp
|
|
Both
|
|
.Dv log_syslog
|
|
and
|
|
.Dv log_file
|
|
channel types can include more information; for instance, a
|
|
.Dv log_syslog Ns -type
|
|
channel allows the specification of a
|
|
.Xr syslog 3 Ns -style
|
|
.Dq facility ,
|
|
and a
|
|
.Dv log_file Ns -type
|
|
channels allows the caller to set a maximum file size and number
|
|
of versions. (See
|
|
.Fn log_new_syslog_channel
|
|
or
|
|
.Fn log_new_file_channel ,
|
|
below.)
|
|
Additionally, once a logging channel of type
|
|
.Dv log_file
|
|
is defined, the functions
|
|
.Fn log_open_stream
|
|
and
|
|
.Fn log_close_stream
|
|
can open or close the stream associated with the logging channel's logging
|
|
filename. The
|
|
.Fn log_get_stream
|
|
and
|
|
.Fn log_get_filename
|
|
functions return the stream or filename, respectively, of such a logging
|
|
channel.
|
|
.Pp
|
|
Callers provide
|
|
.Dq Nm categories ,
|
|
determining both the number of such categories and any (optional) names.
|
|
Categories are like array indexes in C; if the caller declares
|
|
.Dq Va n
|
|
categories, then they are considered to run from 0 to
|
|
.Va n-1 ;
|
|
with this scheme, a category number would be invalid if it were negative or
|
|
greater than/equal to
|
|
.Va n .
|
|
Each category can have its own list of
|
|
.Nm logging channels
|
|
associated with it; we say that such a channel is
|
|
.Dq in
|
|
the particular category.
|
|
.Sy NOTE:
|
|
Individual logging channels can appear in more than one category.
|
|
.Pp
|
|
A
|
|
.Dq Nm logging context
|
|
is the set of all
|
|
.Nm logging channels
|
|
associated with the context's
|
|
.Nm categories;
|
|
thus, a particular
|
|
.Nm category
|
|
scheme is associated with a particular
|
|
.Nm logging context.
|
|
.Sy NOTE:
|
|
A logging channel may appear in more than one logging context, and in
|
|
multiple categories within each logging context.
|
|
.Pp
|
|
Use
|
|
.Fn log_add_channel
|
|
and
|
|
.Fn log_remove_channel
|
|
to add or remove a logging channel to some category in a logging context.
|
|
To see if a given category in a logging context is being used, use the
|
|
Boolean test
|
|
.Fn log_category_is_active .
|
|
.Pp
|
|
A
|
|
.Nm logging context
|
|
can also have a
|
|
.Nm priority
|
|
(logging level)
|
|
and various flags associated with the whole context; in order to alter the
|
|
flags or change the priority of a context, use
|
|
.Fn log_option .
|
|
.Ss Message Priorities
|
|
Currently, five
|
|
.Nm priorities
|
|
(logging levels) are supported (they can also be found in the header file):
|
|
.Bd -literal -offset indent
|
|
#define log_critical (-5)
|
|
#define log_error (-4)
|
|
#define log_warning (-3)
|
|
#define log_notice (-2)
|
|
#define log_info (-1)
|
|
.Ed
|
|
.Pp
|
|
In the current implementation, logging messages which have a level greater
|
|
than 0 are considered to be debugging messages.
|
|
.Ss Logging Types
|
|
The three different
|
|
.Nm logging types
|
|
currently supported are different values of the enumerated type
|
|
.Ft log_output_type
|
|
(these are also listed in the header file):
|
|
.Bd -literal -offset indent
|
|
typedef enum { log_syslog, log_file, log_null } log_output_type;
|
|
.Ed
|
|
.Ss Logging Channel Flags
|
|
There are several flags which can be set on a logging channel; the flags
|
|
and their meanings are as follows (they are also found in the header file):
|
|
.Bl -tag -width "LOG_USE_CONTEXT_LEVEL " -offset indent
|
|
.It Dv LOG_CHANNEL_BROKEN
|
|
This is set only when some portion of
|
|
.Fn log_open_stream
|
|
fails:
|
|
.Xr open 2
|
|
or
|
|
.Xr fdopen 3
|
|
fail;
|
|
.Xr stat 2
|
|
fails in a
|
|
.Dq bad
|
|
way; versioning or truncation is requested on a non-normal file.
|
|
.It Dv LOG_CHANNEL_OFF
|
|
This is set for channels opened by
|
|
.Fn log_new_null_channel .
|
|
.It Dv LOG_CLOSE_STREAM
|
|
If this flag is set, then
|
|
.Fn log_free_channel
|
|
will free a
|
|
.No non- Dv NULL
|
|
stream of a logging channel which is being
|
|
.Xr free 3 Ns -d
|
|
(if the logging channel is of type
|
|
.Dv log_file ,
|
|
of course).
|
|
.It Dv LOG_PRINT_CATEGORY
|
|
If set,
|
|
.Fn log_vwrite
|
|
will insert the category name, if available, into logging messages which are
|
|
logged to channels of type
|
|
.Dv log_syslog
|
|
or
|
|
.Dv log_file .
|
|
.It Dv LOG_PRINT_LEVEL
|
|
If set,
|
|
.Fn log_vwrite
|
|
will insert a string identifying the message priority level into the
|
|
information logged to channels of type
|
|
.Dv log_syslog
|
|
or
|
|
.Dv log_file .
|
|
.It Dv LOG_REQUIRE_DEBUG
|
|
Only log debugging messages (i.e., those with a priority greater than zero).
|
|
.It Dv LOG_TIMESTAMP
|
|
If set,
|
|
.Fn log_vwrite
|
|
will insert a timestamp into logging messages which are logged to channels of
|
|
type
|
|
.Dv log_syslog
|
|
or
|
|
.Dv log_file .
|
|
.It Dv LOG_TRUNCATE
|
|
Truncate logging file when re-opened (
|
|
.Fn log_open_stream
|
|
will
|
|
.Xr unlink 2
|
|
the file and then
|
|
.Xr open 2
|
|
a new file of the same name with the
|
|
.Dv O_EXCL
|
|
bit set).
|
|
.It Dv LOG_USE_CONTEXT_LEVEL
|
|
Use the logging context's priority or logging level, rather than the logging
|
|
channel's own priority. This can be useful for those channels which are
|
|
included in multiple logging contexts.
|
|
.El
|
|
.Ss FUNCTION DESCRIPTIONS
|
|
The function
|
|
.Fn log_open_stream
|
|
is for use with channels which log to a file; i.e., logging channels with a
|
|
.Va type
|
|
field set to
|
|
.Dq Dv log_file .
|
|
If the logging channel pointed to by
|
|
.Dq Fa chan
|
|
is valid, it attempts to open (and return) the stream associated with that
|
|
channel. If the stream is already opened, then it is returned; otherwise,
|
|
.Xr stat 2
|
|
is used to test the filename for the stream.
|
|
.Pp
|
|
At this point, if the logging file is supposed to have different
|
|
.Va versions
|
|
(i.e., incremented version numbers; higher numbers indicate older versions
|
|
of the logging file). If so, then any existing versions are
|
|
.Xr rename 2 Ns -d
|
|
to have one version-number higher than previously, and the
|
|
.Dq current
|
|
filename for the stream is set to the
|
|
.Dq \&.0
|
|
form of the name. Next, if the logging file is supposed to be truncated
|
|
(i.e., the
|
|
.Dv LOG_TRUNCATE
|
|
bit of the
|
|
.Va flags
|
|
field of the logging channel structure is set), then any file with the
|
|
.Dq current
|
|
filename for the stream is
|
|
.X4 unlink 2 Ns -d .
|
|
.Sy NOTE:
|
|
If the logging file is
|
|
.Em not
|
|
a regular file, and either of the above operations (version numbering
|
|
or truncation) is supposed to take place, a
|
|
.Dv NULL
|
|
file pointer is returned.
|
|
.Pp
|
|
Finally, the filename associated with the logging channel is
|
|
.Xr open 2 Ns -d
|
|
using the appropriate flags and a mode which sets the read/write permissions
|
|
for the user, group, and others. The file descriptor returned by
|
|
.Xr open 2
|
|
is then passed to
|
|
.Xr fopen 3 ,
|
|
with the append mode set, and the stream returned by this call is stored
|
|
in the
|
|
.Fa chan
|
|
structure and returned.
|
|
.Pp
|
|
If
|
|
.Fn log_open_stream
|
|
fails at any point, then the
|
|
.Dv LOG_CHANNEL_BROKEN
|
|
bit of the
|
|
.Va flags
|
|
field of the logging channel pointed to by
|
|
.Fa chan
|
|
is set, a
|
|
.Dv NULL
|
|
is returned, and
|
|
.Va errno
|
|
contains pertinent information.
|
|
.Pp
|
|
The
|
|
.Fn log_close_stream
|
|
function closes the stream associated with the logging channel pointed to by
|
|
.Dq Fa chan
|
|
(if
|
|
.Fa chan
|
|
is valid and the stream exists and can be closed properly by
|
|
.Xr fclose 3 ) .
|
|
The stream is set to
|
|
.Dv NULL
|
|
even if the call to
|
|
.Xr fclose 3
|
|
fails.
|
|
.Pp
|
|
The function
|
|
.Fn log_get_stream
|
|
returns the stream associated with the logging channel pointed to by
|
|
.Dq Fa chan ,
|
|
if it is
|
|
.No non- Ns Dv NULL
|
|
and specifies a logging channel which has a
|
|
.Dv FILE *
|
|
or stream associated with it.
|
|
.Pp
|
|
The
|
|
.Fn log_get_filename
|
|
function returns the name of the file associated with the logging channel
|
|
pointed to by
|
|
.Dq Fa chan ,
|
|
if it is
|
|
.No non- Ns Dv NULL
|
|
and specifies a logging channel which has a file associated with it.
|
|
.Pp
|
|
The
|
|
.Fn log_vwrite
|
|
function performs the actual logging of a message to the various logging
|
|
channels of a logging context
|
|
.Fa lc .
|
|
The message consists of an
|
|
.Xr fprint 3 Ns -style
|
|
.Fa format
|
|
and its associated
|
|
.Fa args
|
|
(if any); it will be written to all logging channels in the given
|
|
.Fa category
|
|
which have a priority set to
|
|
.Fa level
|
|
or any
|
|
.Em less important
|
|
priority value. If the
|
|
.Fa category
|
|
is not valid or has no logging channels, then the category defaults to 0.
|
|
.Pp
|
|
There are a number of conditions under which a call to
|
|
.Fn log_vwrite
|
|
will not result in actually logging the message: if there is no logging channel
|
|
at even the default category (0), or if a given channel is either
|
|
.Dq broken
|
|
or
|
|
.Dq off
|
|
(i.e., its flags have
|
|
.Dv LOG_CHANNEL_BROKEN
|
|
or
|
|
.Dv LOG_CHANNEL_OFF
|
|
set, respectively), or if the logging channel channel is of type
|
|
.Dv log_null .
|
|
Additionally, if the logging channel's flag has
|
|
.Dv LOG_REQUIRE_DEBUG
|
|
set and the message is not a debugging message (i.e., has a level greater
|
|
than 0), then it will not be logged.
|
|
Finally, if the message's priority is less important than the
|
|
channel's logging level (the priority threshold), will not be logged.
|
|
.Sy NOTE:
|
|
If a logging channel's flag has
|
|
.Dv LOG_USE_CONTEXT_LEVEL
|
|
set, it will use the logging context's priority, rather than its own.
|
|
.Pp
|
|
If all of these hurdles are passed, then only
|
|
.Dv log_syslog
|
|
and
|
|
.Dv log_file
|
|
channels actually can have logging. For channels which use
|
|
.Xr syslog 3 ,
|
|
the channel's
|
|
.Xr syslog 3
|
|
facility is used in conjunction with a potentially modified form of the
|
|
message's priority level, since
|
|
.Xr syslog 3
|
|
has its own system of priorities
|
|
.Pq Pa /usr/include/syslog.h .
|
|
All debug messages (priority >= 0) are mapped to
|
|
.Xr syslog 3 Ns 's
|
|
.Dv LOG_DEBUG
|
|
priority, all messages
|
|
.Dq more important
|
|
than
|
|
.Dv log_critical
|
|
are mapped to
|
|
.Dv LOG_CRIT ,
|
|
and the priorities corresponding to the ones listed in the section
|
|
.Sx Message Priorities
|
|
are given the obvious corresponding
|
|
.Xr syslog 3
|
|
priority.
|
|
.Pp
|
|
For
|
|
.Dv log_file
|
|
type logging channels, if the file size is greater than the maximum file
|
|
size, then no logging occurs. (The same thing happens if a
|
|
.Dv NULL
|
|
stream is encountered and
|
|
.Fn log_open_stream
|
|
fails to open the channel's stream.)
|
|
.Pp
|
|
For both logging to normal files and logging via
|
|
.Xr syslog 3 ,
|
|
the value of the flags
|
|
.Dv LOG_TIMESTAMP ,
|
|
.Dv LOG_PRINT_CATEGORY ,
|
|
and
|
|
.Dv LOG_PRINT_LEVEL
|
|
are used in determining whether or not these items are included in the logged
|
|
information.
|
|
.Pp
|
|
The
|
|
.Fn log_write
|
|
function is merely a front-end to a call to
|
|
.Fn log_vwrite ;
|
|
see the description of that function, above, for more information.
|
|
.Pp
|
|
.Fn log_check
|
|
and
|
|
.Fn log_check_channel
|
|
are used to see if a contemplated logging call will actually generate any
|
|
output, which is useful when creating a log message involves non-trivial
|
|
work.
|
|
.Fn log_check
|
|
will return non-zero if a call to
|
|
.Fn log_vwrite
|
|
with the given
|
|
.Fa category
|
|
and
|
|
.Fa level
|
|
would generate output on any channels, and zero otherwise.
|
|
.Fn log_check_channel
|
|
will return non-zero if writing to the
|
|
.Fa chan
|
|
at the given
|
|
.Fa level
|
|
would generate output.
|
|
.Pp
|
|
The function
|
|
.Fn log_new_context
|
|
creates a new
|
|
.Nm logging context ,
|
|
and stores this in the
|
|
.Dq Va opaque
|
|
field of the argument
|
|
.Dq Fa lc ,
|
|
and opaque structure used internally. This new
|
|
.Nm context
|
|
will include the
|
|
.Dq Fa num_categories
|
|
and
|
|
.Dq Fa category_names
|
|
which are supplied; the latter can be
|
|
.Dv NULL .
|
|
.Sy NOTE:
|
|
Since
|
|
.Dq Fa category_names
|
|
is used directly, it
|
|
.Em must not
|
|
be freed by the caller, if it is
|
|
.No non- Ns Dv NULL .
|
|
The initial logging flags and priority are both set to zero.
|
|
.Pp
|
|
The
|
|
.Fn log_free_context
|
|
function is used to free the opaque structure
|
|
.Dq Va lc.opaque
|
|
and its components.
|
|
.Sy NOTE:
|
|
The
|
|
.Dq Va opaque
|
|
field of
|
|
.Dq Fa lc
|
|
.Em must
|
|
be
|
|
.No non- Ns Dv NULL .
|
|
For each of the various
|
|
.Dq categories
|
|
(indicated by the
|
|
.Dq Va num_categories
|
|
which were in the corresponding call to
|
|
.Fn log_new_context )
|
|
associated with the given
|
|
.Nm logging context ,
|
|
.Em all
|
|
of the
|
|
.Nm logging channels
|
|
are
|
|
.Xr free 3 Ns -d .
|
|
The opaque structure itself is then
|
|
.Xr free 3 Ns -d ,
|
|
and
|
|
.Dq Va lc.opaque
|
|
is set to
|
|
.Dv NULL .
|
|
.Pp
|
|
.Sy NOTE:
|
|
The function
|
|
.Fn log_free_context
|
|
does
|
|
.Em not
|
|
free the memory associated with
|
|
.Fa category_names ,
|
|
since the logging library did not allocate the memory for it, originally;
|
|
it was supplied in the call to
|
|
.Fn log_new_context .
|
|
.Pp
|
|
The function
|
|
.Fn log_add_channel
|
|
adds the
|
|
.Nm logging channel
|
|
.Dq Fa chan
|
|
to the list of logging channels in the given
|
|
.Fa category
|
|
of the
|
|
.Nm logging context
|
|
.Dq Fa lc .
|
|
No checking is performed to see whether or not
|
|
.Fa chan
|
|
is already present in the given
|
|
.Fa category ,
|
|
so multiple instances in a single
|
|
.Fa category
|
|
can occur (but see
|
|
.Fn log_remove_channel ,
|
|
below).
|
|
.Pp
|
|
The
|
|
.Fn log_remove_channel
|
|
function
|
|
removes
|
|
.Em all
|
|
occurrences of the
|
|
.Nm logging channel
|
|
.Dq Fa chan
|
|
from the list of logging channels in the given
|
|
.Fa category
|
|
of the
|
|
.Nm logging context
|
|
.Dq Fa lc .
|
|
It also attempts to free the channel by calling
|
|
.Fn log_free_channel
|
|
(see its description, below).
|
|
.Pp
|
|
The
|
|
.Fn log_option
|
|
function is used to change the
|
|
.Fa option
|
|
of the indicated logging context
|
|
.Fa lc
|
|
to the given
|
|
.Fa value .
|
|
The
|
|
.Fa option
|
|
can be either
|
|
.Dv LOG_OPTION_LEVEL
|
|
or
|
|
.Dv LOG_OPTION_DEBUG ;
|
|
in the first case, the log context's debugging level is reset to the
|
|
indicated level. If the
|
|
.Fa option
|
|
is
|
|
.Dv LOG_OPTION_DEBUG ,
|
|
then a non-zero
|
|
.Fa value
|
|
results in setting the debug flag of the logging context, while a zero
|
|
.Fa value
|
|
means that the debug flag is reset.
|
|
.Pp
|
|
The
|
|
.Fn log_category_is_active
|
|
test returns a 1 if the given
|
|
.Fa category
|
|
of the indicated logging context
|
|
.Fa lc
|
|
has at least one logging channel, and 0, otherwise.
|
|
.Pp
|
|
The functions
|
|
.Fn log_new_syslog_channel ,
|
|
.Fn log_new_file_channel ,
|
|
and
|
|
.Fn log_new_null_channel
|
|
create a new channel of the type specified (thus, the difference in arguments);
|
|
the
|
|
.Dq Va type
|
|
field of the new
|
|
.Dq Ft struct log_channel
|
|
is always set to the appropriate value.
|
|
.Pp
|
|
The
|
|
.Fn log_new_syslog_channel
|
|
function
|
|
.Xr malloc 3 Ns -s
|
|
a new
|
|
.Ft struct log_channel
|
|
of
|
|
.Va type
|
|
.Dv log_syslog ,
|
|
i.e., a logging channel which will use
|
|
.Xr syslog 3 .
|
|
The new structure is filled out with the
|
|
.Dq Fa flags ,
|
|
.Dq Fa level ,
|
|
and
|
|
.Dq Fa facility
|
|
which are given; the
|
|
.Va references
|
|
field is initialized to zero.
|
|
See
|
|
.Sx Logging Channel Flags
|
|
and
|
|
.Sx Message Priorities ,
|
|
above, or the header file for information about acceptable values for
|
|
.Dq Fa flags ,
|
|
and
|
|
.Dq Fa level .
|
|
The
|
|
.Dq Fa facility .
|
|
can be any valid
|
|
.Xr syslog 3
|
|
facility; see the appropriate system header file or manpage for more
|
|
information.
|
|
.Pp
|
|
.Ft log_channel
|
|
.Fn log_new_file_channel "unsigned int flags" "int level" \
|
|
"char *name" "FILE *stream" "unsigned int versions" \
|
|
"unsigned long max_size"
|
|
.Pp
|
|
.Fn log_new_null_channel
|
|
.Pp
|
|
The functions
|
|
.Fn log_inc_references
|
|
and
|
|
.Fn log_dec_references
|
|
increment or decrements, respectively, the
|
|
.Va references
|
|
field of the logging channel pointed to by
|
|
.Dq Fa chan ,
|
|
if it is a valid channel (and if the
|
|
.Va references
|
|
field is strictly positive, in the case of
|
|
.Fn log_dec_references ) .
|
|
These functions are meant to track changes in the number of different clients
|
|
which refer to the given logging channel.
|
|
.Pp
|
|
The
|
|
.Fn log_free_channel
|
|
function frees the
|
|
field of the logging channel pointed to by
|
|
.Dq Fa chan
|
|
if there are no more outstanding references to it. If the channel uses a file,
|
|
the stream is
|
|
.Xr fclose 3 Ns -d
|
|
(if the
|
|
.Dv LOG_CLOSE_STREAM
|
|
flag is set), and the filename, if
|
|
.No non- Ns Dv NULL ,
|
|
is
|
|
.Xr free 3 Ns -d
|
|
before
|
|
.Dq Fa chan
|
|
is
|
|
.Xr free 3 Ns -d .
|
|
.Pp
|
|
.\" The following requests should be uncommented and
|
|
.\" used where appropriate. This next request is
|
|
.\" for sections 2 and 3 function return values only.
|
|
.Sh RETURN VALUES
|
|
.\" This next request is for sections 1, 6, 7 & 8 only
|
|
.Bl -tag -width "log_category_is_active()"
|
|
.It Fn log_open_stream
|
|
.Dv NULL
|
|
is returned under any of several error conditions:
|
|
a) if
|
|
.Dq Fa chan
|
|
is either
|
|
.Dv NULL
|
|
or a
|
|
.No non- Ns Dv log_file
|
|
channel
|
|
.Pq Va errno No is set to Dv EINVAL ;
|
|
b) if either versioning or truncation is requested for a non-normal file
|
|
.Pq Va errno No is set to Dv EINVAL ;
|
|
c) if any of
|
|
.Xr stat 2 ,
|
|
.Xr open 2 ,
|
|
or
|
|
.Xr fdopen 3
|
|
fails
|
|
.Po Va errno
|
|
is set by the call which failed
|
|
.Pc .
|
|
If some value other than
|
|
.Dv NULL
|
|
is returned, then it is a valid logging stream (either newly-opened or
|
|
already-open).
|
|
.It Fn log_close_stream
|
|
-1 if the stream associated with
|
|
.Dq Fa chan
|
|
is
|
|
.No non- Ns Dv NULL
|
|
and the call to
|
|
.Xr fclose 3
|
|
fails.
|
|
0 if successful or the logging channel pointed to by
|
|
.Dq Fa chan
|
|
is invalid (i.e.,
|
|
.Dv NULL
|
|
or not a logging channel which has uses a file); in the latter case,
|
|
.Va errno
|
|
is set to
|
|
.Dv EINVAL .
|
|
.It Fn log_get_stream
|
|
.Dv NULL
|
|
under the same conditions as those under which
|
|
.Fn log_close_stream ,
|
|
above, returns 0 (including the setting of
|
|
.Va errno ) .
|
|
Otherwise, the stream associated with the logging channel is returned.
|
|
.It Fn log_get_filename
|
|
.Dv NULL
|
|
under the same conditions as those under which
|
|
.Fn log_close_stream ,
|
|
above, returns 0 (including the setting of
|
|
.Va errno ) .
|
|
Otherwise, the name of the file associated with the logging channel is
|
|
returned.
|
|
.It Fn log_new_context
|
|
-1 if
|
|
.Xr malloc 3
|
|
fails
|
|
.Pq with Va errno No set to Dv ENOMEM .
|
|
Otherwise, 0, with
|
|
.Dq Va lc->opaque
|
|
containing the new structures and information.
|
|
.It Fn log_add_channel
|
|
-1 if
|
|
a) either
|
|
.Dq Va lc.opaque
|
|
is
|
|
.Dv NULL
|
|
or
|
|
.Fa category
|
|
is invalid (negative or greater than or equal to
|
|
.Va lcp->num_categories ), with
|
|
.Va errno
|
|
set to
|
|
.Dv EINVAL ;
|
|
b)
|
|
.Xr malloc 3
|
|
fails
|
|
.Pq with Va errno No set to Dv ENOMEM .
|
|
Otherwise, 0.
|
|
.It Fn log_remove_channel
|
|
-1 if
|
|
a) either
|
|
.Dq Va lc.opaque
|
|
is
|
|
.Dv NULL
|
|
or
|
|
.Fa category
|
|
is invalid, as under failure condition a) for
|
|
.Fn log_add_channel ,
|
|
above, including the setting of
|
|
.Va errno ;
|
|
b) no channel numbered
|
|
.Fa chan
|
|
is found in the logging context indicated by
|
|
.Fa lc
|
|
.Pq with Va errno No set to Dv ENOENT .
|
|
Otherwise, 0.
|
|
.It Fn log_option
|
|
-1 if
|
|
a)
|
|
.Dq Va lc.opaque
|
|
is
|
|
.Dv NULL ,
|
|
b)
|
|
.Fa option
|
|
specifies an unknown logging option ;
|
|
in either case,
|
|
.Va errno
|
|
is set to
|
|
.Dv EINVAL .
|
|
Otherwise, 0.
|
|
.It Fn log_category_is_active
|
|
-1 if
|
|
.Dq Va lc.opaque
|
|
is
|
|
.Dv NULL
|
|
.Pq with Va errno No set to Dv EINVAL ;
|
|
1 if the
|
|
.Fa category
|
|
number is valid and there are logging channels in this
|
|
.Fa category
|
|
within the indicated logging context; 0 if the
|
|
.Fa category
|
|
number is invalid or there are no logging channels in this
|
|
.Fa category
|
|
within the indicated logging context.
|
|
.It Fn log_new_syslog_channel
|
|
.Dv NULL
|
|
if
|
|
.Xr malloc 3
|
|
fails
|
|
.Pq with Va errno No set to ENOMEM ;
|
|
otherwise, a valid
|
|
.Dv log_syslog Ns -type
|
|
.Ft log_channel .
|
|
.It Fn log_new_file_channel
|
|
.Dv NULL
|
|
if
|
|
.Xr malloc 3
|
|
fails
|
|
.Pq with Va errno No set to ENOMEM ;
|
|
otherwise, a valid
|
|
.Dv log_file Ns -type
|
|
.Ft log_channel .
|
|
.It Fn log_new_null_channel
|
|
.Dv NULL
|
|
if
|
|
.Xr malloc 3
|
|
fails
|
|
.Pq with Va errno No set to ENOMEM ;
|
|
otherwise, a valid
|
|
.Dv log_null Ns -type
|
|
.Ft log_channel .
|
|
.It Fn log_inc_references
|
|
-1 if
|
|
.Dq Fa chan
|
|
is
|
|
.Dv NULL
|
|
.Pq with Va errno set to Dv EINVAL .
|
|
Otherwise, 0.
|
|
.It Fn log_dec_references
|
|
-1 if
|
|
.Dq Fa chan
|
|
is
|
|
.Dv NULL
|
|
or its
|
|
.Va references
|
|
field is already <= 0
|
|
.Pq with Va errno set to Dv EINVAL .
|
|
Otherwise, 0.
|
|
.It Fn log_free_channel
|
|
-1 under the same conditions as
|
|
.Fn log_dec_references ,
|
|
above, including the setting of
|
|
.Va errno ;
|
|
0 otherwise.
|
|
.El
|
|
.\" .Sh ENVIRONMENT
|
|
.Sh FILES
|
|
.Bl -tag -width "isc/logging.h"
|
|
.It Pa isc/logging.h
|
|
include file for logging library
|
|
.It Pa syslog.h
|
|
.Xr syslog 3 Ns -style
|
|
priorities
|
|
.El
|
|
.\" .Sh EXAMPLES
|
|
.\" This next request is for sections 1, 6, 7 & 8 only
|
|
.\" (command return values (to shell) and
|
|
.\" fprintf/stderr type diagnostics)
|
|
.\" .Sh DIAGNOSTICS
|
|
.\" The next request is for sections 2 and 3 error
|
|
.\" and signal handling only.
|
|
.Sh ERRORS
|
|
This table shows which functions can return the indicated error in the
|
|
.Va errno
|
|
variable; see the
|
|
.Sx RETURN VALUES
|
|
section, above, for more information.
|
|
.Bl -tag -width "(any0other0value)0"
|
|
.It Dv EINVAL
|
|
.Fn log_open_stream ,
|
|
.Fn log_close_stream ,
|
|
.Fn log_get_stream ,
|
|
.Fn log_get_filename ,
|
|
.Fn log_add_channel ,
|
|
.Fn log_remove_channel ,
|
|
.Fn log_option ,
|
|
.Fn log_category_is_active ,
|
|
.Fn log_inc_references ,
|
|
.Fn log_dec_references ,
|
|
.Fn log_free_channel .
|
|
.It Dv ENOENT
|
|
.Fn log_remove_channel .
|
|
.It Dv ENOMEM
|
|
.Fn log_new_context ,
|
|
.Fn log_add_channel ,
|
|
.Fn log_new_syslog_channel ,
|
|
.Fn log_new_file_channel ,
|
|
.Fn log_new_null_channel .
|
|
.It (any other value)
|
|
returned via a pass-through of an error code from
|
|
.Xr stat 2 ,
|
|
.Xr open 2 ,
|
|
or
|
|
.Xr fdopen 3 ,
|
|
which can occur in
|
|
.Fn log_open_stream
|
|
and functions which call it
|
|
.Pq currently, only Fn log_vwrite .
|
|
.El
|
|
.Pp
|
|
Additionally,
|
|
.Fn log_vwrite
|
|
and
|
|
.Fn log_free_context
|
|
will fail via
|
|
.Fn assert
|
|
if
|
|
.Dq Va lc.opaque
|
|
is
|
|
.Dv NULL .
|
|
The function
|
|
.Fn log_vwrite
|
|
can also exit with a critical error logged via
|
|
.Xr syslog 3
|
|
indicating a memory overrun
|
|
.Sh SEE ALSO
|
|
.Xr @INDOT@named @SYS_OPS_EXT@ ,
|
|
.Xr syslog 3 .
|
|
The HTML documentation includes a file,
|
|
.Pa logging.html ,
|
|
which has more information about this logging system.
|
|
.\" .Sh STANDARDS
|
|
.\" .Sh HISTORY
|
|
.Sh AUTHORS
|
|
Bob Halley...TODO
|
|
.\" .Sh BUGS
|