.\" 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