iREADME - 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 iREADME (8346B) Err bitreich.org 70 i--- Err bitreich.org 70 i 1 LIBGCGI(3) Library Functions Manual LIBGCGI(3) Err bitreich.org 70 i 2 Err bitreich.org 70 i 3 NAME Err bitreich.org 70 i 4 gcgi_handle_request, gcgi_fatal, gcgi_template, gcgi_set_var, Err bitreich.org 70 i 5 gcgi_get_var, gcgi_free_var_list, gcgi_read_var_list, Err bitreich.org 70 i 6 gcgi_write_var_list, gcgi_gopher_search, gcgi_gopher_path, Err bitreich.org 70 i 7 gcgi_gopher_query, gcgi_gopher_host, gcgi_gopher_port, – REST library for Err bitreich.org 70 i 8 Gopher Err bitreich.org 70 i 9 Err bitreich.org 70 i 10 SYNOPSIS Err bitreich.org 70 i 11 #include Err bitreich.org 70 i 12 Err bitreich.org 70 i 13 void Err bitreich.org 70 i 14 gcgi_handle_request(struct gcgi_handler h[], char **argv, int argc); Err bitreich.org 70 i 15 Err bitreich.org 70 i 16 void Err bitreich.org 70 i 17 gcgi_fatal(char *fmt, ...); Err bitreich.org 70 i 18 Err bitreich.org 70 i 19 void Err bitreich.org 70 i 20 gcgi_template(char const *path, struct gcgi_var_list *vars); Err bitreich.org 70 i 21 Err bitreich.org 70 i 22 void Err bitreich.org 70 i 23 gcgi_set_var(struct gcgi_var_list *vars, char *key, char *val); Err bitreich.org 70 i 24 Err bitreich.org 70 i 25 char * Err bitreich.org 70 i 26 gcgi_get_var(struct gcgi_var_list *vars, char *key); Err bitreich.org 70 i 27 Err bitreich.org 70 i 28 void Err bitreich.org 70 i 29 gcgi_free_var_list(struct gcgi_var_list *vars); Err bitreich.org 70 i 30 Err bitreich.org 70 i 31 void Err bitreich.org 70 i 32 gcgi_read_var_list(struct gcgi_var_list *vars, char *path); Err bitreich.org 70 i 33 Err bitreich.org 70 i 34 int Err bitreich.org 70 i 35 gcgi_write_var_list(struct gcgi_var_list *vars, char *path); Err bitreich.org 70 i 36 Err bitreich.org 70 i 37 char *gcgi_gopher_search Err bitreich.org 70 i 38 char *gcgi_gopher_path Err bitreich.org 70 i 39 char *gcgi_gopher_host Err bitreich.org 70 i 40 char *gcgi_gopher_port Err bitreich.org 70 i 41 struct gcgi_var_list gcgi_gopher_query Err bitreich.org 70 i 42 Err bitreich.org 70 i 43 DESCRIPTION Err bitreich.org 70 i 44 This library is a C wrapper around the geomyidae(8) new CGI interface, Err bitreich.org 70 i 45 which permits REST applications to be written for Gopher. In this mode, Err bitreich.org 70 i 46 geomyidae(8) directs all requests to a single binary in charge of Err bitreich.org 70 i 47 handling all paths, rather than trying to serve a file. Err bitreich.org 70 i 48 Err bitreich.org 70 i 49 Request Handling Err bitreich.org 70 i 50 The central element of the library is an array of structures, using Err bitreich.org 70 i 51 appropriate handler depending on the query path. Err bitreich.org 70 i 52 Err bitreich.org 70 i 53 struct gcgi_handler { Err bitreich.org 70 i 54 char const *glob; Err bitreich.org 70 i 55 void (*fn)(char **matches); Err bitreich.org 70 i 56 }; Err bitreich.org 70 i 57 Err bitreich.org 70 i 58 The glob is a string against which the path (everything in the query Err bitreich.org 70 i 59 before the “?”) will be matched against. Err bitreich.org 70 i 60 Err bitreich.org 70 i 61 The fn function pointer will be called, with an array of matches passed Err bitreich.org 70 i 62 as argument. There are as many matches populated as there are “*” in Err bitreich.org 70 i 63 glob. Err bitreich.org 70 i 64 Err bitreich.org 70 i 65 void gcgi_handle_request(struct gcgi_handler h[], int argc, char **argv) Err bitreich.org 70 i 66 Given an array of handlers h, call the first function pointer Err bitreich.org 70 i 67 that matches. argc and argv should be set to the program ones to Err bitreich.org 70 i 68 extract the arguments given by geomyidae(8). The h struct is an Err bitreich.org 70 i 69 array of struct gcgi_handler: Err bitreich.org 70 i 70 Err bitreich.org 70 i 71 Content Generation Err bitreich.org 70 i 72 According to geomyidae(8) behavior, the output format will be: Err bitreich.org 70 i 73 • a raw gophermap if the binary is “index.cgi”, Err bitreich.org 70 i 74 • a geomyidae(8) ‘gph’ format if the binary is “index.dcgi”. Err bitreich.org 70 i 75 Err bitreich.org 70 i 76 void gcgi_fatal(char *fmt, ...) Err bitreich.org 70 i 77 Prints an error message formatted by fmt and exit(3) the program Err bitreich.org 70 i 78 with status 1. Err bitreich.org 70 i 79 Err bitreich.org 70 i 80 void gcgi_template(char const *path, struct gcgi_var_list *vars) Err bitreich.org 70 i 81 Format the template at path replacing every occurence of Err bitreich.org 70 i 82 “{{key}}” by the matching value by searching in vars. Err bitreich.org 70 i 83 Err bitreich.org 70 i 84 void gcgi_print_gophermap(char type, char *desc, char *path, char *host, Err bitreich.org 70 i 85 char *port) Err bitreich.org 70 i 86 Print a gophermap entry line with type, desc, path, host, port to Err bitreich.org 70 i 87 be set to the chosen value as described in RFC 1436. Both host Err bitreich.org 70 i 88 and port are NULL, default values will be used. Err bitreich.org 70 i 89 Err bitreich.org 70 i 90 Err bitreich.org 70 i 91 void gcgi_print_gph(char type, char *desc, char *path, char *host, char Err bitreich.org 70 i 92 *port) Err bitreich.org 70 i 93 Print a gph entry line with type, desc, path, host, port to be Err bitreich.org 70 i 94 set to the chosen value as described in geomyidae(8) manual page. Err bitreich.org 70 i 95 If host or port are NULL, default values will be used. Err bitreich.org 70 i 96 Err bitreich.org 70 i 97 Variable List Handling Err bitreich.org 70 i 98 A common data format is used for handling lists of variables: Err bitreich.org 70 i 99 • For parsing a simple text-based database format and writing it back. Err bitreich.org 70 i 100 • For storing the parsed query string in gcgi_gopher_query. Err bitreich.org 70 i 101 • For passing variables to expand in the templates. Err bitreich.org 70 i 102 Err bitreich.org 70 i 103 void gcgi_set_var(struct gcgi_var_list *vars, char *key, char *val) Err bitreich.org 70 i 104 Overwrite with val the value of a variable matching key of vars. Err bitreich.org 70 i 105 The key and val buffers are not duplicated, and must remain valid Err bitreich.org 70 i 106 at all time they need to be accessible, such as through Err bitreich.org 70 i 107 gcgi_get_var(). Err bitreich.org 70 i 108 Err bitreich.org 70 i 109 char * gcgi_get_var(struct gcgi_var_list *vars, char *key) Err bitreich.org 70 i 110 Get the value of the variable of vars matching key or NULL if Err bitreich.org 70 i 111 none match. Err bitreich.org 70 i 112 Err bitreich.org 70 i 113 void gcgi_free_var_list(struct gcgi_var_list *vars) Err bitreich.org 70 i 114 Free memory used by a list of variable. This only frees the Err bitreich.org 70 i 115 memory allocated by this library. Err bitreich.org 70 i 116 Err bitreich.org 70 i 117 void gcgi_read_var_list(struct gcgi_var_list *vars, char *path) Err bitreich.org 70 i 118 Store all variables from path onto variables in vars. The file Err bitreich.org 70 i 119 format is similar to RFC822 messages or HTTP headers: Err bitreich.org 70 i 120 • One line per variable, with a key=value format. Err bitreich.org 70 i 121 • The key is everything at the beginning of the line until the Err bitreich.org 70 i 122 occurence of “:”. Err bitreich.org 70 i 123 • The value is everything after “: ”. Err bitreich.org 70 i 124 • After the list of variables, an empty line declares the body Err bitreich.org 70 i 125 of the message, which continues until the end and is stored in Err bitreich.org 70 i 126 a “text” key. Err bitreich.org 70 i 127 Err bitreich.org 70 i 128 int gcgi_write_var_list(struct gcgi_var_list *vars, char *path) Err bitreich.org 70 i 129 Encode the variable list vars into a new file at path. A Err bitreich.org 70 i 130 temporary file will be created in the meantime, and the Err bitreich.org 70 i 131 replacement will be atomic so that no partial write can occur. Err bitreich.org 70 i 132 The “text” special key will be turned into the body of the Err bitreich.org 70 i 133 message after an empty line instead of a variable on its own Err bitreich.org 70 i 134 line. Err bitreich.org 70 i 135 Err bitreich.org 70 i 136 Global Variables Err bitreich.org 70 i 137 These variables are filled with the components of the query. They will Err bitreich.org 70 i 138 only be valid after handle_request() is called. Err bitreich.org 70 i 139 Err bitreich.org 70 i 140 char *gcgi_gopher_search Err bitreich.org 70 i 141 From argv[1], this is the search string, passed after a tab in Err bitreich.org 70 i 142 the gopher protocol for item type “7”. Err bitreich.org 70 i 143 Err bitreich.org 70 i 144 char *gcgi_gopher_path Err bitreich.org 70 i 145 From argv[2], this is the query path. It is the full query Err bitreich.org 70 i 146 without the search string and with the query string removed. Err bitreich.org 70 i 147 Err bitreich.org 70 i 148 struct gcgi_var_list gcgi_gopher_query Err bitreich.org 70 i 149 From argv[2], this is the query string stored as a key-value Err bitreich.org 70 i 150 gcgi_var_list. It is extracted from the part of the query after Err bitreich.org 70 i 151 the “”?, usually formated as Err bitreich.org 70 i 152 “?key1=value1&key2=value2&key3=value3” Err bitreich.org 70 i 153 Err bitreich.org 70 i 154 char *gcgi_gopher_host Err bitreich.org 70 i 155 From argv[3], this is the current host name configured in Err bitreich.org 70 i 156 geomyidae(8). It is what to use as a ‘host’ in links printed Err bitreich.org 70 i 157 out. Err bitreich.org 70 i 158 Err bitreich.org 70 i 159 char *gcgi_gopher_port Err bitreich.org 70 i 160 From argv[4], this is the current port number configured in Err bitreich.org 70 i 161 geomyidae(8). It is what to use as a ‘port’ in links printed Err bitreich.org 70 i 162 out. Err bitreich.org 70 i 163 Err bitreich.org 70 i 164 EXAMPLES Err bitreich.org 70 i 165 #include "libgcgi.h" Err bitreich.org 70 i 166 Err bitreich.org 70 i 167 /* implementation of each handler here */ Err bitreich.org 70 i 168 Err bitreich.org 70 i 169 static struct gcgi_handler handlers[] = { Err bitreich.org 70 i 170 { "/", page_home }, Err bitreich.org 70 i 171 { "/song", page_song_list }, Err bitreich.org 70 i 172 { "/song/*", page_song_item }, Err bitreich.org 70 i 173 { "*", page_not_found }, Err bitreich.org 70 i 174 { NULL, NULL }, Err bitreich.org 70 i 175 }; Err bitreich.org 70 i 176 Err bitreich.org 70 i 177 int Err bitreich.org 70 i 178 main(int argc, char **argv) Err bitreich.org 70 i 179 { Err bitreich.org 70 i 180 /* privilege dropping, chroot and/or syscall restriction here */ Err bitreich.org 70 i 181 Err bitreich.org 70 i 182 gcgi_handle_request(handlers, argv, argc); Err bitreich.org 70 i 183 return 0; Err bitreich.org 70 i 184 } Err bitreich.org 70 i 185 Err bitreich.org 70 i 186 ENVIRONMENT VARIABLES Err bitreich.org 70 i 187 libgcgi does not use environment variable, but the application code can Err bitreich.org 70 i 188 make use of them. The environment variables applied to geomyidae(8) will Err bitreich.org 70 i 189 be inherited and accessible. Err bitreich.org 70 i 190 Err bitreich.org 70 i 191 BUGS Err bitreich.org 70 i 192 To debug libgcgi, it is possible to call it on a command line, which will Err bitreich.org 70 i 193 show all logging and error messages displayed on stderr: Err bitreich.org 70 i 194 Err bitreich.org 70 i 195 $ ./index.cgi "" "/song/never-bored-of-adventure?lyrics=1&comments=1" "" "" Err bitreich.org 70 i 196 Err bitreich.org 70 i 197 CAVEATS Err bitreich.org 70 i 198 The Gopher protocol is not designed for file upload. A dedicated file Err bitreich.org 70 i 199 upload protocol such as SFTP or FTP may be used instead. Err bitreich.org 70 i 200 Err bitreich.org 70 i 201 The Gopher protocol is not designed for dynamic scripting. A dedicated Err bitreich.org 70 i 202 remote interface protocol such as SSH or telnet may be used instead. Err bitreich.org 70 i 203 Err bitreich.org 70 i 204 SEE ALSO Err bitreich.org 70 i 205 geomyidae(8) Err bitreich.org 70 i 206 Err bitreich.org 70 i 207 AUTHORS Err bitreich.org 70 i 208 Josuah Demangeon Err bitreich.org 70 i 209 gopher://bitreich.org: The Bitreich Project Err bitreich.org 70 i 210 Err bitreich.org 70 i 211 LIBGCGI(3) Library Functions Manual LIBGCGI(3) Err bitreich.org 70 .