public inbox for [email protected]
help / color / mirror / Atom feedImprove PQauthDataHook_type docs
2+ messages / 2 participants
[nested] [flat]
* Improve PQauthDataHook_type docs
@ 2026-04-19 15:54 Daniele Varrazzo <[email protected]>
2026-05-11 23:07 ` Re: Improve PQauthDataHook_type docs Bruce Momjian <[email protected]>
0 siblings, 1 reply; 2+ messages in thread
From: Daniele Varrazzo @ 2026-04-19 15:54 UTC (permalink / raw)
To: [email protected]
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
Attachments:
[text/x-patch] 0001-doc-improve-PQauthDataHook_type-definition.patch (1.1K, 2-0001-doc-improve-PQauthDataHook_type-definition.patch)
download | inline diff:
From 1925c2f47a268aa6a443b6f801c6ea7c1535ceed Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <[email protected]>
Date: Sun, 19 Apr 2026 17:41:13 +0200
Subject: [PATCH] doc: improve PQauthDataHook_type definition
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
--
2.34.1
^ permalink raw reply [nested|flat] 2+ messages in thread
* Re: Improve PQauthDataHook_type docs
2026-04-19 15:54 Improve PQauthDataHook_type docs Daniele Varrazzo <[email protected]>
@ 2026-05-11 23:07 ` Bruce Momjian <[email protected]>
0 siblings, 0 replies; 2+ messages in thread
From: Bruce Momjian @ 2026-05-11 23:07 UTC (permalink / raw)
To: Daniele Varrazzo <[email protected]>; +Cc: [email protected]
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 <[email protected]> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.
^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~2026-05-11 23:07 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-04-19 15:54 Improve PQauthDataHook_type docs Daniele Varrazzo <[email protected]>
2026-05-11 23:07 ` Bruce Momjian <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox