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