Thread

1. Improve PQauthDataHook_type docs

   Daniele Varrazzo <daniele.varrazzo@gmail.com> — 2026-04-19T15:54:02Z

   Hello,
   
   In https://www.postgresql.org/docs/18/libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS
   it is not entirely clear that `hook_fn` is the definition of the
   `PQauthDataHook_type` used in the functions signature, because the
   name is not used elsewhere. The function signatures refer to the
   typedef but the typedef is not shown.
   
   Using https://www.postgresql.org/docs/18/libpq-notice-processing.html#LIBPQ-NOTICE-PROCESSING
   as a guideline I suggest to show the typedef of the callback rather
   than the `hook_fn` example, so that the `PQauthDataHook_type` name can
   be searched for.
   
   Please check the patch attached.
   
   Cheers
   
   -- Daniele
   

2. Re: Improve PQauthDataHook_type docs

   Bruce Momjian <bruce@momjian.us> — 2026-05-11T23:07:57Z

   On Sun, Apr 19, 2026 at 04:54:02PM +0100, Daniele Varrazzo wrote:
   > Hello,
   > 
   > In https://www.postgresql.org/docs/18/libpq-oauth.html#LIBPQ-OAUTH-AUTHDATA-HOOKS
   > it is not entirely clear that `hook_fn` is the definition of the
   > `PQauthDataHook_type` used in the functions signature, because the
   > name is not used elsewhere. The function signatures refer to the
   > typedef but the typedef is not shown.
   > 
   > Using https://www.postgresql.org/docs/18/libpq-notice-processing.html#LIBPQ-NOTICE-PROCESSING
   > as a guideline I suggest to show the typedef of the callback rather
   > than the `hook_fn` example, so that the `PQauthDataHook_type` name can
   > be searched for.
   > 
   > Please check the patch attached.
   
   > Use the typedef name to make it easier to correlate to the functions
   > using this type definition.
   > ---
   >  doc/src/sgml/libpq.sgml | 2 +-
   >  1 file changed, 1 insertion(+), 1 deletion(-)
   > 
   > diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
   > index e50f0cbd8c7..f646244840d 100644
   > --- a/doc/src/sgml/libpq.sgml
   > +++ b/doc/src/sgml/libpq.sgml
   > @@ -10280,7 +10280,7 @@ void PQsetAuthDataHook(PQauthDataHook_type hook);
   >          default handler will be reinstalled. Otherwise, the application passes
   >          a pointer to a callback function with the signature:
   >  <programlisting>
   > -int hook_fn(PGauthData type, PGconn *conn, void *data);
   > +typedef int (*PQauthDataHook_type) (PGauthData type, PGconn *conn, void *data);
   >  </programlisting>
   >          which <application>libpq</application> will call when an action is
   >          required of the application. <replaceable>type</replaceable> describes
   
   I looked at this, and I think using a typedef makes it too complicated. 
   The idea is that "hook" should be a pointer to a function that has this
   definition.  Maybe we should change it to:
   
   	int hook(PGauthData type, PGconn *conn, void *data);
   	    ----
   
   to match the line above:
   
   	void PQsetAuthDataHook(PQauthDataHook_type hook);
   
   -- 
     Bruce Momjian  <bruce@momjian.us>        https://momjian.us
     EDB                                      https://enterprisedb.com
   
     Do not let urgent matters crowd out time for investment in the future.