information..PpThe .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_checkand.Fn log_check_channelare used to see if a contemplated logging call will actually generate anyoutput, which is useful when creating a log message involves non-trivialwork..Fn log_checkwill return non-zero if a call to.Fn log_vwritewith the given .Fa categoryand.Fa levelwould generate output on any channels, and zero otherwise..Fn log_check_channelwill return non-zero if writing to the.Fa chanat the given.Fa levelwould generate output..PpThe function.Fn log_new_context creates a new .Nm logging context ,and stores this in the.Dq Va opaquefield of the argument.Dq Fa lc , and opaque structure used internally.  This new .Nm context will include the.Dq Fa num_categoriesand.Dq Fa category_nameswhich are supplied; the latter can be.Dv NULL ..Sy NOTE :Since .Dq Fa category_namesis 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..PpThe.Fn log_free_context function is used to free the opaque structure .Dq Va lc.opaqueand its components..Sy NOTE :The.Dq Va opaquefield 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_categorieswhich were in the corresponding call to.Fn log_new_context ) associated with the given .Nm logging context ,.Em all of the .Nm logging channelsare .Xr free 3 Ns -d .The opaque structure itself is then.Xr free 3 Ns -d ,and .Dq Va lc.opaqueis set to.Dv NULL ..Pp.Sy NOTE :The function .Fn log_free_context does.Em notfree 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 ..PpThe function.Fn log_add_channel adds the .Nm logging channel.Dq Fa chanto the list of logging channels in the given .Fa categoryof the .Nm logging context.Dq Fa lc .No checking is performed to see whether or not.Fa chanis already present in the given.Fa category ,so multiple instances in a single .Fa category can occur (but see.Fn log_remove_channel ,below)..PpThe.Fn log_remove_channel functionremoves .Em alloccurrences of the.Nm logging channel.Dq Fa chanfrom the list of logging channels in the given .Fa categoryof the .Nm logging context.Dq Fa lc .It also attempts to free the channel by calling.Fn log_free_channel (see its description, below)..PpThe.Fn log_option function is used to change the.Fa option of the indicated logging context.Fa lcto the given.Fa value .The .Fa optioncan be either.Dv LOG_OPTION_LEVELor.Dv LOG_OPTION_DEBUG ;in the first case, the log context's debugging level is reset to theindicated level.  If the.Fa option is .Dv LOG_OPTION_DEBUG , then a non-zero.Fa valueresults in setting the debug flag of the logging context, while a zero.Fa valuemeans that the debug flag is reset..PpThe.Fn log_category_is_active test returns a 1 if the given.Fa categoryof the indicated logging context.Fa lchas at least one logging channel, and 0, otherwise..PpThe functions.Fn log_new_syslog_channel ,.Fn log_new_file_channel ,and .Fn log_new_null_channelcreate a new channel of the type specified (thus, the difference in arguments);the .Dq Va typefield of the new.Do.Ft struct log_channel.Dcis always set to the appropriate value..PpThe .Fn log_new_syslog_channelfunction .Xr malloc 3 Ns -sa new.Ft struct log_channelof.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 referencesfield is initialized to zero.See .Sx Logging Channel Flagsand.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 3facility; 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 .PpThe 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 referencesfield is strictly positive, in the case of.Fn log_dec_references ) .These functions are meant to track changes in the number of different clientswhich refer to the given logging channel..PpThe .Fn log_free_channelfunction 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_STREAMflag is set), and the filename, if .No non- Ns Dv NULL ,is .Xr free 3 Ns -d before .Dq Fa chanis .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 chanis either.Dv NULLor a .No non- Ns Dv log_filechannel.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 3fails.Po.Va errno is set by the call which failed .Pc .If some value other than.Dv NULLis 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 chanis .No non- Ns Dv NULLand the call to.Xr fclose 3fails.0 if successful or the logging channel pointed to by.Dq Fa chanis invalid (i.e.,.Dv NULLor not a logging channel which has uses a file); in the latter case, .Va errnois 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 3fails.Pq with Va errno No set to Dv ENOMEM .Otherwise, 0, with .Dq Va lc->opaquecontaining the new structures and information..It Fn log_add_channel-1 ifa) either.Dq Va lc.opaqueis.Dv NULL or .Fa categoryis invalid (negative or greater than or equal to .Va lcp->num_categories ) ,with.Va errno set to .Dv EINVAL ;b) .Xr malloc 3fails.Pq with Va errno No set to Dv ENOMEM .Otherwise, 0..It Fn log_remove_channel-1 ifa) either.Dq Va lc.opaqueis .Dv NULLor .Fa categoryis invalid, as under failure condition a) for.Fn log_add_channel ,above, including the setting of.Va errno ;b) no channel numbered.Fa chanis 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 ifa) .Dq Va lc.opaqueis.Dv NULL , b).Fa optionspecifies 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.opaqueis.Dv NULL .Pq with Va errno No set to Dv EINVAL ;1 if the.Fa categorynumber is valid and there are logging channels in this .Fa categorywithin the indicated logging context; 0 if the.Fa categorynumber is invalid or there are no logging channels in this.Fa categorywithin the indicated logging context..It Fn log_new_syslog_channel.Dv NULLif.Xr malloc 3fails.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 NULLif.Xr malloc 3fails.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 NULLif.Xr malloc 3fails.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 chanis .Dv NULL .Pq with Va errno set to Dv EINVAL .Otherwise, 0..It Fn log_dec_references-1 if .Dq Fa chanis .Dv NULL or its.Va referencesfield 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.hinclude file for logging library.It Pa syslog.h.Xr syslog 3 Ns -stylepriorities.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 ERRORSThis table shows which functions can return the indicated error in the.Va errnovariable; see the.Sx RETURN VALUESsection, 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_streamand functions which call it.Pq currently, only Fn log_vwrite ..El.PpAdditionally, .Fn log_vwriteand.Fn log_free_contextwill fail via .Fn assertif .Dq Va lc.opaqueis.Dv NULL .The function.Fn log_vwritecan also exit with a critical error logged via.Xr syslog 3indicating 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 AUTHORSBob Halley...TODO.\" .Sh BUGS