From 94a8c19eed6cdaffad8939a41ed89e3c6afa7c94 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Fri, 1 Nov 2024 13:32:21 -0400
Subject: doc:  explain how the home directory is found on Unix-like syst.

Done for libpq, postgres-fdw, and psql.

Reported-by: marc@msys.ch

Discussion: https://postgr.es/m/CAKFQuwZ-T-zsVM7gApS9-XU9vGxC7Oa-UyRQPVcJFagNU=AjOw@mail.gmail.com

Backpatch-through: master
---
 doc/src/sgml/libpq.sgml        | 4 +++-
 doc/src/sgml/postgres-fdw.sgml | 4 +++-
 doc/src/sgml/ref/psql-ref.sgml | 3 ++-
 3 files changed, 8 insertions(+), 3 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index afc9346757a..bfefb1289e8 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -9256,7 +9256,9 @@ myEventProc(PGEventId evtId, void *evtInfo, void *passThrough)
    The file <filename>.pgpass</filename> in a user's home directory can
    contain passwords to
    be used if the connection requires a password (and no password has been
-   specified otherwise). On Microsoft Windows the file is named
+   specified otherwise). On Unix systems, the directory can be specified by
+   the <envar>HOME</envar> environment variable, or if undefined, the home
+   directory of the effective user.  On Microsoft Windows the file is named
    <filename>%APPDATA%\postgresql\pgpass.conf</filename> (where
    <filename>%APPDATA%</filename> refers to the Application Data subdirectory in
    the user's profile).
diff --git a/doc/src/sgml/postgres-fdw.sgml b/doc/src/sgml/postgres-fdw.sgml
index 627bb5ab5cc..188e8f0b4d0 100644
--- a/doc/src/sgml/postgres-fdw.sgml
+++ b/doc/src/sgml/postgres-fdw.sgml
@@ -194,7 +194,9 @@ OPTIONS (ADD password_required 'false');
     user can potentially use any client certificates,
     <filename>.pgpass</filename>,
     <filename>.pg_service.conf</filename> etc. in the unix home directory of the
-    system user the postgres server runs as. They can also use any trust
+    system user the postgres server runs as.   (For details on how home
+    directories are found, see <xref linkend="libpq-pgpass"/>.)  They can
+    also use any trust
     relationship granted by authentication modes like <literal>peer</literal>
     or <literal>ident</literal> authentication.
    </para>
diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml
index b825ca96a23..e42073ed748 100644
--- a/doc/src/sgml/ref/psql-ref.sgml
+++ b/doc/src/sgml/ref/psql-ref.sgml
@@ -1048,7 +1048,8 @@ INSERT INTO tbls1 VALUES ($1, $2) \parse stmt1
         <para>
          Changes the current working directory to
          <replaceable>directory</replaceable>. Without argument, changes
-         to the current user's home directory.
+         to the current user's home directory.  For details on how home
+         directories are found, see <xref linkend="libpq-pgpass"/>.
         </para>
 
         <tip>
-- 
cgit v1.2.3