[PATCH v1 0/1] Document strnul(3)

[PATCH v1 0/1] Document strnul(3)

[Alejandro Colomar]

Hi!

gnulib has added strnul(3).  I hope libc implementation eventually pick
up this API.  Let's document it in a manual page.


Have a lovely day!
Alex


Alejandro Colomar (1):
  man/man3/strnul.3: New page

 man/man3/strnul.3 | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 man/man3/strnul.3

Range-diff against v0:
-:  ------------ > 1:  7b2c4b363f65 man/man3/strnul.3: New page

base-commit: 707b47ed0e29dd8ebab93c6c5baa400320160c8b
-- 
2.51.0

[PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strnul.3 | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 man/man3/strnul.3

diff --git a/man/man3/strnul.3 b/man/man3/strnul.3
new file mode 100644
index 000000000000..05995f0407af
--- /dev/null
+++ b/man/man3/strnul.3
@@ -0,0 +1,44 @@
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH strnul 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+strnul \- string null-terminator
+.SH LIBRARY
+gnulib \- The GNU Portability Library
+.SH SYNOPSIS
+.nf
+.B #include <string.h>
+.P
+.BI char\~*streq(const\~char\~* s );
+.fi
+.SH DESCRIPTION
+.BR strnul ()
+returns a pointer to the terminating null byte in the string
+.IR s .
+.SH RETURN VALUE
+.IR s+strlen(s) .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR strnul ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+GNU.
+.SH HISTORY
+gnulib 202607.
+.SH SEE ALSO
+.BR strlen (3),
+.BR strchr (3),
+.BR string (3)
-- 
2.51.0

Re: [PATCH v1 0/1] Document strnul(3)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1937 bytes --]

On 2026-02-21T16:02:49+0100, Alejandro Colomar wrote:
> Hi!
> 
> gnulib has added strnul(3).  I hope libc implementation eventually pick
> up this API.  Let's document it in a manual page.

Here's how the page looks like:

$ MANWIDTH=72 diffman-git HEAD
fatal: path 'man/man3/strnul.3' exists on disk, but not in 'HEAD^'
--- HEAD^:man/man3/strnul.3
+++ HEAD:man/man3/strnul.3
@@ -0,0 +1,39 @@
+strnul(3)               Library Functions Manual              strnul(3)
+
+NAME
+     strnul - string null‐terminator
+
+LIBRARY
+     gnulib - The GNU Portability Library
+
+SYNOPSIS
+     #include <string.h>
+
+     char *streq(const char *s);
+
+DESCRIPTION
+     strnul() returns a pointer to the terminating null byte in the
+     string s.
+
+RETURN VALUE
+     s+strlen(s).
+
+ATTRIBUTES
+     For an explanation of the terms used in this section, see attrib‐
+     utes(7).
+     ┌──────────────────────────────────────┬───────────────┬─────────┐
+     │ Interface                            │ Attribute     │ Value   │
+     ├──────────────────────────────────────┼───────────────┼─────────┤
+     │ strnul()                             │ Thread safety │ MT‐Safe │
+     └──────────────────────────────────────┴───────────────┴─────────┘
+
+STANDARDS
+     GNU.
+
+HISTORY
+     gnulib 202607.
+
+SEE ALSO
+     strlen(3), strchr(3), string(3)
+
+Linux man‐pages (unreleased)     (date)                       strnul(3)

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 0/1] Document strnul(3)

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 2185 bytes --]

On 2026-02-21T16:04:24+0100, Alejandro Colomar wrote:
> On 2026-02-21T16:02:49+0100, Alejandro Colomar wrote:
> > Hi!
> > 
> > gnulib has added strnul(3).  I hope libc implementation eventually pick
> > up this API.  Let's document it in a manual page.
> 
> Here's how the page looks like:
> 
> $ MANWIDTH=72 diffman-git HEAD
> fatal: path 'man/man3/strnul.3' exists on disk, but not in 'HEAD^'
> --- HEAD^:man/man3/strnul.3
> +++ HEAD:man/man3/strnul.3
> @@ -0,0 +1,39 @@
> +strnul(3)               Library Functions Manual              strnul(3)
> +
> +NAME
> +     strnul - string null‐terminator
> +
> +LIBRARY
> +     gnulib - The GNU Portability Library
> +
> +SYNOPSIS
> +     #include <string.h>
> +
> +     char *streq(const char *s);

