libgcgi.3 - libgcgi - REST library for Gopher
HTML git clone git://bitreich.org/libgcgi/ git://enlrupgkhuxnvlhsf6lc3fziv5h2hhfrinws65d7roiv6bfj7d652fid.onion/libgcgi/
DIR Log
DIR Files
DIR Refs
DIR Tags
DIR README
DIR LICENSE
---
libgcgi.3 (7912B)
---
1 .Dd $Mdocdate: August 01 2022 $
2 .Dt LIBGCGI 3
3 .Os
4 .
5 .
6 .Sh NAME
7 .
8 .Nm gcgi_handle_request ,
9 .Nm gcgi_fatal ,
10 .Nm gcgi_template ,
11 .Nm gcgi_set_var ,
12 .Nm gcgi_get_var ,
13 .Nm gcgi_free_var_list ,
14 .Nm gcgi_read_var_list ,
15 .Nm gcgi_write_var_list ,
16 .Nm gcgi_gopher_search ,
17 .Nm gcgi_gopher_path ,
18 .Nm gcgi_gopher_query ,
19 .Nm gcgi_gopher_host ,
20 .Nm gcgi_gopher_port ,
21 .Nd REST library for Gopher
22 .
23 .
24 .Sh SYNOPSIS
25 .
26 .In libgcgi.h
27 .
28 .Ft "void" Fn gcgi_handle_request "struct gcgi_handler h[]" "char **argv" "int argc"
29 .Ft "void" Fn gcgi_fatal "char *fmt" "..."
30 .Ft "void" Fn gcgi_template "char const *path" "struct gcgi_var_list *vars"
31 .Ft "void" Fn gcgi_set_var "struct gcgi_var_list *vars" "char *key" "char *val"
32 .Ft "char *" Fn gcgi_get_var "struct gcgi_var_list *vars" "char *key"
33 .Ft "void" Fn gcgi_free_var_list "struct gcgi_var_list *vars"
34 .Ft "void" Fn gcgi_read_var_list "struct gcgi_var_list *vars" "char *path"
35 .Ft "int" Fn gcgi_write_var_list "struct gcgi_var_list *vars" "char *path"
36 .Vt char *gcgi_gopher_search
37 .Vt char *gcgi_gopher_path
38 .Vt char *gcgi_gopher_host
39 .Vt char *gcgi_gopher_port
40 .Vt struct gcgi_var_list gcgi_gopher_query
41 .
42 .
43 .Sh DESCRIPTION
44 .
45 This library is a C wrapper around the
46 .Xr geomyidae 8
47 new CGI interface, which permits REST applications to be written for Gopher.
48 In this mode,
49 .Xr geomyidae 8
50 directs all requests to a single binary in charge of handling all paths,
51 rather than trying to serve a file.
52 .
53 .
54 .Ss Request Handling
55 .
56 The central element of the library is an array of structures,
57 using appropriate handler depending on the query path.
58 .Pp
59 .Bd -literal
60 struct gcgi_handler {
61 char const *glob;
62 void (*fn)(char **matches);
63 };
64 .Ed
65 .
66 .Pp
67 The
68 .Vt glob
69 is a string against which the path (everything in the query before the
70 .Dq "?" )
71 will be matched against.
72 .Pp
73 The
74 .Vt fn
75 function pointer will be called, with an array of matches passed as argument.
76 There are as many matches populated as there are
77 .Dq "*"
78 in
79 .Vt glob .
80 .
81 .Pp
82 .Bl -tag
83 .
84 .It Ft "void" Fn gcgi_handle_request "struct gcgi_handler h[]" "int argc" "char **argv"
85 Given an array of handlers
86 .Fa h ,
87 call the first function pointer that matches.
88 .Fa argc
89 and
90 .Fa argv
91 should be set to the program ones to extract the arguments given by
92 .Xr geomyidae 8 .
93 The
94 .Fa h
95 struct is an array of
96 .Vt struct gcgi_handler :
97 .
98 .El
99 .
100 .
101 .Ss Content Generation
102 .
103 According to
104 .Xr geomyidae 8
105 behavior, the output format will be:
106 .Bl -bullet -compact -width 1n
107 .
108 .It
109 a raw gophermap if the binary is
110 .Dq index.cgi ,
111 .It
112 a
113 .Xr geomyidae 8
114 .Sq gph
115 format if the binary is
116 .Dq index.dcgi .
117 .El
118 .
119 .Pp
120 .Bl -tag
121 .
122 .It Ft "void" Fn gcgi_fatal "char *fmt" "..."
123 Prints an error message formatted by
124 .Fa fmt
125 and
126 .Xr exit 3
127 the program with status 1.
128 .
129 .It Ft "void" Fn gcgi_template "char const *path" "struct gcgi_var_list *vars"
130 Format the template at
131 .Fa path
132 replacing every occurence of
133 .Dq {{key}}
134 by the matching value by searching in
135 .Fa vars .
136 .
137 .It Vt void Fn gcgi_print_gophermap "char type" "char *desc" "char *path" "char *host" "char *port"
138 Print a gophermap entry line with
139 .Fa type ,
140 .Fa desc ,
141 .Fa path ,
142 .Fa host ,
143 .Fa port
144 to be set to the chosen value as described in RFC 1436.
145 Both
146 .Fa host
147 and
148 .Fa port
149 are NULL, default values will be used.
150
151 .It Ft void Fn gcgi_print_gph "char type" "char *desc" "char *path" "char *host" "char *port"
152 Print a gph entry line with
153 .Fa type ,
154 .Fa desc ,
155 .Fa path ,
156 .Fa host ,
157 .Fa port
158 to be set to the chosen value as described in
159 .Xr geomyidae 8
160 manual page.
161 If
162 .Fa host
163 or
164 .Fa port
165 are NULL, default values will be used.
166 .
167 .El
168 .
169 .
170 .Ss Variable List Handling
171 .
172 A common data format is used for handling lists of variables:
173 .Bl -bullet -compact -width 1n
174 .It
175 For parsing a simple text-based database format and writing it back.
176 .It
177 For storing the parsed query string in
178 .Vt gcgi_gopher_query .
179 .It
180 For passing variables to expand in the templates.
181 .El
182 .
183 .Pp
184 .Bl -tag
185 .
186 .It Ft "void" Fn gcgi_set_var "struct gcgi_var_list *vars" "char *key" "char *val"
187 Overwrite with
188 .Fa val
189 the value of a variable matching
190 .Fa key
191 of
192 .Fa vars .
193 The
194 .Fa key
195 and
196 .Fa val
197 buffers are not duplicated, and must remain valid at all time they need to be
198 accessible, such as through
199 .Fn gcgi_get_var .
200 .
201 .It Ft "char *" Fn gcgi_get_var "struct gcgi_var_list *vars" "char *key"
202 Get the value of the variable of
203 .Fa vars
204 matching
205 .Fa key
206 or NULL if none match.
207 .
208 .It Ft "void" Fn gcgi_free_var_list "struct gcgi_var_list *vars"
209 Free memory used by a list of variable.
210 This only frees the memory allocated by this library.
211 .
212 .It Ft "void" Fn gcgi_read_var_list "struct gcgi_var_list *vars" "char *path"
213 Store all variables from
214 .Fa path
215 onto variables in
216 .Fa vars .
217 The file format is similar to RFC822 messages or HTTP headers:
218 .Bl -bullet -compact -width 1n
219 .It
220 One line per variable, with a key=value format.
221 .It
222 The key is everything at the beginning of the line until the occurence of
223 .Dq ":" .
224 .It
225 The value is everything after
226 .Dq ": " .
227 .It
228 After the list of variables, an empty line declares the body of the message,
229 which continues until the end and is stored in a
230 .Dq text
231 key.
232 .El
233 .
234 .It Ft "int" Fn gcgi_write_var_list "struct gcgi_var_list *vars" "char *path"
235 Encode the variable list
236 .Fa vars
237 into a new file at
238 .Fa path .
239 A temporary file will be created in the meantime,
240 and the replacement will be atomic so that no partial write can occur.
241 The
242 .Dq text
243 special key will be turned into the body of the message after an empty line
244 instead of a variable on its own line.
245 .
246 .El
247 .
248 .
249 .Ss Global Variables
250 .
251 These variables are filled with the components of the query.
252 They will only be valid after
253 .Fn handle_request
254 is called.
255 .
256 .Pp
257 .Bl -tag
258 .
259 .It Vt char *gcgi_gopher_search
260 From argv[1], this is the search string, passed after a tab in
261 the gopher protocol for item type
262 .Dq 7 .
263 .
264 .It Vt char *gcgi_gopher_path
265 From argv[2], this is the query path.
266 It is the full query without the search string and with the query string removed.
267 .
268 .It Vt struct gcgi_var_list gcgi_gopher_query
269 From argv[2], this is the query string stored as a key-value
270 .Vt gcgi_var_list .
271 It is extracted from the part of the query after the
272 .Dq ? ,
273 usually formated as
274 .Dq ?key1=value1&key2=value2&key3=value3
275 .
276 .It Vt char *gcgi_gopher_host
277 From argv[3], this is the current host name configured in
278 .Xr geomyidae 8 .
279 It is what to use as a
280 .Sq host
281 in links printed out.
282 .
283 .It Vt char *gcgi_gopher_port
284 From argv[4], this is the current port number configured in
285 .Xr geomyidae 8 .
286 It is what to use as a
287 .Sq port
288 in links printed out.
289 .
290 .El
291 .
292 .
293 .Sh EXAMPLES
294 .
295 .
296 .Bd -literal
297 #include "libgcgi.h"
298
299 /* implementation of each handler here */
300
301 static struct gcgi_handler handlers[] = {
302 { "/", page_home },
303 { "/song", page_song_list },
304 { "/song/*", page_song_item },
305 { "*", page_not_found },
306 { NULL, NULL },
307 };
308
309 int
310 main(int argc, char **argv)
311 {
312 /* privilege dropping, chroot and/or syscall restriction here */
313
314 gcgi_handle_request(handlers, argv, argc);
315 return 0;
316 }
317 .Ed
318 .
319 .
320 .Sh ENVIRONMENT VARIABLES
321 .
322 .Nm libgcgi
323 does not use environment variable, but the application code can make use of them.
324 The environment variables applied to
325 .Xr geomyidae 8
326 will be inherited and accessible.
327 .
328 .
329 .Sh BUGS
330 .
331 To debug
332 .Nm libgcgi ,
333 it is possible to call it on a command line, which will show all logging and error messages displayed on stderr:
334 .
335 .Bd -literal
336 $ ./index.cgi "" "/song/never-bored-of-adventure?lyrics=1&comments=1" "" ""
337 .Ed
338 .
339 .
340 .Sh CAVEATS
341 .
342 The Gopher protocol is not designed for file upload.
343 A dedicated file upload protocol such as SFTP or FTP may be used instead.
344 .
345 .Pp
346 The Gopher protocol is not designed for dynamic scripting.
347 A dedicated remote interface protocol such as SSH or telnet may be used instead.
348 .
349 .
350 .Sh SEE ALSO
351 .
352 .Xr geomyidae 8
353 .
354 .
355 .Sh AUTHORS
356 .
357 .Bl -ohang -compact
358 .It
359 .An Josuah Demangeon Aq Mt me@josuah.net
360 .It
361 .Lk "The Bitreich Project" gopher://bitreich.org
362 .El