.\" $Id: logging.mdoc,v 1.1.2.1.10.1 2004/03/09 08:33:43 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 DESCRIPTIONThe.Sy ISC.Nm logging libraryis flexible logging system which is based upon a set of concepts:.Nm logging channels ,.Nm categories ,and .Nm logging contexts ..PpThe basic building block is the.Dq Nm logging channel , which includes a .Nm priority (logging level), which type of logging is to occur, and otherflags 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 onlylog those messages which are .Em at least as importantas its priority indicates.  (The fact that .Dq more importantmeans .Dq more negative ,under the current scheme, is an implementation detail; if a channel hasa priority of.Dv log_error ,then it will.Em notlog messages with the.Dv log_warningpriority, but it.Em willlog messages with the.Dv log_erroror .Dv log_criticalpriority.).PpThe.Nm logging channelalso 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_syslogfor .Xr syslog 3 Ns -stylelogging.It Dv log_filefor use of a file.It Dv log_nullfor .Em nologging.ElA 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 ..PpBoth .Dv log_syslogand.Dv log_filechannel 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 -typechannels allows the caller to set a maximum file size and numberof versions.  (See .Fn log_new_syslog_channelor.Fn log_new_file_channel ,below.)Additionally, once a logging channel of type.Dv log_fileis defined, the functions.Fn log_open_streamand .Fn log_close_streamcan open or close the stream associated with the logging channel's loggingfilename.  The.Fn log_get_streamand.Fn log_get_filenamefunctions return the stream or filename, respectively, of such a logging channel.  Also unique to logging channels of type.Dv log_fileis the.Fn log_set_file_ownerfunction, which tells the logging system what user and group ought to ownnewly created files (which is only effective if the caller is privileged.).PpCallers 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 ncategories, 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..PpA.Dq Nm logging contextis 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..PpUse .Fn log_add_channeland.Fn log_remove_channelto 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 theBoolean test.Fn log_category_is_active ..PpA .Nm logging contextcan also have a .Nm priority(logging level)and various flags associated with the whole context; in order to alter theflags or change the priority of a context, use.Fn log_option ..Ss Message PrioritiesCurrently, 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.PpIn the current implementation, logging messages which have a level greaterthan 0 are considered to be debugging messages..Ss Logging TypesThe 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 indenttypedef 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_BROKENThis is set only when some portion of .Fn log_open_streamfails:.Xr open 2 or.Xr fdopen 3  fail;.Xr stat 2fails in a.Dq badway; versioning or truncation is requested on a non-normal file..It Dv LOG_CHANNEL_OFFThis is set for channels opened by .Fn log_new_null_channel ..It Dv LOG_CLOSE_STREAMIf this flag is set, then .Fn log_free_channelwill free a .No non- Dv NULLstream 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_CATEGORYIf set, .Fn log_vwritewill insert the category name, if available, into logging messages which are logged to channels of type.Dv log_syslogor .Dv log_file ..It Dv LOG_PRINT_LEVELIf set, .Fn log_vwritewill insert a string identifying the message priority level into the information logged to channels of type.Dv log_syslogor .Dv log_file ..It Dv LOG_REQUIRE_DEBUGOnly log debugging messages (i.e., those with a priority greater than zero)..It Dv LOG_TIMESTAMPIf set, .Fn log_vwritewill insert a timestamp into logging messages which are logged to channels oftype.Dv log_syslogor .Dv log_file ..It Dv LOG_TRUNCATETruncate logging file when re-opened.Fn ( log_open_stream will.Xr unlink 2the file and then .Xr open 2a new file of the same name with the.Dv O_EXCLbit set)..It Dv LOG_USE_CONTEXT_LEVELUse 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 DESCRIPTIONSThe 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 chanis valid, it attempts to open (and return) the stream associated with thatchannel.  If the stream is already opened, then it is returned; otherwise,.Xr stat 2is used to test the filename for the stream..PpAt this point, if the logging file is supposed to have different.Va versions (i.e., incremented version numbers; higher numbers indicate older versionsof the logging file).  If so, then any existing versions are.Xr rename 2 Ns -dto have one version-number higher than previously, and the.Dq currentfilename for the stream is set to the.Dq \&.0form of the name.  Next, if the logging file is supposed to be truncated(i.e., the.Dv LOG_TRUNCATEbit of the.Va flagsfield of the logging channel structure is set), then any file with the.Dq currentfilename 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 numberingor truncation) is supposed to take place, a.Dv NULLfile pointer is returned..PpFinally, the filename associated with the logging channel is.Xr open 2 Ns -dusing the appropriate flags and a mode which sets the read/write permissionsfor the user, group, and others.  The file descriptor returned by .Xr open 2is then passed to.Xr fopen 3 ,with the append mode set, and the stream returned by this call is storedin the .Fa chanstructure and returned..PpIf .Fn log_open_streamfails at any point, then the .Dv LOG_CHANNEL_BROKEN bit of the.Va flags field of the logging channel pointed to by.Fa chanis set, a .Dv NULLis returned, and .Va errnocontains pertinent information..PpThe.Fn log_close_streamfunction 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 NULLeven if the call to .Xr fclose 3fails..PpThe function.Fn log_get_streamreturns the stream associated with the logging channel pointed to by.Dq Fa chan ,if it is .No non- Ns Dv NULLand specifies a logging channel which has a .Dv FILE *or stream associated with it..PpThe.Fn log_get_filenamefunction returns the name of the file associated with the logging channel pointed to by.Dq Fa chan ,if it is .No non- Ns Dv NULLand specifies a logging channel which has a file associated with it..PpThe.Fn log_vwrite function performs the actual logging of a message to the various loggingchannels 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 categorywhich have a priority set to.Fa levelor any .Em less importantpriority value.  If the.Fa categoryis not valid or has no logging channels, then the category defaults to 0..PpThere are a number of conditions under which a call to .Fn log_vwritewill 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 brokenor.Dq off(i.e., its flags have .Dv LOG_CHANNEL_BROKENor.Dv LOG_CHANNEL_OFFset, respectively), or if the logging channel channel is of type.Dv log_null .Additionally, if the logging channel's flag has.Dv LOG_REQUIRE_DEBUGset and the message is not a debugging message (i.e., has a level greaterthan 0), then it will not be logged.Finally, if the message's priority is less important than thechannel's logging level (the priority threshold), will not be logged..Sy NOTE :If a logging channel's flag has.Dv LOG_USE_CONTEXT_LEVELset, it will use the logging context's priority, rather than its own..PpIf all of these hurdles are passed, then only.Dv log_syslogand.Dv log_filechannels actually can have logging.  For channels which use.Xr syslog 3 ,the channel's .Xr syslog 3facility is used in conjunction with a potentially modified form of themessage's priority level, since .Xr syslog 3has 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_DEBUGpriority, all messages .Dq more importantthan.Dv log_criticalare mapped to.Dv LOG_CRIT ,and the priorities corresponding to the ones listed in the section.Sx Message Prioritiesare given the obvious corresponding .Xr syslog 3priority..PpFor .Dv log_filetype logging channels, if the file size is greater than the maximum file size, then no logging occurs.  (The same thing happens if a .Dv NULLstream is encountered and.Fn log_open_streamfails to open the channel's stream.).PpFor 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