Document the existence of the socket lock file under unix_socket_directory,

which is perhaps not a terribly good spot for it but there doesn't seem to be
a better place.  Also add a source-code comment pointing out a couple reasons
for having a separate lock file.  Per suggestion from Greg Smith.

doc/src/sgml/config.sgml

-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.308 2010/08/24 13:32:25 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.309 2010/08/26 22:00:19 tgl Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -426,6 +426,20 @@ SET ENABLE_SEQSCAN TO OFF;
         <filename>/tmp</filename>, but can be changed at build time.
         This parameter can only be set at server start.
        </para>
+
+       <para>
+        In addition to the socket file itself, which is named
+        <literal>.s.PGSQL.<replaceable>nnnn</></literal> where
+        <replaceable>nnnn</> is the server's port number, an ordinary file
+        named <literal>.s.PGSQL.<replaceable>nnnn</>.lock</literal> will be
+        created in the <varname>unix_socket_directory</> directory.  Neither
+        file should ever be removed manually.
+       </para>
+
+       <para>
+        This parameter is irrelevant on Windows, which does not have
+        Unix-domain sockets.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -445,6 +459,11 @@ SET ENABLE_SEQSCAN TO OFF;
         group of the server user.  This parameter can only be set at
         server start.
        </para>
+
+       <para>
+        This parameter is irrelevant on Windows, which does not have
+        Unix-domain sockets.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -482,6 +501,11 @@ SET ENABLE_SEQSCAN TO OFF;
        <para>
         This parameter can only be set at server start.
        </para>
+
+       <para>
+        This parameter is irrelevant on Windows, which does not have
+        Unix-domain sockets.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -523,18 +547,19 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-        Specifies the number of seconds before sending a keepalive packet on an otherwise idle
-        connection.  A value of 0 uses the system default.  This parameter is supported
-        only on systems that support the <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</>
-        symbols, and on Windows; on other systems, it must be zero. This parameter is
-        ignored for connections made via a Unix-domain socket.
+        Specifies the number of seconds before sending a keepalive packet on
+        an otherwise idle connection.  A value of 0 uses the system default.
+        This parameter is supported only on systems that support the
+        <symbol>TCP_KEEPIDLE</> or <symbol>TCP_KEEPALIVE</> symbols, and on
+        Windows; on other systems, it must be zero. This parameter is ignored
+        for connections made via a Unix-domain socket.
+       </para>
        <note>
         <para>
          On Windows, a value of 0 will set this parameter to 2 hours,
-           since Windows does not provide a way to read the default value.
+         since Windows does not provide a way to read the system default value.
         </para>
        </note>
-       </para>
       </listitem>
      </varlistentry>
 
@@ -545,18 +570,19 @@ SET ENABLE_SEQSCAN TO OFF;
       </indexterm>
       <listitem>
        <para>
-        Specifies the number of seconds between sending keepalives on an otherwise idle
-        connection.  A value of 0 uses the system default.  This parameter is supported
-        only on systems that support the <symbol>TCP_KEEPINTVL</>
-        symbol, and on Windows; on other systems, it must be zero. This parameter is
-        ignored for connections made via a Unix-domain socket.
+        Specifies the number of seconds between sending keepalives on an
+        otherwise idle connection.  A value of 0 uses the system default.
+        This parameter is supported only on systems that support the
+        <symbol>TCP_KEEPINTVL</> symbol, and on Windows; on other systems, it
+        must be zero. This parameter is ignored for connections made via a
+        Unix-domain socket.
+       </para>
        <note>
         <para>
          On Windows, a value of 0 will set this parameter to 1 second,
-           since Windows does not provide a way to read the default value.
+         since Windows does not provide a way to read the system default value.
         </para>
        </note>
-       </para>
       </listitem>
      </varlistentry>
 
@@ -568,16 +594,16 @@ SET ENABLE_SEQSCAN TO OFF;
       <listitem>
        <para>
         Specifies the number of keepalive packets to send on an otherwise idle
-        connection.  A value of 0 uses the system default.  This parameter is supported
-        only on systems that support the <symbol>TCP_KEEPCNT</>
-        symbol; on other systems, it must be zero. This parameter is
-        ignored for connections made via a Unix-domain socket.
+        connection.  A value of 0 uses the system default.  This parameter is
+        supported only on systems that support the <symbol>TCP_KEEPCNT</>
+        symbol; on other systems, it must be zero. This parameter is ignored
+        for connections made via a Unix-domain socket.
+       </para>
        <note>
         <para>
          This parameter is not supported on Windows, and must be zero.
         </para>
        </note>
-       </para>
       </listitem>
      </varlistentry>
 

src/backend/libpq/pqcomm.c

@@ -30,7 +30,7 @@
  * Portions Copyright (c) 1996-2010, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- *	$PostgreSQL: pgsql/src/backend/libpq/pqcomm.c,v 1.212 2010/07/08 16:19:50 mha Exp $
+ *	$PostgreSQL: pgsql/src/backend/libpq/pqcomm.c,v 1.213 2010/08/26 22:00:19 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -484,6 +484,11 @@ Lock_AF_UNIX(unsigned short portNumber, char *unixSocketName)
 
 	/*
 	 * Grab an interlock file associated with the socket file.
+	 *
+	 * Note: there are two reasons for using a socket lock file, rather than
+	 * trying to interlock directly on the socket itself.  First, it's a lot
+	 * more portable, and second, it lets us remove any pre-existing socket
+	 * file without race conditions.
 	 */
 	CreateSocketLockFile(sock_path, true);