contrib/bind-9.3/lib/bind/isc/logging.mdoc

   1 .\" $Id: logging.mdoc,v 1.1.2.1.10.1 2004/03/09 08:33:43 marka Exp $
   2 .\"
   3 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
   4 .\" Copyright (c) 1995-1999 by Internet Software Consortium
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
  16 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\" The following six UNCOMMENTED lines are required.
  19 .Dd January 1, 1996
  20 .\"Os OPERATING_SYSTEM [version/release]
  21 .Os BSD 4
  22 .\"Dt DOCUMENT_TITLE [section number] [volume]
  23 .Dt LOGGING @SYSCALL_EXT@
  24 .Sh NAME
  25 .Nm log_open_stream ,
  26 .Nm log_close_stream ,
  27 .Nm log_get_stream ,
  28 .Nm log_get_filename ,
  29 .Nm log_vwrite ,
  30 .Nm log_write ,
  31 .Nm log_new_context ,
  32 .Nm log_free_context ,
  33 .Nm log_add_channel ,
  34 .Nm log_remove_channel ,
  35 .Nm log_option ,
  36 .Nm log_category_is_active ,
  37 .Nm log_new_syslog_channel ,
  38 .Nm log_new_file_channel ,
  39 .Nm log_set_file_owner ,
  40 .Nm log_new_null_channel ,
  41 .Nm log_inc_references ,
  42 .Nm log_dec_references ,
  43 .Nm log_free_channel
  44 .Nd logging system
  45 .Sh SYNOPSIS
  46 .Fd #include <isc/logging.h>
  47 .Ft FILE *
  48 .Fn log_open_stream "log_channel chan"
  49 .Ft int
  50 .Fn log_close_stream "log_channel chan"
  51 .Ft FILE *
  52 .Fn log_get_stream "log_channel chan"
  53 .Ft char *
  54 .Fn log_get_filename "log_channel chan"
  55 .Ft void
  56 .Fn log_vwrite "log_context lc" "int category" "int level" \
  57     "const char *format" va_list args"
  58 .Ft void
  59 .Fn log_write "log_context lc" "int category" "int level" \
  60     "const char *format" "..."
  61 .Ft int
  62 .Fn log_check_channel "log_context lc" "int level" "log_channel chan"
  63 .Ft int
  64 .Fn log_check "log_context lc" "int category" "int level"
  65 .Ft int
  66 .Fn log_new_context "int num_categories" "char **category_names" \
  67     "log_context *lc"
  68 .Ft void
  69 .Fn log_free_context "log_context lc"
  70 .Ft int
  71 .Fn log_add_channel "log_context lc" "int category" "log_channel chan"
  72 .Ft int
  73 .Fn log_remove_channel "log_context lc" "int category" "log_channel chan"
  74 .Ft int
  75 .Fn log_option "log_context lc" "int option" "int value"
  76 .Ft int
  77 .Fn log_category_is_active "log_context lc" "int category"
  78 .Ft log_channel
  79 .Fn log_new_syslog_channel "unsigned int flags" "int level" "int facility"
  80 .Ft log_channel
  81 .Fn log_new_file_channel "unsigned int flags" "int level" \
  82     "char *name" "FILE *stream" "unsigned int versions" \
  83     "unsigned long max_size"
  84 .Ft int
  85 .Fn log_set_file_owner "log_channel chan" "uid_t owner" "gid_t group"
  86 .Ft log_channel
  87 .Fn log_new_null_channel "void"
  88 .Ft int
  89 .Fn log_inc_references "log_channel chan"
  90 .Ft int
  91 .Fn log_dec_references "log_channel chan"
  92 .Ft int
  93 .Fn log_free_channel "log_channel chan"
  94 .Sh DESCRIPTION
  95 The
  96 .Sy ISC
  97 .Nm logging library
  98 is flexible logging system which is based upon a set of concepts:
  99 .Nm logging channels ,
 100 .Nm categories ,
 101 and
 102 .Nm logging contexts .
 103 .Pp
 104 The basic building block is the
 105 .Dq Nm logging channel ,
 106 which includes a
 107 .Nm priority
 108 (logging level), which type of logging is to occur, and other
 109 flags and information associated with technical aspects of the logging.
 110 The set of priorities which are supported is shown below, in the section
 111 .Sx Message Priorities .
 112 A priority sets a threshold for message logging; a logging channel will
 113 .Em only
 114 log those messages which are
 115 .Em at least as important
 116 as its priority indicates.  (The fact that
 117 .Dq more important
 118 means
 119 .Dq more negative ,
 120 under the current scheme, is an implementation detail; if a channel has
 121 a priority of
 122 .Dv log_error ,
 123 then it will
 124 .Em not
 125 log messages with the
 126 .Dv log_warning
 127 priority, but it
 128 .Em will
 129 log messages with the
 130 .Dv log_error
 131 or
 132 .Dv log_critical
 133 priority.)
 134 .Pp
 135 The
 136 .Nm logging channel
 137 also has an indication of the type of logging performed.  Currently,
 138 the supported
 139 .Nm logging types
 140 include (see also
 141 .Sx Logging Types ,
 142 below):
 143 .Bl -tag -width "log_syslog" -compact -offset indent
 144 .It Dv log_syslog
 145 for
 146 .Xr syslog 3 Ns -style
 147 logging
 148 .It Dv log_file
 149 for use of a file
 150 .It Dv log_null
 151 for
 152 .Em no
 153 logging
 154 .El
 155 A new logging channel is created by calling either
 156 .Fn log_new_syslog_channel ,
 157 .Fn log_new_file_channel ,
 158 or
 159 .Fn log_new_null_channel ,
 160 respectively.
 161 When a channel is no longer to be used, it can be freed using
 162 .Fn log_free_channel .
 163 .Pp
 164 Both
 165 .Dv log_syslog
 166 and
 167 .Dv log_file
 168 channel types can include more information; for instance, a
 169 .Dv log_syslog Ns -type
 170 channel allows the specification of a
 171 .Xr syslog 3 Ns -style
 172 .Dq facility ,
 173 and a
 174 .Dv log_file Ns -type
 175 channels allows the caller to set a maximum file size and number
 176 of versions.  (See
 177 .Fn log_new_syslog_channel
 178 or
 179 .Fn log_new_file_channel ,
 180 below.)
 181 Additionally, once a logging channel of type
 182 .Dv log_file
 183 is defined, the functions
 184 .Fn log_open_stream
 185 and
 186 .Fn log_close_stream
 187 can open or close the stream associated with the logging channel's logging
 188 filename.  The
 189 .Fn log_get_stream
 190 and
 191 .Fn log_get_filename
 192 functions return the stream or filename, respectively, of such a logging
 193 channel.  Also unique to logging channels of type
 194 .Dv log_file
 195 is the
 196 .Fn log_set_file_owner
 197 function, which tells the logging system what user and group ought to own
 198 newly created files (which is only effective if the caller is privileged.)
 199 .Pp
 200 Callers provide
 201 .Dq Nm categories ,
 202 determining both the number of such categories and any (optional) names.
 203 Categories are like array indexes in C; if the caller declares
 204 .Dq Va n
 205 categories, then they are considered to run from 0 to
 206 .Va n-1 ;
 207 with this scheme, a category number would be invalid if it were negative or
 208 greater than/equal to
 209 .Va n .
 210 Each category can have its own list of
 211 .Nm logging channels
 212 associated with it; we say that such a channel is
 213 .Dq in
 214 the particular category.
 215 .Sy NOTE :
 216 Individual logging channels can appear in more than one category.
 217 .Pp
 218 A
 219 .Dq Nm logging context
 220 is the set of all
 221 .Nm logging channels
 222 associated with the context's
 223 .Nm categories ;
 224 thus, a particular
 225 .Nm category
 226 scheme is associated with a particular
 227 .Nm logging context .
 228 .Sy NOTE :
 229 A logging channel may appear in more than one logging context, and in
 230 multiple categories within each logging context.
 231 .Pp
 232 Use
 233 .Fn log_add_channel
 234 and
 235 .Fn log_remove_channel
 236 to add or remove a logging channel to some category in a logging context.
 237 To see if a given category in a logging context is being used, use the
 238 Boolean test
 239 .Fn log_category_is_active .
 240 .Pp
 241 A
 242 .Nm logging context
 243 can also have a
 244 .Nm priority
 245 (logging level)
 246 and various flags associated with the whole context; in order to alter the
 247 flags or change the priority of a context, use
 248 .Fn log_option .
 249 .Ss Message Priorities
 250 Currently, five
 251 .Nm priorities
 252 (logging levels) are supported (they can also be found in the header file):
 253 .Bd -literal -offset indent
 254 #define log_critical            (-5)
 255 #define log_error               (-4)
 256 #define log_warning             (-3)
 257 #define log_notice              (-2)
 258 #define log_info                (-1)
 259 .Ed
 260 .Pp
 261 In the current implementation, logging messages which have a level greater
 262 than 0 are considered to be debugging messages.
 263 .Ss Logging Types
 264 The three different
 265 .Nm logging types
 266 currently supported are different values of the enumerated type
 267 .Ft log_output_type
 268 (these are also listed in the header file):
 269 .Bd -literal -offset indent
 270 typedef enum { log_syslog, log_file, log_null } log_output_type;
 271 .Ed
 272 .Ss Logging Channel Flags
 273 There are several flags which can be set on a logging channel; the flags
 274 and their meanings are as follows (they are also found in the header file):
 275 .Bl -tag -width "LOG_USE_CONTEXT_LEVEL  " -offset indent
 276 .It Dv LOG_CHANNEL_BROKEN
 277 This is set only when some portion of
 278 .Fn log_open_stream
 279 fails:
 280 .Xr open 2
 281 or
 282 .Xr fdopen 3
 283 fail;
 284 .Xr stat 2
 285 fails in a
 286 .Dq bad
 287 way; versioning or truncation is requested on a non-normal file.
 288 .It Dv LOG_CHANNEL_OFF
 289 This is set for channels opened by
 290 .Fn log_new_null_channel .
 291 .It Dv LOG_CLOSE_STREAM
 292 If this flag is set, then
 293 .Fn log_free_channel
 294 will free a
 295 .No non- Dv NULL
 296 stream of a logging channel which is being
 297 .Xr free 3 Ns -d
 298 (if the logging channel is of type
 299 .Dv log_file ,
 300 of course).
 301 .It Dv LOG_PRINT_CATEGORY
 302 If set,
 303 .Fn log_vwrite
 304 will insert the category name, if available, into logging messages which are
 305 logged to channels of type
 306 .Dv log_syslog
 307 or
 308 .Dv log_file .
 309 .It Dv LOG_PRINT_LEVEL
 310 If set,
 311 .Fn log_vwrite
 312 will insert a string identifying the message priority level into the
 313 information logged to channels of type
 314 .Dv log_syslog
 315 or
 316 .Dv log_file .
 317 .It Dv LOG_REQUIRE_DEBUG
 318 Only log debugging messages (i.e., those with a priority greater than zero).
 319 .It Dv LOG_TIMESTAMP
 320 If set,
 321 .Fn log_vwrite
 322 will insert a timestamp into logging messages which are logged to channels of
 323 type
 324 .Dv log_syslog
 325 or
 326 .Dv log_file .
 327 .It Dv LOG_TRUNCATE
 328 Truncate logging file when re-opened
 329 .Fn ( log_open_stream
 330 will
 331 .Xr unlink 2
 332 the file and then
 333 .Xr open 2
 334 a new file of the same name with the
 335 .Dv O_EXCL
 336 bit set).
 337 .It Dv LOG_USE_CONTEXT_LEVEL
 338 Use the logging context's priority or logging level, rather than the logging
 339 channel's own priority.  This can be useful for those channels which are
 340 included in multiple logging contexts.
 341 .El
 342 .Ss FUNCTION DESCRIPTIONS
 343 The function
 344 .Fn log_open_stream
 345 is for use with channels which log to a file; i.e., logging channels with a
 346 .Va type
 347 field set to
 348 .Dq Dv log_file .
 349 If the logging channel pointed to by
 350 .Dq Fa chan
 351 is valid, it attempts to open (and return) the stream associated with that
 352 channel.  If the stream is already opened, then it is returned; otherwise,
 353 .Xr stat 2
 354 is used to test the filename for the stream.
 355 .Pp
 356 At this point, if the logging file is supposed to have different
 357 .Va versions
 358 (i.e., incremented version numbers; higher numbers indicate older versions
 359 of the logging file).  If so, then any existing versions are
 360 .Xr rename 2 Ns -d
 361 to have one version-number higher than previously, and the
 362 .Dq current
 363 filename for the stream is set to the
 364 .Dq \&.0
 365 form of the name.  Next, if the logging file is supposed to be truncated
 366 (i.e., the
 367 .Dv LOG_TRUNCATE
 368 bit of the
 369 .Va flags
 370 field of the logging channel structure is set), then any file with the
 371 .Dq current
 372 filename for the stream is
 373 .Xr unlink 2 Ns -d .
 374 .Sy NOTE :
 375 If the logging file is
 376 .Em not
 377 a regular file, and either of the above operations (version numbering
 378 or truncation) is supposed to take place, a
 379 .Dv NULL
 380 file pointer is returned.
 381 .Pp
 382 Finally, the filename associated with the logging channel is
 383 .Xr open 2 Ns -d
 384 using the appropriate flags and a mode which sets the read/write permissions
 385 for the user, group, and others.  The file descriptor returned by
 386 .Xr open 2
 387 is then passed to
 388 .Xr fopen 3 ,
 389 with the append mode set, and the stream returned by this call is stored
 390 in the
 391 .Fa chan
 392 structure and returned.
 393 .Pp
 394 If
 395 .Fn log_open_stream
 396 fails at any point, then the
 397 .Dv LOG_CHANNEL_BROKEN
 398 bit of the
 399 .Va flags
 400 field of the logging channel pointed to by
 401 .Fa chan
 402 is set, a
 403 .Dv NULL
 404 is returned, and
 405 .Va errno
 406 contains pertinent information.
 407 .Pp
 408 The
 409 .Fn log_close_stream
 410 function closes the stream associated with the logging channel pointed to by
 411 .Dq Fa chan
 412 (if
 413 .Fa chan
 414 is valid and the stream exists and can be closed properly by
 415 .Xr fclose 3 ) .
 416 The stream is set to
 417 .Dv NULL
 418 even if the call to
 419 .Xr fclose 3
 420 fails.
 421 .Pp
 422 The function
 423 .Fn log_get_stream
 424 returns the stream associated with the logging channel pointed to by
 425 .Dq Fa chan ,
 426 if it is
 427 .No non- Ns Dv NULL
 428 and specifies a logging channel which has a
 429 .Dv FILE *
 430 or stream associated with it.
 431 .Pp
 432 The
 433 .Fn log_get_filename
 434 function returns the name of the file associated with the logging channel
 435 pointed to by
 436 .Dq Fa chan ,
 437 if it is
 438 .No non- Ns Dv NULL
 439 and specifies a logging channel which has a file associated with it.
 440 .Pp
 441 The
 442 .Fn log_vwrite
 443 function performs the actual logging of a message to the various logging
 444 channels of a logging context
 445 .Fa lc .
 446 The message consists of an
 447 .Xr fprint 3 Ns -style
 448 .Fa format
 449 and its associated
 450 .Fa args
 451 (if any); it will be written to all logging channels in the given
 452 .Fa category
 453 which have a priority set to
 454 .Fa level
 455 or any
 456 .Em less important
 457 priority value.  If the
 458 .Fa category
 459 is not valid or has no logging channels, then the category defaults to 0.
 460 .Pp
 461 There are a number of conditions under which a call to
 462 .Fn log_vwrite
 463 will not result in actually logging the message: if there is no logging channel
 464 at even the default category (0), or if a given channel is either
 465 .Dq broken
 466 or
 467 .Dq off
 468 (i.e., its flags have
 469 .Dv LOG_CHANNEL_BROKEN
 470 or
 471 .Dv LOG_CHANNEL_OFF
 472 set, respectively), or if the logging channel channel is of type
 473 .Dv log_null .
 474 Additionally, if the logging channel's flag has
 475 .Dv LOG_REQUIRE_DEBUG
 476 set and the message is not a debugging message (i.e., has a level greater
 477 than 0), then it will not be logged.
 478 Finally, if the message's priority is less important than the
 479 channel's logging level (the priority threshold), will not be logged.
 480 .Sy NOTE :
 481 If a logging channel's flag has
 482 .Dv LOG_USE_CONTEXT_LEVEL
 483 set, it will use the logging context's priority, rather than its own.
 484 .Pp
 485 If all of these hurdles are passed, then only
 486 .Dv log_syslog
 487 and
 488 .Dv log_file
 489 channels actually can have logging.  For channels which use
 490 .Xr syslog 3 ,
 491 the channel's
 492 .Xr syslog 3
 493 facility is used in conjunction with a potentially modified form of the
 494 message's priority level, since
 495 .Xr syslog 3
 496 has its own system of priorities
 497 .Pq Pa /usr/include/syslog.h .
 498 All debug messages (priority >= 0) are mapped to
 499 .Xr syslog 3 Ns 's
 500 .Dv LOG_DEBUG
 501 priority, all messages
 502 .Dq more important
 503 than
 504 .Dv log_critical
 505 are mapped to
 506 .Dv LOG_CRIT ,
 507 and the priorities corresponding to the ones listed in the section
 508 .Sx Message Priorities
 509 are given the obvious corresponding
 510 .Xr syslog 3
 511 priority.
 512 .Pp
 513 For
 514 .Dv log_file
 515 type logging channels, if the file size is greater than the maximum file
 516 size, then no logging occurs.  (The same thing happens if a
 517 .Dv NULL
 518 stream is encountered and
 519 .Fn log_open_stream
 520 fails to open the channel's stream.)
 521 .Pp
 522 For both logging to normal files and logging via
 523 .Xr syslog 3 ,
 524 the value of the flags
 525 .Dv LOG_TIMESTAMP ,
 526 .Dv LOG_PRINT_CATEGORY ,
 527 and
 528 .Dv LOG_PRINT_LEVEL
 529 are used in determining whether or not these items are included in the logged
 530 information.
 531 .Pp
 532 The
 533 .Fn log_write
 534 function is merely a front-end to a call to
 535 .Fn log_vwrite ;
 536 see the description of that function, above, for more information.
 537 .Pp
 538 .Fn log_check
 539 and
 540 .Fn log_check_channel
 541 are used to see if a contemplated logging call will actually generate any
 542 output, which is useful when creating a log message involves non-trivial
 543 work.
 544 .Fn log_check
 545 will return non-zero if a call to
 546 .Fn log_vwrite
 547 with the given
 548 .Fa category
 549 and
 550 .Fa level
 551 would generate output on any channels, and zero otherwise.
 552 .Fn log_check_channel
 553 will return non-zero if writing to the
 554 .Fa chan
 555 at the given
 556 .Fa level
 557 would generate output.
 558 .Pp
 559 The function
 560 .Fn log_new_context
 561 creates a new
 562 .Nm logging context ,
 563 and stores this in the
 564 .Dq Va opaque
 565 field of the argument
 566 .Dq Fa lc ,
 567 and opaque structure used internally.  This new
 568 .Nm context
 569 will include the
 570 .Dq Fa num_categories
 571 and
 572 .Dq Fa category_names
 573 which are supplied; the latter can be
 574 .Dv NULL .
 575 .Sy NOTE :
 576 Since
 577 .Dq Fa category_names
 578 is used directly, it
 579 .Em must not
 580 be freed by the caller, if it is
 581 .No non- Ns Dv NULL .
 582 The initial logging flags and priority are both set to zero.
 583 .Pp
 584 The
 585 .Fn log_free_context
 586 function is used to free the opaque structure
 587 .Dq Va lc.opaque
 588 and its components.
 589 .Sy NOTE :
 590 The
 591 .Dq Va opaque
 592 field of
 593 .Dq Fa lc
 594 .Em must
 595 be
 596 .No non- Ns Dv NULL .
 597 For each of the various
 598 .Dq categories
 599 (indicated by the
 600 .Dq Va num_categories
 601 which were in the corresponding call to
 602 .Fn log_new_context )
 603 associated with the given
 604 .Nm logging context ,
 605 .Em all
 606 of the
 607 .Nm logging channels
 608 are
 609 .Xr free 3 Ns -d .
 610 The opaque structure itself is then
 611 .Xr free 3 Ns -d ,
 612 and
 613 .Dq Va lc.opaque
 614 is set to
 615 .Dv NULL .
 616 .Pp
 617 .Sy NOTE :
 618 The function
 619 .Fn log_free_context
 620 does
 621 .Em not
 622 free the memory associated with
 623 .Fa category_names ,
 624 since the logging library did not allocate the memory for it, originally;
 625 it was supplied in the call to
 626 .Fn log_new_context .
 627 .Pp
 628 The function
 629 .Fn log_add_channel
 630 adds the
 631 .Nm logging channel
 632 .Dq Fa chan
 633 to the list of logging channels in the given
 634 .Fa category
 635 of the
 636 .Nm logging context
 637 .Dq Fa lc .
 638 No checking is performed to see whether or not
 639 .Fa chan
 640 is already present in the given
 641 .Fa category ,
 642 so multiple instances in a single
 643 .Fa category
 644 can occur (but see
 645 .Fn log_remove_channel ,
 646 below).
 647 .Pp
 648 The
 649 .Fn log_remove_channel
 650 function
 651 removes
 652 .Em all
 653 occurrences of the
 654 .Nm logging channel
 655 .Dq Fa chan
 656 from the list of logging channels in the given
 657 .Fa category
 658 of the
 659 .Nm logging context
 660 .Dq Fa lc .
 661 It also attempts to free the channel by calling
 662 .Fn log_free_channel
 663 (see its description, below).
 664 .Pp
 665 The
 666 .Fn log_option
 667 function is used to change the
 668 .Fa option
 669 of the indicated logging context
 670 .Fa lc
 671 to the given
 672 .Fa value .
 673 The
 674 .Fa option
 675 can be either
 676 .Dv LOG_OPTION_LEVEL
 677 or
 678 .Dv LOG_OPTION_DEBUG ;
 679 in the first case, the log context's debugging level is reset to the
 680 indicated level.  If the
 681 .Fa option
 682 is
 683 .Dv LOG_OPTION_DEBUG ,
 684 then a non-zero
 685 .Fa value
 686 results in setting the debug flag of the logging context, while a zero
 687 .Fa value
 688 means that the debug flag is reset.
 689 .Pp
 690 The
 691 .Fn log_category_is_active
 692 test returns a 1 if the given
 693 .Fa category
 694 of the indicated logging context
 695 .Fa lc
 696 has at least one logging channel, and 0, otherwise.
 697 .Pp
 698 The functions
 699 .Fn log_new_syslog_channel ,
 700 .Fn log_new_file_channel ,
 701 and
 702 .Fn log_new_null_channel
 703 create a new channel of the type specified (thus, the difference in arguments);
 704 the
 705 .Dq Va type
 706 field of the new
 707 .Do
 708 .Ft struct log_channel
 709 .Dc
 710 is always set to the appropriate value.
 711 .Pp
 712 The
 713 .Fn log_new_syslog_channel
 714 function
 715 .Xr malloc 3 Ns -s
 716 a new
 717 .Ft struct log_channel
 718 of
 719 .Va type
 720 .Dv log_syslog ,
 721 i.e., a logging channel which will use
 722 .Xr syslog 3 .
 723 The new structure is filled out with the
 724 .Dq Fa flags ,
 725 .Dq Fa level ,
 726 and
 727 .Dq Fa facility
 728 which are given; the
 729 .Va references
 730 field is initialized to zero.
 731 See
 732 .Sx Logging Channel Flags
 733 and
 734 .Sx Message Priorities ,
 735 above, or the header file for information about acceptable values for
 736 .Dq Fa flags ,
 737 and
 738 .Dq Fa level .
 739 The
 740 .Dq Fa facility .
 741 can be any valid
 742 .Xr syslog 3
 743 facility; see the appropriate system header file or manpage for more
 744 information.
 745 .Pp
 746 .Ft log_channel
 747 .Fn log_new_file_channel "unsigned int flags" "int level" \
 748     "char *name" "FILE *stream" "unsigned int versions" \
 749     "unsigned long max_size"
 750 .Pp
 751 .Fn log_new_null_channel
 752 .Pp
 753 The functions
 754 .Fn log_inc_references
 755 and
 756 .Fn log_dec_references
 757 increment or decrements, respectively, the
 758 .Va references
 759 field of the logging channel pointed to by
 760 .Dq Fa chan ,
 761 if it is a valid channel (and if the
 762 .Va references
 763 field is strictly positive, in the case of
 764 .Fn log_dec_references ) .
 765 These functions are meant to track changes in the number of different clients
 766 which refer to the given logging channel.
 767 .Pp
 768 The
 769 .Fn log_free_channel
 770 function frees the
 771 field of the logging channel pointed to by
 772 .Dq Fa chan
 773 if there are no more outstanding references to it.  If the channel uses a file,
 774 the stream is
 775 .Xr fclose 3 Ns -d
 776 (if the
 777 .Dv LOG_CLOSE_STREAM
 778 flag is set), and the filename, if
 779 .No non- Ns Dv NULL ,
 780 is
 781 .Xr free 3 Ns -d
 782 before
 783 .Dq Fa chan
 784 is
 785 .Xr free 3 Ns -d .
 786 .Pp
 787 .\" The following requests should be uncommented and
 788 .\" used where appropriate.  This next request is
 789 .\" for sections 2 and 3 function return values only.
 790 .Sh RETURN VALUES
 791 .\" This next request is for sections 1, 6, 7 & 8 only
 792 .Bl -tag -width "log_category_is_active()"
 793 .It Fn log_open_stream
 794 .Dv NULL
 795 is returned under any of several error conditions:
 796 a) if
 797 .Dq Fa chan
 798 is either
 799 .Dv NULL
 800 or a
 801 .No non- Ns Dv log_file
 802 channel
 803 .Pq Va errno No is set to Dv EINVAL ;
 804 b) if either versioning or truncation is requested for a non-normal file
 805 .Pq Va errno No is set to Dv EINVAL ;
 806 c) if any of
 807 .Xr stat 2 ,
 808 .Xr open 2 ,
 809 or
 810 .Xr fdopen 3
 811 fails
 812 .Po
 813 .Va errno
 814 is set by the call which failed
 815 .Pc .
 816 If some value other than
 817 .Dv NULL
 818 is returned, then it is a valid logging stream (either newly-opened or
 819 already-open).
 820 .It Fn log_close_stream
 821 -1 if the stream associated with
 822 .Dq Fa chan
 823 is
 824 .No non- Ns Dv NULL
 825 and the call to
 826 .Xr fclose 3
 827 fails.
 828 0 if successful or the logging channel pointed to by
 829 .Dq Fa chan
 830 is invalid (i.e.,
 831 .Dv NULL
 832 or not a logging channel which has uses a file); in the latter case,
 833 .Va errno
 834 is set to
 835 .Dv EINVAL .
 836 .It Fn log_get_stream
 837 .Dv NULL
 838 under the same conditions as those under which
 839 .Fn log_close_stream ,
 840 above, returns 0 (including the setting of
 841 .Va errno ) .
 842 Otherwise, the stream associated with the logging channel is returned.
 843 .It Fn log_get_filename
 844 .Dv NULL
 845 under the same conditions as those under which
 846 .Fn log_close_stream ,
 847 above, returns 0 (including the setting of
 848 .Va errno ) .
 849 Otherwise, the name of the file associated with the logging channel is
 850 returned.
 851 .It Fn log_new_context
 852 -1 if
 853 .Xr malloc 3
 854 fails
 855 .Pq with Va errno No set to Dv ENOMEM .
 856 Otherwise, 0, with
 857 .Dq Va lc->opaque
 858 containing the new structures and information.
 859 .It Fn log_add_channel
 860 -1 if
 861 a) either
 862 .Dq Va lc.opaque
 863 is
 864 .Dv NULL
 865 or
 866 .Fa category
 867 is invalid (negative or greater than or equal to
 868 .Va lcp->num_categories ) ,
 869 with
 870 .Va errno
 871 set to
 872 .Dv EINVAL ;
 873 b)
 874 .Xr malloc 3
 875 fails
 876 .Pq with Va errno No set to Dv ENOMEM .
 877 Otherwise, 0.
 878 .It Fn log_remove_channel
 879 -1 if
 880 a) either
 881 .Dq Va lc.opaque
 882 is
 883 .Dv NULL
 884 or
 885 .Fa category
 886 is invalid, as under failure condition a) for
 887 .Fn log_add_channel ,
 888 above, including the setting of
 889 .Va errno ;
 890 b) no channel numbered
 891 .Fa chan
 892 is found in the logging context indicated by
 893 .Fa lc
 894 .Pq with Va errno No set to Dv ENOENT .
 895 Otherwise, 0.
 896 .It Fn log_option
 897 -1 if
 898 a)
 899 .Dq Va lc.opaque
 900 is
 901 .Dv NULL ,
 902 b)
 903 .Fa option
 904 specifies an unknown logging option;
 905 in either case,
 906 .Va errno
 907 is set to
 908 .Dv EINVAL .
 909 Otherwise, 0.
 910 .It Fn log_category_is_active
 911 -1 if
 912 .Dq Va lc.opaque
 913 is
 914 .Dv NULL
 915 .Pq with Va errno No set to Dv EINVAL ;
 916 1 if the
 917 .Fa category
 918 number is valid and there are logging channels in this
 919 .Fa category
 920 within the indicated logging context; 0 if the
 921 .Fa category
 922 number is invalid or there are no logging channels in this
 923 .Fa category
 924 within the indicated logging context.
 925 .It Fn log_new_syslog_channel
 926 .Dv NULL
 927 if
 928 .Xr malloc 3
 929 fails
 930 .Pq with Va errno No set to ENOMEM ;
 931 otherwise, a valid
 932 .Dv log_syslog Ns -type
 933 .Ft log_channel .
 934 .It Fn log_new_file_channel
 935 .Dv NULL
 936 if
 937 .Xr malloc 3
 938 fails
 939 .Pq with Va errno No set to ENOMEM ;
 940 otherwise, a valid
 941 .Dv log_file Ns -type
 942 .Ft log_channel .
 943 .It Fn log_new_null_channel
 944 .Dv NULL
 945 if
 946 .Xr malloc 3
 947 fails
 948 .Pq with Va errno No set to ENOMEM ;
 949 otherwise, a valid
 950 .Dv log_null Ns -type
 951 .Ft log_channel .
 952 .It Fn log_inc_references
 953 -1 if
 954 .Dq Fa chan
 955 is
 956 .Dv NULL
 957 .Pq with Va errno set to Dv EINVAL .
 958 Otherwise, 0.
 959 .It Fn log_dec_references
 960 -1 if
 961 .Dq Fa chan
 962 is
 963 .Dv NULL
 964 or its
 965 .Va references
 966 field is already <= 0
 967 .Pq with Va errno set to Dv EINVAL .
 968 Otherwise, 0.
 969 .It Fn log_free_channel
 970 -1 under the same conditions as
 971 .Fn log_dec_references ,
 972 above, including the setting of
 973 .Va errno ;
 974 0 otherwise.
 975 .El
 976 .\" .Sh ENVIRONMENT
 977 .Sh FILES
 978 .Bl -tag -width "isc/logging.h"
 979 .It Pa isc/logging.h
 980 include file for logging library
 981 .It Pa syslog.h
 982 .Xr syslog 3 Ns -style
 983 priorities
 984 .El
 985 .\" .Sh EXAMPLES
 986 .\" This next request is for sections 1, 6, 7 & 8 only
 987 .\"     (command return values (to shell) and
 988 .\"    fprintf/stderr type diagnostics)
 989 .\" .Sh DIAGNOSTICS
 990 .\" The next request is for sections 2 and 3 error
 991 .\" and signal handling only.
 992 .Sh ERRORS
 993 This table shows which functions can return the indicated error in the
 994 .Va errno
 995 variable; see the
 996 .Sx RETURN VALUES
 997 section, above, for more information.
 998 .Bl -tag -width "(any0other0value)0"
 999 .It Dv EINVAL
