cgi-fcgi-perl: wip, doc comment

diff --git a/cprogs/cgi-fcgi-perl.c b/cprogs/cgi-fcgi-perl.c
new file mode 100644 (file)
index 0000000..62c5831
--- /dev/null
+++ b/cprogs/cgi-fcgi-perl.c
@@ -0,0 +1,57 @@
+/*
+ * "Interpreter" that you can put in #! like this
+ *   #!/usr/bin/cgi-fcgi-perl [<options>]
+ *
+ * The result is a program which looks, when executed via the #!
+ * line, like a CGI program.  But the perl script inside will
+ * be executed via /usr/bin/perl in fcgi.
+ *
+ * Options:
+ *
+ *  -M<ident>
+ *          Use <ident> rather than hex(sha256(<script>))
+ *          as the basename of the leafname of the fcgi rendezvous
+ *          socket.  If <ident> contains only hex digit characters it
+ *          ought to be no more than 32 characters.
+ *
+ *  -M<numservers>
+ *         Start <numservers> instances of the program.  This
+ *         determines the maximum concurrency.  (Note that unlike
+ *         speedy, the specified number of servers is started
+ *         right away.)  The default is 4.
+ *
+ * cgi-fcgi-perl automatically expires old sockets, including
+ * ones where the named perl script is out of date.
+ */
+
+/*
+ * Uses one of two directories
+ *   /var/run/user/<UID>/cgi-fcgi-perl/
+ *   ~/.cgi-fcgi-perl/<node>/
+ * and inside there uses these paths
+ *   s<ident>
+ *   g<inum>
+ *
+ * If -M<ident> is not specified then an initial substricg of the
+ * lowercase hex of the sha256 of the <script> (ie, our argv[1]) is
+ * used.  The substring is chosen so that the whole path is 10 bytes
+ * shorter than sizeof(sun_path).  But always at least 33 characters.
+ *
+ * Algorithm:
+ *  - see if /var/run/user exists
+ *       if so, lstat /var/run/user/<UID> and check that
+ *         we own it and it's X700; if not, fail
+ *         if it's ok then <base> is /var/run/user/<UID>
+ *       otherwise, look for and maybe create ~/.cgi-fcgi-perl
+ *         (where ~ is HOME or from getpwuid)
+ *         and then <base> is ~/.cgi-fcgi-perl/<node>
+ *  - calculate pathname (checking <ident> length is OK)
+ *  - check for and maybe create <base>
+ *  - stat and lstat the <script>
+ *  - stat the socket and check its timestamp
+ *       if it is too hold, rename it to g<inum> (where
+ *       <inum> is in decimal)
+ *       and run garbage collection
+ *  - run  cgi-fcgi -connect SOCKET SCRIPT
+ */
+