git: 3fe326bfa030 - stable/14 - memcmp.3: Clarify return value

The branch stable/14 has been updated by emaste:

URL: https://cgit.FreeBSD.org/src/commit/?id=3fe326bfa03025654c017dde7ac8124beb5142fb

commit 3fe326bfa03025654c017dde7ac8124beb5142fb
Author:     Ed Maste <emaste@FreeBSD.org>
AuthorDate: 2024-06-05 20:03:13 +0000
Commit:     Ed Maste <emaste@FreeBSD.org>
CommitDate: 2025-07-29 14:19:49 +0000

    memcmp.3: Clarify return value
    
    The return value is not required to be the difference between the
    differing bytes, only less than zero, zero, or greater than zero.
    
    Reviewed by:    fuz
    Event:          Kitchener-Waterloo Hackathon 202406
    Sponsored by:   The FreeBSD Foundation
    Differential Revision: https://reviews.freebsd.org/D47683
    
    (cherry picked from commit 5cc53d79655bf7f67b1a794c088d896aa6475c2e)
---
 lib/libc/string/memcmp.3 | 43 +++++++++++++++++++++++++------------------
 1 file changed, 25 insertions(+), 18 deletions(-)

diff --git a/lib/libc/string/memcmp.3 b/lib/libc/string/memcmp.3
index bf02412d9e70..8f4980d61c05 100644
--- a/lib/libc/string/memcmp.3
+++ b/lib/libc/string/memcmp.3
@@ -29,14 +29,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     @(#)memcmp.3	8.1 (Berkeley) 6/4/93
-.\"
-.Dd August 15, 2016
+.Dd November 20, 2024
 .Dt MEMCMP 3
 .Os
 .Sh NAME
 .Nm memcmp
-.Nd compare byte string
+.Nd compare bytes in memory
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
@@ -47,27 +45,25 @@
 The
 .Fn memcmp
 function
-compares byte string
+compares byte object
 .Fa b1
-against byte string
+against byte object
 .Fa b2 .
-Both strings are assumed to be
+Both objects are assumed to be
 .Fa len
 bytes long.
 .Sh RETURN VALUES
 The
 .Fn memcmp
-function
-returns zero if the two strings are identical,
-otherwise returns the difference between the first two differing bytes
-(treated as
-.Vt "unsigned char"
-values, so that
-.Sq Li \e200
-is greater than
-.Sq Li \&\e0 ,
-for example).
-Zero-length strings are always identical.
+function returns zero if the two objects are identical.
+Zero-length objects are considered identical.
+The
+.Fn memcmp
+function returns a negative value if the first differing byte has a lower
+value in
+.Fa b1
+and a positive value if the first differing byte has a higher value in
+.Fa b1 .
 .Sh SEE ALSO
 .Xr bcmp 3 ,
 .Xr strcasecmp 3 ,
@@ -82,3 +78,14 @@ The
 function
 conforms to
 .St -isoC .
+.Sh CAVEATS
+If the objects differ, the C library
+.Fn memcmp
+implementation returns the difference between the first two differing bytes
+.Po treated as
+.Vt "unsigned char"
+values
+.Pc .
+This behavior is not specified by
+.St -isoC ,
+is not portable, and may not occur in light of compiler optimizations.