Document strnul(3)
Alejandro Colomar
maintainercover Document strnul(3)
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
Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH 1/1 man/man3/strnul.3: New page
--- man/man3/strnul.3 | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 man/man3/strnul.3
man/man3/strnul.3 new file +44 -0
@@ -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)
Signature · 1 line
2.51.0
Re: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Alex,
Quoted 2 lines · Alejandro Colomar
+.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
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Branden,
Quoted 7 lines · G. Branden Robinson
Hi Alex,
Quoted 2 lines · Alejandro Colomar
+.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?
Quoted 7 lines
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--
nearandfar. 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. :)
Quoted 3 lines
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. ;)
Quoted 2 lines
Avoiding cleverness when
presenting new interfaces can make them less scary.
Agree.
Have a lovely night!
Alex
Quoted 3 lines
Regards,
Branden
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Alex,
Quoted 14 lines · Alejandro Colomar
Quoted 5 lines · G. Branden Robinson
Quoted 2 lines · Alejandro Colomar
+.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.
Quoted 5 lines
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.
Quoted 2 lines
I might as well write it as &s[strlen(s)] if pointer arithmetic is the confusing part. :)
Hah!
Quoted 4 lines
Quoted 2 lines
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.
Quoted 2 lines
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
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Branden,
Quoted 8 lines · G. Branden Robinson
Quoted 4 lines
Quoted 2 lines
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.
Quoted 6 lines
Some old programmers get really good. Some just get old.
Quoted 2 lines
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. :)
Quoted 3 lines
Replacing our bespoke
strsave()withstrdup()seems like a higher priority to me.
Will you, or should I?
Quoted 5 lines
https://savannah.gnu.org/bugs/?66518
Regards,
Branden
Cheers,
Alex
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v1 1/1] man/man3/strnul.3: New page
In reply to Alejandro ColomarQuoted 18 lines · Alejandro Colomar
Hi Branden,
Quoted 7 lines · G. Branden Robinson
Hi Alex,
Quoted 2 lines · Alejandro Colomar
+.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.
Quoted 5 lines
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
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Simon,
Quoted 24 lines · Simon Josefsson
Quoted 22 lines · Alejandro Colomar
Hi Branden,
Quoted 7 lines · G. Branden Robinson
Hi Alex,
Quoted 2 lines · Alejandro Colomar
+.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.
Quoted 7 lines
Quoted 1 line
I could remove the DESCRIPTION altogether... What would you do?
Use the same style as for strlen:
DESCRIPTION
Thestrlen()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.
Quoted 6 lines
RETURN VALUE
Thestrlen()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
Quoted 2 lines
/Simon
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v1 1/1] man/man3/strnul.3: New page
In reply to Alejandro ColomarQuoted 1 line · Alejandro Colomar
+.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.
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Paul,
Quoted 7 lines · Paul Eggert
Quoted 1 line · Alejandro Colomar
+.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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Quoted 6 lines · Alejandro Colomar
Hi Paul,
Quoted 3 lines · Paul Eggert
Quoted 1 line · Alejandro Colomar
+.BI char\~*streq(const\~char\~* s );
Quoted 7 lines
Quoted 4 lines
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 <[email protected]> Date: 2026-02-22 14:34:36 +0100 man/man3/strnul.3: SYNOPSIS: Use QChar Reported-by: Paul Eggert <[email protected]> Signed-off-by: Alejandro Colomar <[email protected]> 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
Signature · 1 line
<https://www.alejandro-colomar.es>
Re: [PATCH v1 1/1] man/man3/strnul.3: New page
Quoted 5 lines · Alejandro Colomar
.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
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Hi Bruno,
Quoted 7 lines · Bruno Haible
Quoted 5 lines · Alejandro Colomar
.B #include <string.h> .P -.BI char\~*strnul(const\~char\~* s ); +.BI QChar\~*strnul(QChar\~* s ); .fi
Quoted 8 lines
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
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerRe: [PATCH v1 1/1] man/man3/strnul.3: New page
Quoted 13 lines · Alejandro Colomar
Hi Bruno,
Quoted 10 lines · Bruno Haible
Quoted 5 lines · Alejandro Colomar
.B #include <string.h> .P -.BI char\~*strnul(const\~char\~* s ); +.BI QChar\~*strnul(QChar\~* s ); .fiOuch. This is not understandable. Why should a user learn about what 'QChar' is??
Quoted 7 lines
Quoted 5 lines
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 <[email protected]> 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 <[email protected]> Suggested-by: Bruno Haible <[email protected]> Signed-off-by: Alejandro Colomar <[email protected]> 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 ()
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerQuoted 4 lines · 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.
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)
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerQuoted 15 lines · Alejandro Colomar
Quoted 4 lines · 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.
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^'man3/strnul.3 +2
-0@@ -0,0 +1,39 @@ +strnul(3) Library Functions Manual strnul(3) +
man3/strnul.3 line 12
Quoted 10 lines
man3/strnul.3 +10
-0+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.
Quoted 30 lines
man3/strnul.3 +27
-0+ +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)Signature · 2 lines
-- <https://www.alejandro-colomar.es>
Signature · 1 line
<https://www.alejandro-colomar.es>
Alejandro Colomar
maintainerv2 cover Document strnul(3)
In reply to Alejandro ColomarHi,
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).Signature · 1 line
2.51.0
Alejandro Colomar
maintainerPATCH v2 1/1 man/man3/strnul.3: New page
--- man/man3/strnul.3 | 48 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 man/man3/strnul.3
man/man3/strnul.3 new file +48 -0
@@ -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)
Signature · 1 line
2.51.0