>From 7f4c2265f6ca97b0d11cfb8eb242ffd0a6ec03bb Mon Sep 17 00:00:00 2001
From: James Hunt <james.hunt-GeWIH/nMZzLQT0dZR+AlfA@public.gmane.org>
Date: Tue, 29 Nov 2011 09:32:38 +0000
Subject: Explain behaviour of memchr+strchr when searching for null byte.

---
 man3/memchr.3 |   21 +++++++++++++++++++++
 man3/strchr.3 |    7 +++++++
 2 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/man3/memchr.3 b/man3/memchr.3
index af8f314..873ea48 100644
--- a/man3/memchr.3
+++ b/man3/memchr.3
@@ -109,6 +109,27 @@ The
 .BR rawmemchr ()
 function returns a pointer to the matching byte, if one is found.
 If no matching byte is found, the result is unspecified.
+.SH NOTES
+If \fIn\fP is large enough to include the null byte (\(aq\\0\(aq) at the
+end of \fIs\fP and the character \fIc\fP is specified as the null byte,
+.BR memchr ()
+behaves like 
+.BR strchr (3) "" ","
+returning a pointer to the null byte at the end of \fIs\fP rather than
+NULL.
+.in +4n
+.nf
+
+char str[] = "abc";
+char *p;
+
+/* will set \(aqp\(aq to NULL */
+p = memchr(str, \(aq\\0\(aq, strlen(str));
+
+/* will set \(aqp\(aq to address of terminating null of \(aqstr\(aq */
+p = memchr(str, \(aq\\0\(aq, strlen(str) + 1);
+.fi
+.in
 .SH VERSIONS
 .BR rawmemchr ()
 first appeared in glibc in version 2.1.
diff --git a/man3/strchr.3 b/man3/strchr.3
index b2ecfef..8ff2906 100644
--- a/man3/strchr.3
+++ b/man3/strchr.3
@@ -72,6 +72,13 @@ and
 .BR strrchr ()
 functions return a pointer to
 the matched character or NULL if the character is not found.
+.PP
+If the character \fIc\fP is specified as the null byte (\(aq\\0\(aq),
+.BR strchr ()
+and
+.BR strrchr ()
+return a pointer to address of the null byte at the end of \fIs\fP,
+rather than NULL.
 
 The
 .BR strchrnul ()
-- 
1.7.5.4