Oops; s/streq/strnul/.  Fixed.

> +
> +DESCRIPTION
> +     strnul() returns a pointer to the terminating null byte in the
> +     string s.
> +
> +RETURN VALUE
> +     s+strlen(s).
> +
> +ATTRIBUTES
> +     For an explanation of the terms used in this section, see attrib‐
> +     utes(7).
> +     ┌──────────────────────────────────────┬───────────────┬─────────┐
> +     │ Interface                            │ Attribute     │ Value   │
> +     ├──────────────────────────────────────┼───────────────┼─────────┤
> +     │ strnul()                             │ Thread safety │ MT‐Safe │
> +     └──────────────────────────────────────┴───────────────┴─────────┘
> +
> +STANDARDS
> +     GNU.
> +
> +HISTORY
> +     gnulib 202607.
> +
> +SEE ALSO
> +     strlen(3), strchr(3), string(3)
> +
> +Linux man‐pages (unreleased)     (date)                       strnul(3)
> 
> -- 
> <https://www.alejandro-colomar.es>



-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 741 bytes --]

Hi Alex,

At 2026-02-21T16:02:52+0100, Alejandro Colomar wrote:
> +.SH RETURN VALUE
> +.IR s+strlen(s) .

Too cute, in my opinion.  Use English.  :)

C novices struggle with pointer arithmetic as it is.  (Even non-novices
can, when working with exotic architectures with multiple memory models
like the x86's historical--and thankfully near-forgotten--`near` and
`far`.  Pointer arithmetic in the former can, if my vague recollection
is correct, do surprising stuff like wrap around a 64 KiB memory segment
without causing a fault.)

I assume that the string library reforms you're pursuing are intended in
part to be adopted by newcomers to C.  Avoiding cleverness when
presenting new interfaces can make them less scary.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1583 bytes --]

Hi Branden,

On 2026-02-21T11:41:42-0600, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2026-02-21T16:02:52+0100, Alejandro Colomar wrote:
> > +.SH RETURN VALUE
> > +.IR s+strlen(s) .
> 
> Too cute, in my opinion.  Use English.  :)

The thing is, at first I thought, am I going to repeat the same exact
words as in the DESCRIPTION?

DESCRIPTION
     strnul() returns a pointer to the terminating null byte in the
     string s.

RETURN VALUE
     strnul() returns a pointer to the terminating null byte in the
     string s.

I could remove the DESCRIPTION altogether...  What would you do?

> 
> C novices struggle with pointer arithmetic as it is.  (Even non-novices
> can, when working with exotic architectures with multiple memory models
> like the x86's historical--and thankfully near-forgotten--`near` and
> `far`.  Pointer arithmetic in the former can, if my vague recollection
> is correct, do surprising stuff like wrap around a 64 KiB memory segment
> without causing a fault.)

I might as well write it as &s[strlen(s)] if pointer arithmetic is the
confusing part.  :)

> 
> I assume that the string library reforms you're pursuing are intended in
> part to be adopted by newcomers to C.

I intend old programmers to use it too.  I guess you're expecting
a patch to groff once this is in a branch of gnulib you're using.  ;)

>  Avoiding cleverness when
> presenting new interfaces can make them less scary.

Agree.


Have a lovely night!
Alex

> 
> Regards,
> Branden



-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Simon Josefsson]

[-- Attachment #1: Type: text/plain, Size: 1064 bytes --]

Alejandro Colomar <alx@kernel.org> writes:

> Hi Branden,
>
> On 2026-02-21T11:41:42-0600, G. Branden Robinson wrote:
>> Hi Alex,
>> 
>> At 2026-02-21T16:02:52+0100, Alejandro Colomar wrote:
>> > +.SH RETURN VALUE
>> > +.IR s+strlen(s) .
>> 
>> Too cute, in my opinion.  Use English.  :)
>
> The thing is, at first I thought, am I going to repeat the same exact
> words as in the DESCRIPTION?
>
> DESCRIPTION
>      strnul() returns a pointer to the terminating null byte in the
>      string s.
>
> RETURN VALUE
>      strnul() returns a pointer to the terminating null byte in the
>      string s.
>
> I could remove the DESCRIPTION altogether...  What would you do?

Use the same style as for strlen:

DESCRIPTION
       The  strlen() function calculates the length of the string pointed to by
       s, excluding the terminating null byte ('\0').

