with-authinfo-kludge.1: Fix the various lies in the manual.

diff --git a/with-authinfo-kludge.1 b/with-authinfo-kludge.1
index 5a67856..da2d0e6 100644 (file)
--- a/with-authinfo-kludge.1
+++ b/with-authinfo-kludge.1
@@ -362,8 +362,10 @@ set up by the
 .B via
 parameter.
 The default is to use
 .B via
 parameter.
 The default is to use

-.\" FIXME Fuck you openssh
-127.1.0.1:119.
+127.1.0.1:1119,
+because OpenSSH refuses to try to listen on low-numbered ports
+rather than trying it and seeing whether it would work
+(which it would, in this case).

 It is
 .I not
 a problem for multiple servers to use the same address:
 It is
 .I not
 a problem for multiple servers to use the same address:


@@ -436,26 +438,31 @@ option is given, then it is read as a configuration file.
 A fatal error is reported if the file does not exist,
 or cannot be read for some other reason.
 .hP 3.
 A fatal error is reported if the file does not exist,
 or cannot be read for some other reason.
 .hP 3.

-The user's home directory is determined, as follows.
-If the environment variable
-.B HOME
-is set, then its value is used.

 Let
 .I home
 Let
 .I home

-be the home directory so determined, if any.
+be the value of the environment variable
+.BR HOME ;
+if this variable is not set, then
+.I home
+is not defined.

 .hP 4.
 .hP 4.

-A `configuration home' directory is determined, as follows.
+A `configuration path' is built, as follows.

 If the environment variable
 .B XDG_CONFIG_HOME
 If the environment variable
 .B XDG_CONFIG_HOME

-is set, then its value is used.
-Otherwise, the configuration home is
+is set, then its value is the first entry in the path;
+otherwise the first entry is

 .IB home /.config \fR;
 a fatal error is reported at this point
 if no home directory was determined.
 .IB home /.config \fR;
 a fatal error is reported at this point
 if no home directory was determined.

-Let
-.I config-home
-denote the configuration home directory so determined.
-.\" FIXME XDG_CONFIG_DIRS too now
+If the environment variable
+.B XDG_CONFIG_DIRS
+is defined,
+then the
+.RB ` : '-separated
+entries in its value are appended to the path;
+otherwise, the single entry
+.B /etc/xdg
+is appended.

 .hP 5.
 A `tag' is chosen, as follows.
 If the
 .hP 5.
 A `tag' is chosen, as follows.
 If the


@@ -470,14 +477,20 @@ Let
 .I tag
 denote the tag so chosen.
 .hP 6.
 .I tag
 denote the tag so chosen.
 .hP 6.

-If
-.IB config-home /with-authinfo-kludge/ tag .conf
-exists, then it is read as a configuration file.
+A search is made for a file
+.IB dir /with-authinfo-kludge/ tag .conf
+for each directory
+.I dir
+in the configuration path established in step 4,
+in order.
+If such a file exists exists,
+then it is read as a configuration file.

 (If it can't be read, then a fatal error is reported.)
 .hP 7.
 (If it can't be read, then a fatal error is reported.)
 .hP 7.

-If
-.IB config-home /with-authinfo-kludge/@default.conf
-exists, then it is read as a configuration file.
+A similar search is made for
+.IB dir /with-authinfo-kludge/@default.conf \fR.
+If such a file exists,
+then it is read as a configuration file.

 (If it can't be read, then a fatal error is reported.)
 .hP 8.
 No configuration file could be found,
 (If it can't be read, then a fatal error is reported.)
 .hP 8.
 No configuration file could be found,


@@ -545,13 +558,13 @@ and has no permissions for group or others;
 or if it does not exist but can be created with the above properties;
 then it is used as the runtime directory.
 .hP 4.
 or if it does not exist but can be created with the above properties;
 then it is used as the runtime directory.
 .hP 4.

-The user's home directory is determined, as follows.
-If the environment variable
-.B HOME
-is set, then its value is used.

 Let
 .I home
 Let
 .I home

-be the home directory so determined, if any.
+be the value of the environment variable
+.BR HOME ;
+if this variable is not set, then
+.I home
+is not defined.

 .hP 5.
 A `cache home' directory is determined, as follows.
 If the environment variable
 .hP 5.
 A `cache home' directory is determined, as follows.
 If the environment variable


@@ -582,25 +595,68 @@ with mode 0700 (and modified by the umask).
 (If it exists, but is not in fact a directory,
 then later operations will fail.)
 .PP
 (If it exists, but is not in fact a directory,
 then later operations will fail.)
 .PP

-The runtime directory contains a number of other directories,
-named
-.\" FIXME junk, new, naming
-.\" session dirs now entirely different
-.IR tag . pid \fR.
-Each such directory corresponds to a running
+The runtime directory contains a number of other directories.
+There are a small number of shared directories,
+and zero or more
+.I session
+directories,
+each one corresponding to a running

 (or failed)
 instance of
 (or failed)
 instance of

-.BR with-authinfo-kludge ;
-the
+.BR with-authinfo-kludge .
+.PP
+The shared directories are as follows.
+.TP
+.B new/
+This is the `nursery' directory:
+new session directories are created and populated in here.
+Subdirectories have names of the form
+.BI n. time . pid . rand /
+where
+.I time
+is the time
+(seconds since the POSIX epoch)
+at which the directory was created;

 .I pid
 .I pid

-is its process-id (possibly useful for diagnostic purposes),
-and the
+is the creator's process id; and
+.I rand
+is a random number chosen to minimize conflicts.
+Directories in the nursery older than 300 seconds
+may be deleted.
+The creation protocol is to
+create a directory with an appropriate name;
+create a file within it named
+.BR lock ;
+take out a
+.BR fcntl (2)-style
+exclusive lock on this file;
+and then move the directory to be a direct child
+of the runtime directory.
+.TP
+.B junk/
+Session and nursery directories are deleted in two stages:
+the first stage is to make them be subdirectories of
+.BR junk/ .
+Once there, any process may delete them.
+Note that nursery directories can be junked
+even if they're locked:
+moving them to
+.B junk/
+prevents them from being promoted to proper sessions.
+.PP
+Session directories are named
+.BI s. tag . pid /
+where the

 .I tag
 is the tag summarizing its purpose
 (as determined in step 5 of the procedure
 .I tag
 is the tag summarizing its purpose
 (as determined in step 5 of the procedure

-for finding a configuration file).
+for finding a configuration file), and
+the
+.I pid
+is the creator's process-id,
+which distinguishes this session from others with the same tag.

 .PP
 .PP

-The contents of the instance directory are as follows.
+The contents of a session directory are as follows.

 .TP
 .B client.pid
 The process-id of the client command run by
 .TP
 .B client.pid
 The process-id of the client command run by


@@ -611,17 +667,32 @@ An empty file.
 A
 running
 .B with-authinfo-kludge
 A
 running
 .B with-authinfo-kludge

-process holds a lock on this file.
+process holds a
+.BR fcntl (2)-style
+lock on this file.

 It is used simply to tell other processes that
 the directory is still in use and shouldn't be cleaned up.
 .TP
 It is used simply to tell other processes that
 the directory is still in use and shouldn't be cleaned up.
 .TP

-.B noip/
-A directory containing Unix-domain sockets,
-maintained by the
+.B noip-client/
+A directory containing Unix-domain sockets created by
+.BR with-authinfo-kludge ;
+the

 .B noip
 .B noip

-library.
+library arranges for the client program
+to connect to these Unix-domain sockets
+rather than to the real remote NNTP servers.
+.TP
+.BR noip-ssh. server /
+This directory also contains Unix-domain sockets ;
+they are created by
+.BR ssh (1)
+and
+.B authinfo-kludge
+connects to them,
+both under the influence of
+.BR noip .

 .TP
 .TP

-.B ssh.pid
+.BI ssh- server .pid

 The process-id of the SSH process started to satisfy a
 .B via
 server parameter.
 The process-id of the SSH process started to satisfy a
 .B via
 server parameter.