.\" Id: logging.mdoc,v 1.3 2004/03/09 06:30:08 marka Exp 
.\"
.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
.\" Copyright (c) 1995-1999 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 ISC DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC 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_set_file_owner ,
.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 int
.Fn log_set_file_owner "log_channel chan" "uid_t owner" "gid_t group"
.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.  Also unique to logging channels of type
.Dv log_file
is the
.Fn log_set_file_owner
function, which tells the logging system what user and group ought to own
newly created files (which is only effective if the caller is privileged.)
.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
.Xr 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
.Do
.Ft struct log_channel
.Dc
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