ksgi

1
.\"	$Id$
2
.\"
3
.\" Copyright (c) 2014, 2017--2018, 2020 Kristaps Dzonsons <kristaps@bsd.lv>
4
.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
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 THE AUTHOR DISCLAIMS ALL WARRANTIES
11
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR 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 OF
16
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17
.\"
18
.Dd $Mdocdate$
19
.Dt KHTTP_TEMPLATE 3
20
.Os
21
.Sh NAME
22
.Nm khttp_template ,
23
.Nm khttp_template_buf ,
24
.Nm khttp_template_fd
25
.Nd emit filled-in templates for kcgi
26
.Sh LIBRARY
27
.Lb libkcgi
28
.Sh SYNOPSIS
29
.In sys/types.h
30
.In stdarg.h
31
.In stdint.h
32
.In kcgi.h
33
.Ft enum kcgi_err
34
.Fo khttp_template
35
.Fa "struct kreq *req"
36
.Fa "const struct ktemplate *t"
37
.Fa "const char *filename"
38
.Fc
39
.Ft enum kcgi_err
40
.Fo khttp_template_buf
41
.Fa "struct kreq *req"
42
.Fa "const struct ktemplate *t"
43
.Fa "const char *buf"
44
.Fa "size_t sz"
45
.Fc
46
.Ft enum kcgi_err
47
.Fo khttp_template_fd
48
.Fa "struct kreq *req"
49
.Fa "const struct ktemplate *t"
50
.Fa "int fd"
51
.Fa "const char *filename"
52
.Fc
53
.Sh DESCRIPTION
54
Modify input by replacing keys in a template.
55
May only be called after
56
.Xr khttp_body 3 .
57
Output is written with
58
.Xr khttp_write 3
59
using the
60
.Fa req
61
previously allocated with
62
.Xr khttp_parse 3
63
or
64
.Xr khttp_fcgi_parse 3 .
65
The
66
.Xr khttp_templatex 3
67
family allows for alternative writers.
68
.Pp
69
All functions accept a template
70
.Fa t
71
consisting of the following fields:
72
.Bl -tag -width Ds
73
.It Fa "const char *const *key"
74
An array of keys to be replaced in the template.
75
.It Fa "size_t keysz"
76
The number of keys in
77
.Fa t->key .
78
.It Fa "void *arg"
79
An optional argument passed to
80
.Fa t->cb .
81
.It Fa "int (*cb)(size_t index, void *arg)"
82
The callback function invoked when a key at position
83
.Fa index ,
84
which is always less than
85
.Fa t->keysz ,
86
is found in
87
.Fa t->key .
88
The optional
89
.Fa arg
90
is passed the function.
91
The function must return zero on failure, non-zero on success.
92
.El
93
.Pp
94
If
95
.Fa t
96
is
97
.Dv NULL ,
98
the input is passed through to
99
.Xr khttp_write 3
100
without any processing.
101
.Pp
102
Otherwise, the input is passed to
103
.Xr khttp_write 3
104
until a key sequence in encountered matching a key in
105
.Fa t->key .
106
The callback
107
.Fa t->cb
108
is then invoked instead of printing the key sequence.
109
If there are multiple matching keys in
110
.Fa t->key ,
111
only one is used (which is not yet fixed).
112
If the key sequence is not found in
113
.Fa t->key ,
114
it is passed unchanged to
115
.Xr khttp_write 3 .
116
.Pp
117
The different input types are
118
.Fn khttp_template ,
119
which reads input from the file
120
.Fa filename ;
121
.Fn khttp_template_buf ,
122
which reads from a binary buffer
123
.Fa buf
124
of length
125
.Fa sz ;
126
and
127
.Fn khttp_template_fd ,
128
which reads from a file descriptor
129
.Fa fd
130
with optional file-name
131
.Fa fname
132
used only for logging purposes.
133
.Sh SYNTAX
134
Each substring of the input beginning and ending with a pair
135
of
136
.Dq at
137
signs,
138
.Cm @@ Ns Ar key Ns Cm @@ ,
139
is called a
140
.Qq key sequence .
141
Zero-length keys
142
.Cm @@@@
143
are allowed and match empty template keys.
144
If the
145
.Cm @@
146
pair is escaped with a single backslash,
147
.Cm \e@@ ,
148
the backslash is removed and it's emitted as
149
.Cm @@ .
150
.Pp
151
A key sequence may not contain an escaped pair: this is parsed as a
152
backslash followed by the trailing pair.
153
.Sh RETURN VALUES
154
These return an
155
.Ft enum kcgi_err
156
indicating the error state:
157
.Bl -tag -width KCGI_SYSTEM
158
.It Dv KCGI_OK
159
No error occurred.
160
.It Dv KCGI_ENOMEM
161
Memory allocation failed.
162
.It Dv KCGI_SYSTEM
163
A system call failed.
164
For example, writing to the output stream failed, or
165
.Fn khttp_template
166
failed to
167
.Xr open 2
168
.Fa filename .
169
.It Dv KCGI_FORM
170
.Fa t->cb
171
returned 0.
172
.El
173
.Sh EXAMPLES
174
The following simple example takes a buffer
175
.Fa buf
176
and applies the replacement template of two values, writing it to the
177
current context
178
.Fa req .
179
.Bd -literal -offset indent
180
static int writer(size_t idx, void *arg)
181
{
182
  struct kreq *r = arg;
183
  if (idx == 0)
184
    khttp_puts(r, "foo-value");
185
  else if (idx == 1)
186
    khttp_puts(r, "bar-value");
187
  return 1;
188
}
189

190
enum kcgi_err format(struct kreq *r)
191
{
192
  const char *const keys[] = { "foo", "bar" };
193
  struct ktemplate t = {
194
    .key = keys,
195
    .keysz = 2,
196
    .arg = r,
197
    .cb = writer
198
  };
199
  const char *buf = "foo=@@foo@@, bar=@@bar@@";
200
  return khttp_template_buf(r, &t, buf, strlen(buf));
201
}
202
.Ed
203
.Pp
204
The function will produce
205
.Qq foo=foo-value, bar=bar-value .
206
.Sh SEE ALSO
207
.Xr kcgi 3 ,
208
.Xr khttp_body 3 ,
209
.Xr khttp_parse 3 ,
210
.Xr khttp_templatex 3 ,
211
.Xr khttp_write 3
212
.Sh AUTHORS
213
Written by
214
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
215