From nobody Wed Nov 20 17:15:35 2024 X-Original-To: dev-commits-src-all@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 4Xtp0S04psz5dWVg; Wed, 20 Nov 2024 17:15:35 +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 4Xtp0R6N0lz4PW7; Wed, 20 Nov 2024 17:15:35 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1732122935; 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=eDMTv2QUsp2e+3kFXR4hbKlacH+yZd/zKpJg5U6fJqo=; b=WrOD0ON+8SGIafwqteE0uFxRJLEm23q5gbvTavk9KecAmWYkzxdaywVKAZ3m6FmzBwglCf Z/J9qteTrcmvH9cxp72ORMLhnVZNSna00OpYIO2ztMA6FzSqjew0xK3GIhPHJGnzJiVrDw bL5RqvoKwXSGGc6kDyZ2AwQU0PSPHCFdNfxyE3j7VtBYKW3e0c5TaLQTNioMdavKON3WfV otnn+ZDgCmNWm3k93Zrfv+4AYCfi723RuzkSsXdEBZxJm7MyYXzWFXr+Ujvnvc/u+1GL+C sWD+AaDbR1GNqB5mxQYdBEITFB6+tIWbhVj/0728WEZ07Lopqgq0Ly5Ye+3LjQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1732122935; 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=eDMTv2QUsp2e+3kFXR4hbKlacH+yZd/zKpJg5U6fJqo=; b=MAQ05rXgab8nOaF2eLAexsPzBq7SsNy6EzGC+CEaB++pqWwj2inenTxGRrvilb49MO7iyW qlsIUhvI2wIbLlgtmoN8Vniw9hwt1sjFeWZ2GNsLFXhpBq80X3Y4w2pyfhh3O7CysWyaeE 1qWv8nuh6eeKBS7FHXmg4WeyXBtBfyP1ugH9f8goJZHcexyX9r+GV+/7+b7JOt+p9rTKIE GV6Lu9euq7XrOqzohdy/fL15H/R1FzRDJQxRjXta4Hn00BilkaUldcpv1UQnmKoz+iX/ja zWVbp9KEmFHKy3HfqceL6xasUr8v7VzVrDMOeOP0cBCqSrPUSysZrrGFbCRLHw== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1732122935; a=rsa-sha256; cv=none; b=f9B3vLSZ/xlT6K1HCtMplzSeWJ7XjCyq4smH35nHRXRZhiSuO0o6/i7FmkDLla/nXABtFK 1XVTUmxnA7Oft3SkXdOrf9hKXpdDTgWL9gLRisnL9t/HJDX/dlDpSVYdYufKLZkhkpGjmV 4tQCjZpGXiB+zuvwKue8SWrFIyCWMLX0paEyirl1ZQP6cvMHjbQcAwxXDH4WhfmNzcEIqB 75j2TuCutkvtEzdBp7zjxefxZsdITiRZ6T/jMUM2MHlQyWPYt6Xyg0Wtlf2LKH82viSefG FbqpaPGS2B/4kutRlHxomH5L1wiW5klWrWedKZgNzDZUEPzw0itwuPTfN5nTjA== 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 4Xtp0R5P8dz13lQ; Wed, 20 Nov 2024 17:15:35 +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 4AKHFZr9026592; Wed, 20 Nov 2024 17:15:35 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 4AKHFZsH026589; Wed, 20 Nov 2024 17:15:35 GMT (envelope-from git) Date: Wed, 20 Nov 2024 17:15:35 GMT Message-Id: <202411201715.4AKHFZsH026589@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Ed Maste Subject: git: 5cc53d79655b - main - memcmp.3: Clarify return value List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@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/main X-Git-Reftype: branch X-Git-Commit: 5cc53d79655bf7f67b1a794c088d896aa6475c2e Auto-Submitted: auto-generated The branch main has been updated by emaste: URL: https://cgit.FreeBSD.org/src/commit/?id=5cc53d79655bf7f67b1a794c088d896aa6475c2e commit 5cc53d79655bf7f67b1a794c088d896aa6475c2e Author: Ed Maste AuthorDate: 2024-06-05 20:03:13 +0000 Commit: Ed Maste CommitDate: 2024-11-20 17:15:11 +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 --- lib/libc/string/memcmp.3 | 41 +++++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/lib/libc/string/memcmp.3 b/lib/libc/string/memcmp.3 index e7666fe6d605..8f4980d61c05 100644 --- a/lib/libc/string/memcmp.3 +++ b/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.