From nobody Tue Jul 29 14:20:14 2025 X-Original-To: dev-commits-src-branches@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bryDH10wqz6336W; Tue, 29 Jul 2025 14:20:15 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bryDH0DShz3KKF; Tue, 29 Jul 2025 14:20:15 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1753798815; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=tRGC8m2haVEFXA2OuziHfm164CrpIE8UHhI5EPSVmIE=; b=J/T+QCtuDIe8mQAOiIjjaymBV0YUOQBLdTEMlIKxcd7ftR57g0MP3y4gsnKeRItXN6oX2u Zy2SPUiIDkGWO1Z3n1Hqr/a828QeThjFWwZoaXjP/+cYaJ072WffecbjQALFTUcOHZO1i/ WmAf7+Vo0FbOz1J8LivB9D+7W2K+gaqauiDrsJ7Xp4NddowAePhhpRtvN/dM/3tpXGGO0K 4mEOPqfxZnf5+WRQfgRGb4UjPRvqxM8TxtRBftQ+1FV916TMmNXx/OmyUWpTZ0vUGShHHf NlBHrIFZ2lX6rqbN8fL7Z0M8RVAv/hfVk362RyPpsf9NrWou348M1Kiji9hZsA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1753798815; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=tRGC8m2haVEFXA2OuziHfm164CrpIE8UHhI5EPSVmIE=; b=c2GLySRflELPHgz/QcjU1bssxq+lYIS/xkXSduTJRm0R2Cs7gWHubc+bsBDn7cjwzAvviJ Wc6v25mpMSesED3IzQC/8kPQIge65NtzZE7qNa2j5bAx3efFOZmiXWZ58lz3s4+fAp6uny 4kT2Qb16PwpdunC4hR4Ea1wRdycNqcSjwJnteOeiQiM9s2FkPwkFrYympiYvX47o5BMjnM 9KMy37pbSspOnXnD5Y7vlVs9oT2vRLGZZwnZ4p7ZHokzBGjku4DyO92CxOKKV8SNM1zTRO busbSGrWOsepKaujykQ47gvfKewMaE2e9HHkCYMdwecAgBZTOyuwIct0NUgrZg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1753798815; a=rsa-sha256; cv=none; b=vjuR4zSFwyW2YEAbByq34Lnx+hFJLNvfiOv+7FGq0ORVkN4W4LkL8aO7Eh+2WvtK5aW4D2 cjfXQrv+b2DLYgRwVPYAsYG+tr7ZJLKybCoICgG87CJ6lr1o+n7Oh/Q6wHXcNN8NGxmt4F 8TSQ6+vTBRTkvnw/wvywZdwkoqO6tI328WrYq5EhytKGR3GkaJyQxcQjmjmQVtJ44tdL8O 29uqhZZjLMCE669vJocnutVr7Junc5VufxLQ79R4d0j81LVh3h/Xk7LhCW+TCdetuhti73 rlsgnGfOs1vzy6tCrwWpxKFitHiMqOd806EGhHihT+RpXttn+A1hhfbrGKmnyQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bryDG6fb4zbV3; Tue, 29 Jul 2025 14:20:14 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56TEKE1M012972; Tue, 29 Jul 2025 14:20:14 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56TEKEx3012961; Tue, 29 Jul 2025 14:20:14 GMT (envelope-from git) Date: Tue, 29 Jul 2025 14:20:14 GMT Message-Id: <202507291420.56TEKEx3012961@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Ed Maste Subject: git: 3fe326bfa030 - stable/14 - memcmp.3: Clarify return value List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-branches@freebsd.org Sender: owner-dev-commits-src-branches@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: emaste X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: 3fe326bfa03025654c017dde7ac8124beb5142fb Auto-Submitted: auto-generated The branch stable/14 has been updated by emaste: URL: https://cgit.FreeBSD.org/src/commit/?id=3fe326bfa03025654c017dde7ac8124beb5142fb commit 3fe326bfa03025654c017dde7ac8124beb5142fb Author: Ed Maste AuthorDate: 2024-06-05 20:03:13 +0000 Commit: Ed Maste 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.