geomyidae

A small C-based gopherd. (gopher://bitreich.org/1/scm/geomyidae)
git clone git://r-36.net/geomyidae
Log | Files | Refs | README | LICENSE

CGI.md (3191B)


      1 # INTRODUCTION TO CGI
      2 
      3 Geomyidae has  support for running  scripts on each request,  which will
      4 generate dynamic content.
      5 
      6 There are two modes: standard cgi  and dynamic cgi. (»CGI« as name was
      7 just taken, because that's easier to compare to the web.)
      8 
      9 
     10 ## PERMISSIONS
     11 
     12 The scripts are run using the permissions of geomyidae. It is advised to
     13 use the -g and -u options of geomyidae.
     14 
     15 
     16 ## BEFOREHAND
     17 
     18 In these examples C: is what the client sends and S: what the server is
     19 sending.
     20 
     21 
     22 ## CALLING CONVENTION
     23 
     24 Geomyidae will call the script like this:
     25 
     26 	% $gopherroot/test.cgi $search $arguments $host $port
     27 
     28 When it is a plain request, the arguments will have these values:
     29 
     30 	C: /test.cgi
     31 	-> $search = ""
     32 	-> $arguments = ""
     33 	-> $host = server host
     34 	-> $port = server port
     35 
     36 If the request is for a type 7 search element, then the entered string by
     37 the user will be seen as following:
     38 
     39 	C: /test.cgi	searchterm		(There is a TAB in-between)
     40 	-> $search = »searchterm«
     41 	-> $arguments = ""
     42 	-> $host = server host
     43 	-> $port = server port
     44 
     45 When you are trying to give your script some calling arguments, the syntax
     46 is:
     47 
     48 	C: /test.cgi?hello
     49 	-> $search = ""
     50 	-> $arguments = »hello«
     51 	-> $host = server host
     52 	-> $port = server port
     53 
     54 If both ways of input are combined, the variables are set as following:
     55 
     56 	C: /test.cgi?hello=world	searchterm	(Beware! A Tab!)
     57 	-> $search = »searchterm«
     58 	-> $arguments = »hello=world«
     59 	-> $host = server host
     60 	-> $port = server port
     61 
     62 ## REST CALLING CONVENTION
     63 
     64 There is a special mode in geomyidae to imitate REST calling abilities.
     65 
     66 When a user requests some non-existing path, geomyidae will start from
     67 the base and go up the path directories, until it reaches the first not
     68 existing directory.
     69 
     70 	C: /base/some/dir/that/does/not/exist?some-arguments	searchterm
     71 	-> /base exists
     72 	-> /some exists
     73 	-> /dir does not exist
     74 	-> search for index.cgi or index.dcgi in /base/some
     75 	-> if not found, display directory content
     76 	-> if found, call index.cgi or index.dcgi as follows:
     77 		-> $search = »searchterm«
     78 		-> $arguments = »/dir/that/does/not/exist?some-arguments«
     79 		-> $host = server host
     80 		-> $port = server port
     81 
     82 ## STANDARD CGI
     83 
     84 The file  extension »cgi« switches to  this mode, where the  output of
     85 the script is not interpreted at all  by the server and the script needs
     86 to send raw content.
     87 
     88 	% cat test.cgi
     89 	#!/bin/sh
     90 	echo "Hello my friend."
     91 	%
     92 
     93 The client will receive:
     94 
     95 	S: Hello my friend.
     96 
     97 
     98 ## DYNAMIC CGI
     99 
    100 For using  dynamic CGI, the  file needs to  end in »dcgi«,  which will
    101 switch on  the interpretation of the  returned lines by the  server. The
    102 interpreted for- mat is the same as in the .gph files.
    103 
    104 	% cat test.dcgi
    105 	#!/bin/sh
    106 	echo "[1|Some link|/somewhere|server|port]"
    107 	%
    108 
    109 Here  geomyidae will  interpret the  .gph format  and return  the valid
    110 gopher menu item.
    111 
    112 	S: 1Some link	/somewhere	gopher.r-36.net	70
    113 
    114 For outputting  large texts and  having minor hassles with  the content,
    115 prepend »t« to every line beginning with »t« or all lines:
    116 
    117 	% cat filereader.dcgi
    118 	#!/bin/sh
    119 	cat bigfile.txt | sed 's,^t,&&,'
    120 
    121 ## ENVIRONMENT VARIABLES
    122 
    123 Please see the manpage geomyidae(8) for all variables and their content.
    124 
    125 
    126 Have fun!
    127