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

lib/libc/string/memcmp.3

@@ -29,12 +29,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.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
@@ -45,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 ,
@@ -80,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.