1000 .Fn log_open_stream ,
1001 .Fn log_close_stream ,
1002 .Fn log_get_stream ,
1003 .Fn log_get_filename ,
1004 .Fn log_add_channel ,
1005 .Fn log_remove_channel ,
1006 .Fn log_option ,
1007 .Fn log_category_is_active ,
1008 .Fn log_inc_references ,
1009 .Fn log_dec_references ,
1010 .Fn log_free_channel .
1011 .It Dv ENOENT
1012 .Fn log_remove_channel .
1013 .It Dv ENOMEM
1014 .Fn log_new_context ,
1015 .Fn log_add_channel ,
1016 .Fn log_new_syslog_channel ,
1017 .Fn log_new_file_channel ,
1018 .Fn log_new_null_channel .
1019 .It (any other value)
1020 returned via a pass-through of an error code from
1021 .Xr stat 2 ,
1022 .Xr open 2 ,
1023 or
1024 .Xr fdopen 3 ,
1025 which can occur in
1026 .Fn log_open_stream
1027 and functions which call it
1028 .Pq currently, only Fn log_vwrite .
1029 .El
1030 .Pp
1031 Additionally,
1032 .Fn log_vwrite
1033 and
1034 .Fn log_free_context
1035 will fail via
1036 .Fn assert
1037 if
1038 .Dq Va lc.opaque
1039 is
1040 .Dv NULL .
1041 The function
1042 .Fn log_vwrite
1043 can also exit with a critical error logged via
1044 .Xr syslog 3
1045 indicating a memory overrun
1046 .Sh SEE ALSO
1047 .Xr @INDOT@named @SYS_OPS_EXT@ ,
1048 .Xr syslog 3 .
1049 The HTML documentation includes a file,
1050 .Pa logging.html ,
1051 which has more information about this logging system.
1052 .\" .Sh STANDARDS
1053 .\" .Sh HISTORY
1054 .Sh AUTHORS
1055 Bob Halley...TODO
1056 .\" .Sh BUGS