From: Peter Eisentraut <peter_e@gmx.net>
Date: Wed, 17 Apr 2013 01:42:10 +0000 (-0400)
Subject: doc: Update PQgetssl() documentation
X-Git-Tag: REL9_3_BETA1~90
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=b9bdaf3964a1fbd32e6140eb180dfa82ff1d8f23;p=postgresql

doc: Update PQgetssl() documentation

The return type of PQgetssl() was changed from SSL* to void* a long time
ago, but the documentation was not updated.
---

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 3b6ada08f7..deef3be965 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1864,7 +1864,7 @@ int PQconnectionUsedPassword(const PGconn *conn);
        if SSL is not in use.
 
 <synopsis>
-SSL *PQgetssl(const PGconn *conn);
+void *PQgetssl(const PGconn *conn);
 </synopsis>
       </para>
 
@@ -1875,10 +1875,29 @@ SSL *PQgetssl(const PGconn *conn);
       </para>
 
       <para>
-       You must define <symbol>USE_SSL</symbol> in order to get the
-       correct prototype for this function. Doing so will also
-       automatically include <filename>ssl.h</filename> from
-       <productname>OpenSSL</productname>.
+       The actual return value is of type <type>SSL *</type>,
+       where <type>SSL</type> is a type defined by
+       the <productname>OpenSSL</productname> library, but it is not declared
+       this way to avoid requiring the <productname>OpenSSL</productname>
+       header files.  To use this function, code along the following lines
+       could be used:
+<programlisting><![CDATA[
+#include <libpq-fe.h>
+#include <openssl/ssl.h>
+
+...
+
+    SSL *ssl;
+
+    dbconn = PQconnectdb(...);
+    ...
+
+    ssl = PQgetssl(dbconn);
+    if (ssl)
+    {
+        /* use OpenSSL functions to access ssl */
+    }
+]]></programlisting>
       </para>
      </listitem>
     </varlistentry>