diff options
Diffstat (limited to 'contrib/bind/lib/isc/logging.mdoc')
| -rw-r--r-- | contrib/bind/lib/isc/logging.mdoc | 1056 |
1 files changed, 0 insertions, 1056 deletions
diff --git a/contrib/bind/lib/isc/logging.mdoc b/contrib/bind/lib/isc/logging.mdoc deleted file mode 100644 index 8d8d27e..0000000 --- a/contrib/bind/lib/isc/logging.mdoc +++ /dev/null @@ -1,1056 +0,0 @@ -.\" $Id: logging.mdoc,v 8.6 2001/12/28 04:24:23 marka Exp $ -.\" -.\"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 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_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 |
