Skip to contentSkip to conversation

Document strnul(3)

PATCH Superseded Alejandro Colomar 5 participants 18 messages Feb 21 – Feb 22 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Alejandro Colomar

author maintainer
#0 lore raw

cover 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
author maintainer
#1 lore raw

PATCH 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
new file mode 100644
index 000000000000..05995f0407af
@@ -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
#2 lore raw

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

author maintainer
#3 lore raw

Re: [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--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. :)

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>
#4 lore raw

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

author maintainer
#5 lore raw

Re: [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() with strdup() 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>
#6 lore raw

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

In reply to Alejandro Colomar
Quoted 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

author maintainer
#7 lore raw

Re: [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
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.

Quoted 6 lines

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

Quoted 2 lines

/Simon

Signature · 1 line
<https://www.alejandro-colomar.es>
#8 lore raw

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

In reply to Alejandro Colomar
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.

author maintainer
#9 lore raw

Re: [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>
author maintainer
#10 lore raw

Re: [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>
#11 lore raw

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

author maintainer
#12 lore raw

Re: [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>
author maintainer
#13 lore raw

Re: [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 );
	 .fi

Ouch. 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>
author maintainer
#14 lore raw
In reply to 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^'
--- 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>
author maintainer
#15 lore raw
Quoted 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>
author maintainer
#16 lore raw

v2 cover Document strnul(3)

In reply to 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).
Signature · 1 line
2.51.0
author maintainer
#17 lore raw

PATCH 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
new file mode 100644
index 000000000000..0554edb401e9
@@ -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