| blob | 98b2aed9c6dc15c48ed9bac6489f19505ffe0859 |
1 .\" $Id: logging.mdoc,v 1.3 2004/03/09 06:30:08 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