RETURN VALUE
       The strlen() function returns the number of bytes in the string  pointed
       to by s.

One says what it does, the other says what it returns.

/Simon

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1251 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1826 bytes --]

Hi Alex,

At 2026-02-21T20:56:05+0100, Alejandro Colomar wrote:
> On 2026-02-21T11:41:42-0600, G. Branden Robinson wrote:
> > At 2026-02-21T16:02:52+0100, Alejandro Colomar wrote:
> > > +.SH RETURN VALUE
> > > +.IR s+strlen(s) .
> > 
> > Too cute, in my opinion.  Use English.  :)
> 
> The thing is, at first I thought, am I going to repeat the same exact
> words as in the DESCRIPTION?
> 
> DESCRIPTION
>      strnul() returns a pointer to the terminating null byte in the
>      string s.
> 
> RETURN VALUE
>      strnul() returns a pointer to the terminating null byte in the
>      string s.
> 
> I could remove the DESCRIPTION altogether...  What would you do?

Fair.  In this case, I'd probably just say...

See \[lq]DESCRIPTION\[rq] above.

I don't have much sympathy for hackers who complain that the "RETURN
VALUE" section didn't tell them what they needed to know when the
one-sentence "DESCRIPTION" _that they didn't read_ would have.

At a certain point, documentation writers have no defense from people
who refuse to read.

> I might as well write it as &s[strlen(s)] if pointer arithmetic is the
> confusing part.  :)

Hah!

> > I assume that the string library reforms you're pursuing are
> > intended in part to be adopted by newcomers to C.
> 
> I intend old programmers to use it too.

Goooooood luck.  As we've seen, to take gets(3) away from some people
has required killing it off from the standard C library itself.

Some old programmers get really good.  Some just get old.

> I guess you're expecting a patch to groff once this is in a branch of
> gnulib you're using.  ;)

No, not expecting.  :)

Replacing our bespoke `strsave()` with `strdup()` seems like a higher
priority to me.

https://savannah.gnu.org/bugs/?66518

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1446 bytes --]

Hi Simon,

On 2026-02-21T21:02:49+0100, Simon Josefsson wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hi Branden,
> >
> > On 2026-02-21T11:41:42-0600, G. Branden Robinson wrote:
> >> Hi Alex,
> >> 
> >> At 2026-02-21T16:02:52+0100, Alejandro Colomar wrote:
> >> > +.SH RETURN VALUE
> >> > +.IR s+strlen(s) .
> >> 
> >> Too cute, in my opinion.  Use English.  :)
> >
> > The thing is, at first I thought, am I going to repeat the same exact
> > words as in the DESCRIPTION?
> >
> > DESCRIPTION
> >      strnul() returns a pointer to the terminating null byte in the
> >      string s.
> >
> > RETURN VALUE
> >      strnul() returns a pointer to the terminating null byte in the
> >      string s.
> >
> > I could remove the DESCRIPTION altogether...  What would you do?
> 
> Use the same style as for strlen:
> 
> DESCRIPTION
>        The  strlen() function calculates the length of the string pointed to by
>        s, excluding the terminating null byte ('\0').

Hmmm, maybe I could do this.

DESCRIPTION
	strnul() calculates the position of the terminating null byte
	in the string pointed to by s.

> 
> RETURN VALUE
>        The strlen() function returns the number of bytes in the string  pointed
>        to by s.
> 
> One says what it does, the other says what it returns.

Thanks!


Have a lovely night!
Alex

> 
> /Simon



-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v2 0/1] Document strnul(3)

[Alejandro Colomar]

Hi,

gnulib has added strnul(3).  I hope libc implementations eventually pick
up this API.  Let's document it in a manual page.

This v2 changes a typo, and the wording of DESCRIPTION and RETURN VALUE.


Have a lovely night!
Alex

Alejandro Colomar (1):
  man/man3/strnul.3: New page

 man/man3/strnul.3 | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 man/man3/strnul.3

