ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2016--2017 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\"
5
.\" Permission to use, copy, modify, and distribute this software for any
6
.\" purpose with or without fee is hereby granted, provided that the above
7
.\" copyright notice and this permission notice appear in all copies.
8
.\"
9
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16
.\"
17
.Dd $Mdocdate$
18
.Dt KUTIL_OPENLOG 3
19
.Os
20
.Sh NAME
21
.Nm kutil_openlog
22
.Nd configure log message sink
23
.Sh LIBRARY
24
.Lb libkcgi
25
.Sh SYNOPSIS
26
.In sys/types.h
27
.In stdarg.h
28
.In stdint.h
29
.In kcgi.h
30
.Ft "int"
31
.Fo kutil_openlog
32
.Fa "const char *file"
33
.Fc
34
.Sh DESCRIPTION
35
The
36
.Fn kutil_openlog
37
function configures output for the
38
.Xr kutil_log 3
39
family of functions.
40
By default, these functions log to
41
.Dv stderr
42
and inherit the initial output buffering behaviour
43
.Pq see Xr setvbuf 3 .
44
.Pp
45
If
46
.Fa file
47
is not
48
.Dv NULL ,
49
.Fn kutil_openlog
50
first redirects
51
.Vt stderr
52
to
53
.Fa file .
54
Then, regardless of whether
55
.Fa file
56
is
57
.Dv NULL ,
58
the output buffering of the stream is set to line buffered.
59
.Pp
60
CGI scripts invoking long-running child processes via
61
.Xr fork 2
62
should use this function with a valid
63
.Fa file
64
as the web server might wait for all file descriptors to close before
65
closing the request connection.
66
.Sh RETURN VALUES
67
The
68
.Fn kutil_openlog
69
function returns zero on failure (system error) and non-zero on success.
70
If
71
.Fn kutil_openlog
72
fails to re-open
73
.Vt stderr ,
74
the output stream may no longer be operable: the caller should exit.
75
.Sh AUTHORS
76
The
77
.Fn kutil_openlog
78
function was written by
79
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
80
.Sh CAVEATS
81
In most situations,
82
.Fa file
83
is configured in the default log directory, which is not writable to the
84
CGI process.
85
Thus,
86
.Fa file
87
must be pre-created and be writable to the CGI process.
88
Otherwise,
89
.Fn kutil_openlog
90
will fail to create the file and exit with failure.
91