Serving the Output of a Program or Script

   Sometimes it is convenient to have the server return the output of a
   program or script. This capability is built into _gn_. Assuming you
   have a program in a file "prog" which returns some text you can make
   its output be an item on your server's menu with a menu entry like

     Name=Program output
     Type=0
     Path=exec0::/dir/prog

   
   
   The phrase "exec" says to run the program "prog" which must be
   executable by the _gn_ userid (probably "nobody"). The "0" after the
   exec says this is a text file. exec can return most types, including 0
   (text), 1 (menus), 9 (binaries), s (sound), I (image). Scripts or
   programs returning type 1 documents must produce a document in the
   format of a .cache file. This format is described in the file
   /docs/technical.notes. To specify a type the single character type is
   appended to the word exec in the path and the Type=0 line above is not
   really necessary. Thus if you wanted to return the output of a program
   which is in the format of an image file you might have an entry like

     Name=Image program output
     Path=execI::/dir/prog
     ContentType=image/gif

   
   
   The pair of colons in the path can contain arguments to the program.
   For security reasons none of the characters

     ; ` ' | \ * ? - ~ < > ^ ( ) [ ] { } & $ / or \

   
   
   are allowed in the arguments to programs. Thus, if you want to run a
   command like "prog -u #!/bin/sh exec /fullpath/prog -u
   
   and make this script be what _gn_ executes.
   
   It would be nice to have the client query the user for a word or
   phrase and have this passed to the program as an argument.
   Unfortunately the basic gopher protocol protocol does not allow this.
   In the meantime here is an example of how to work around the
   difficulty. This is a simple example of how to make a search item
   which will print all the lines of a file containing a match for a
   given word. It requires two very small shell scripts. The first, let's
   call it "script1" would have a menu file entry like

     Name=Search for a word in Myfile
     Path=7/dir/script1

   
   
   in gn_root/dir/menu and the script itself, gn_root/dir/script1, would
   contain only the lines

     #!/bin/sh
     echo "0Matches for $1: <tab>exec0:$1:/dir2/script2<tab>myhost.edu<tab>70"

   
   
   with <tab> replaced by the tab character. When a client selects this
   item and returns a search term the script creates a new menu with one
   item "on the fly". The one menu item is "Matches for X" where X is the
   search term entered by the user.
   
   When this "Matches" item is selected and sent to the server the second
   script "script2" is invoked with argument set to the search term
   already entered. Script2 should contain the lines

     #!/bin/sh
     grep "$1" /complete/path/of/Myfile

   
   
   which will then output the matching lines. Recall that for security
   reasons every file, including scripts, which will be served, must be
   in a .cache file. To achieve this there must be a menu item for
   script2 in gn_root/dir2/menu like

     Name=Anything
     Path=exec0::/dir2/script2

   
   
   One normally puts this in a different directory (gn_root/dir2 in this
   example) which is not in your gn hierarchy and hence this item won't
   show on any menu. It is only there so that when gn is asked to provide
   the output of script2 in response to the "on the fly menu", it can
   find script2 in a .cache file and hence serve its output.
   
   One final remark about this example. It will work fine it the search
   term is a normal word or part of a word. However, regular expressions
   used by grep often contain special characters which by default are not
   allowed in arguments to scripts as mentioned above. This applies only
   to arguments to scripts, as in this example, and regular expressions
   work fine with the built searches in gn described above.
   
   There is also support in _gn_ for scripts which comply with the CGI
   (Common Gateway Interface) standard. This allows the use of a growing
   collection of scripts which are written for HTTP servers supporting
   the standard. There is an archive of such scripts. The use of these
   scripts is similar to the _exec0_ types described above but with a
   somewhat different syntax. Your menu file entry might look like

     Name=A CGI script
     Path=CGI/dir/script.cgi

   
   
   The initial _CGI_ in the Path field indicates that this is a CGI item.
   In some respects the syntax is rather awkward, but it is made
   necessary by complying with the standard which was really intended for
   servers with a quite different design.
   
   In particular the name of the script _must_ end with the suffix ".cgi"
   (or a replacement set at compile time in the file config.h) and no
   directory above the script in the data hierarchy may end in this
   suffix. The reason for this is the unusual way in which arguments to
   CGI scripts must be transmitted to the script. Instead of enclosing
   them in colons as with the _exec0_ examples above, the arguments are
   appended to the end of the path as if they were a file name. Thus to
   execute the script above with argument "foo" you would use the URL
   _http://host/CGI/dir/script.cgi/foo_. This URL is frequently generated
   by the script itself with the extra so called "path information" (the
   "foo" in this example) used as a way of saving state. It is also
   possible to put this in the menu file so the script will be executed
   with that argument.

     Name=A CGI script
     Path=CGI/dir/script.cgi/foo

   
   
.