Range-diff against v1:
1:  7b2c4b363f65 ! 1:  2b86d10abfc3 man/man3/strnul.3: New page
    @@ man/man3/strnul.3 (new)
     +.nf
     +.B #include <string.h>
     +.P
    -+.BI char\~*streq(const\~char\~* s );
    ++.BI char\~*strnul(const\~char\~* s );
     +.fi
     +.SH DESCRIPTION
     +.BR strnul ()
    -+returns a pointer to the terminating null byte in the string
    ++calculates the position of the terminating null byte (\[aq]\[rs]0\[aq])
    ++in the string pointed to by
     +.IR s .
     +.SH RETURN VALUE
    -+.IR s+strlen(s) .
    ++.BR strnul ()
    ++returns a pointer to the terminating null byte
    ++in the string pointed to by
    ++.IR s .
     +.SH ATTRIBUTES
     +For an explanation of the terms used in this section, see
     +.BR attributes (7).
-- 
2.51.0

[PATCH v2 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man/man3/strnul.3 | 48 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 man/man3/strnul.3

diff --git a/man/man3/strnul.3 b/man/man3/strnul.3
new file mode 100644
index 000000000000..0554edb401e9
--- /dev/null
+++ b/man/man3/strnul.3
@@ -0,0 +1,48 @@
+'\" t
+.\" Copyright, the authors of the Linux man-pages project
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH strnul 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+strnul \- string null-terminator
+.SH LIBRARY
+gnulib \- The GNU Portability Library
+.SH SYNOPSIS
+.nf
+.B #include <string.h>
+.P
+.BI char\~*strnul(const\~char\~* s );
+.fi
+.SH DESCRIPTION
+.BR strnul ()
+calculates the position of the terminating null byte (\[aq]\[rs]0\[aq])
+in the string pointed to by
+.IR s .
+.SH RETURN VALUE
+.BR strnul ()
+returns a pointer to the terminating null byte
+in the string pointed to by
+.IR s .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR strnul ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+GNU.
+.SH HISTORY
+gnulib 202607.
+.SH SEE ALSO
+.BR strlen (3),
+.BR strchr (3),
+.BR string (3)
-- 
2.51.0

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 880 bytes --]

Hi Branden,

On 2026-02-21T14:05:09-0600, G. Branden Robinson wrote:
> > > I assume that the string library reforms you're pursuing are
> > > intended in part to be adopted by newcomers to C.
> > 
> > I intend old programmers to use it too.
> 
> Goooooood luck.  As we've seen, to take gets(3) away from some people
> has required killing it off from the standard C library itself.
> 
> Some old programmers get really good.  Some just get old.
> 
> > I guess you're expecting a patch to groff once this is in a branch of
> > gnulib you're using.  ;)
> 
> No, not expecting.  :)

Well, now you know.  :)

> 
> Replacing our bespoke `strsave()` with `strdup()` seems like a higher
> priority to me.

Will you, or should I?

> 
> https://savannah.gnu.org/bugs/?66518
> 
> Regards,
> Branden

Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Paul Eggert]

On 2026-02-21 07:02, Alejandro Colomar wrote:
> +.BI char\~*streq(const\~char\~* s );

I see you fixed the misspelling of "strnul". However, there's a more 
important issue here: that's not the type of Gnulib strnul. Gnulib 
strnul is a qualifier-generic macro, and (unlike C23 strchr) there is no 
underlying function named "strnul". This needs to be documented clearly.

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 623 bytes --]

Hi Paul,

On 2026-02-21T17:48:30-0800, Paul Eggert wrote:
> On 2026-02-21 07:02, Alejandro Colomar wrote:
> > +.BI char\~*streq(const\~char\~* s );
> 
> I see you fixed the misspelling of "strnul". However, there's a more
> important issue here: that's not the type of Gnulib strnul. Gnulib strnul is
> a qualifier-generic macro, and (unlike C23 strchr) there is no underlying
> function named "strnul". This needs to be documented clearly.

Yup, if there are no plans to have a function, I'll document the
const-generic macro.  Thanks!


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1579 bytes --]

On 2026-02-22T12:21:34+0100, Alejandro Colomar wrote:
> Hi Paul,
> 
> On 2026-02-21T17:48:30-0800, Paul Eggert wrote:
> > On 2026-02-21 07:02, Alejandro Colomar wrote:
> > > +.BI char\~*streq(const\~char\~* s );
> > 
> > I see you fixed the misspelling of "strnul". However, there's a more
> > important issue here: that's not the type of Gnulib strnul. Gnulib strnul is
> > a qualifier-generic macro, and (unlike C23 strchr) there is no underlying
> > function named "strnul". This needs to be documented clearly.
> 
> Yup, if there are no plans to have a function, I'll document the
> const-generic macro.  Thanks!

