BUG #17249: Bug in .pgpass search and/or documentation thereof, Ubuntu 13.4-4

The following bug has been logged on the website:

Bug reference:      17249
Logged by:          David Hillman
Email address:      david@kapitaltrading.com
PostgreSQL version: 13.4
Operating system:   Kubuntu 20.04.3 LTS
Description:

There's a bug in either the .pgpass search, or the documentation thereof, in
13.4-4.

 The documentation ( https://www.postgresql.org/docs/13/libpq-pgpass.html )
says:

"The host name field is matched to the host connection parameter if that is
specified, otherwise to the hostaddr parameter if that is specified; if
neither are given then the host name localhost is searched for. The host
name localhost is also searched for when the connection is a Unix-domain
socket connection and the host parameter matches libpq's default socket
directory path.

If that were the situation, the following two cases would produce the same
result.  As you can see, they do not.  In the first case below, "neither
(host connection parameter) are given" which should result in .pgpass being
searched for "localhost" per the above statements.  It does not.


root@dbserver:~# cat ~/.pgpass
localhost:*:*:valid_user:valid_password

root@dbserver:~# psql -d postgres -U valid_user
psql: error: connection to server on socket
"/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  Peer authentication
failed for user "valid_user"

root@dbserver:~# psql -d postgres -U valid_user -h localhost
psql (13.4 (Ubuntu 13.4-4.pgdg20.04+1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits:
256, compression: off)
Type "help" for help.

postgres=# \q