Add an officially exported libpq function to encrypt passwords, and

modify the previous \password patch to use it instead of depending
on a not-officially-exported function.  Per discussion.

doc/src/sgml/libpq.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.199 2005/11/04 23:14:00 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.200 2005/12/23 01:16:37 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -3565,6 +3565,40 @@ void PQuntrace(PGconn *conn);
 
 </sect1>
 
+<sect1 id="libpq-misc">
+<title>Miscellaneous Functions</title>
+
+<para>
+As always, there are some functions that just don't fit anywhere.
+</para>
+
+<variablelist>
+<varlistentry>
+<term><function>pg_make_encrypted_password</function><indexterm><primary>pg_make_encrypted_password</></></term>
+<listitem>
+<para>
+Prepares the encrypted form of a <productname>PostgreSQL</> password.
+<synopsis>
+char *pg_make_encrypted_password(const char *passwd, const char *user);
+</synopsis>
+<function>pg_make_encrypted_password</> is intended to be used by client
+applications that wish to send commands like
+<literal>ALTER USER joe PASSWORD 'pwd'</>.
+It is good practice not to send the original cleartext password in such a
+command, because it might be exposed in command logs, activity displays,
+and so on.  Instead, use this function to convert the password to encrypted
+form before it is sent.  The arguments are the cleartext password, and the SQL
+name of the user it is for.  The return value is a malloc'd string, or NULL if
+out-of-memory.  The caller may assume the string doesn't contain any weird
+characters that would require escaping.  Use <function>PQfreemem</> to free
+the result when done with it.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
 <sect1 id="libpq-notice-processing">
 <title>Notice Processing</title>