I've pushed the following patch:

	commit e29efc9b6bdbb644a44c2b9e3d6bfbf06ce4ec62 (HEAD -> contrib)
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-02-22 14:34:36 +0100

	    man/man3/strnul.3: SYNOPSIS: Use QChar
	    
	    Reported-by: Paul Eggert <eggert@cs.ucla.edu>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/strnul.3 b/man/man3/strnul.3
	index 714b4d191cae..f84e13fdc82b 100644
	--- a/man/man3/strnul.3
	+++ b/man/man3/strnul.3
	@@ -12,7 +12,7 @@ .SH SYNOPSIS
	 .nf
	 .B #include <string.h>
	 .P
	-.BI char\~*strnul(const\~char\~* s );
	+.BI QChar\~*strnul(QChar\~* s );
	 .fi
	 .SH DESCRIPTION
	 .BR strnul ()

I might document QChar is a separate page, eventually.  I'm still
thinking about whether to do it or not, and what to document in such
a page.  Patches are welcome, if anyone has some ideas.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Bruno Haible]

Alejandro Colomar wrote:
> 	 .B #include <string.h>
> 	 .P
> 	-.BI char\~*strnul(const\~char\~* s );
> 	+.BI QChar\~*strnul(QChar\~* s );
> 	 .fi

Ouch. This is not understandable. Why should a user learn about what 'QChar'
is??

It's basically like a C++ template with 2 instantiations. Just list them
explicitly; this will be much clearer.

It's common that the SYNOPSIS section has several lines. For example,
man1/locale.1 has 4 separate lines.

Bruno

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 662 bytes --]

Hi Bruno,

On 2026-02-22T15:10:03+0100, Bruno Haible wrote:
> Alejandro Colomar wrote:
> > 	 .B #include <string.h>
> > 	 .P
> > 	-.BI char\~*strnul(const\~char\~* s );
> > 	+.BI QChar\~*strnul(QChar\~* s );
> > 	 .fi
> 
> Ouch. This is not understandable. Why should a user learn about what 'QChar'
> is??
> 
> It's basically like a C++ template with 2 instantiations. Just list them
> explicitly; this will be much clearer.
> 
> It's common that the SYNOPSIS section has several lines. For example,
> man1/locale.1 has 4 separate lines.

Hmmm; sounds reasonable.  I'll do that.


Cheers,
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v1 1/1] man/man3/strnul.3: New page

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1612 bytes --]

On 2026-02-22T15:19:35+0100, Alejandro Colomar wrote:
> Hi Bruno,
> 
> On 2026-02-22T15:10:03+0100, Bruno Haible wrote:
> > Alejandro Colomar wrote:
> > > 	 .B #include <string.h>
> > > 	 .P
> > > 	-.BI char\~*strnul(const\~char\~* s );
> > > 	+.BI QChar\~*strnul(QChar\~* s );
> > > 	 .fi
> > 
> > Ouch. This is not understandable. Why should a user learn about what 'QChar'
> > is??
> > 
> > It's basically like a C++ template with 2 instantiations. Just list them
> > explicitly; this will be much clearer.
> > 
> > It's common that the SYNOPSIS section has several lines. For example,
> > man1/locale.1 has 4 separate lines.
> 
> Hmmm; sounds reasonable.  I'll do that.

I've amended the commit to do that:

	commit 0dffb0e8afdd3b025a6001a342b2f49f179a8914 (HEAD -> contrib)
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-02-22 14:34:36 +0100

	    man/man3/strnul.3: SYNOPSIS: Document that it's a const-generic API
	    
	    Document it as two overloads (C++-style).
	    
	    Reported-by: Paul Eggert <eggert@cs.ucla.edu>
	    Suggested-by: Bruno Haible <bruno@clisp.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man3/strnul.3 b/man/man3/strnul.3
	index 714b4d191cae..a92ced866a02 100644
	--- a/man/man3/strnul.3
	+++ b/man/man3/strnul.3
	@@ -12,7 +12,8 @@ .SH SYNOPSIS
	 .nf
	 .B #include <string.h>
	 .P
	-.BI char\~*strnul(const\~char\~* s );
	+.BI char\~*strnul(char\~* s );
	+.BI const\~char\~*strnul(const\~char\~* s );
	 .fi
	 .SH DESCRIPTION
	 .BR strnul ()

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]