From nobody Fri Nov 19 08:58:55 2021 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 41B3818540DB; Fri, 19 Nov 2021 08:58:56 +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 "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4HwVvh1PmNz3HrJ; Fri, 19 Nov 2021 08:58:56 +0000 (UTC) (envelope-from git@FreeBSD.org) 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 02699255D5; Fri, 19 Nov 2021 08:58:56 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 1AJ8wtpC083030; Fri, 19 Nov 2021 08:58:55 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 1AJ8wtHh083029; Fri, 19 Nov 2021 08:58:55 GMT (envelope-from git) Date: Fri, 19 Nov 2021 08:58:55 GMT Message-Id: <202111190858.1AJ8wtHh083029@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Guangyuan Yang Subject: git: f6842865d336 - main - uuid(3): Document return values 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: Sender: owner-dev-commits-src-all@freebsd.org X-BeenThere: dev-commits-src-all@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ygy X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: f6842865d3367217f2df3e5ae7ecb5b66caf9451 Auto-Submitted: auto-generated X-ThisMailContainsUnwantedMimeParts: N The branch main has been updated by ygy (doc, ports committer): URL: https://cgit.FreeBSD.org/src/commit/?id=f6842865d3367217f2df3e5ae7ecb5b66caf9451 commit f6842865d3367217f2df3e5ae7ecb5b66caf9451 Author: Felix Johnson AuthorDate: 2021-11-19 08:42:49 +0000 Commit: Guangyuan Yang CommitDate: 2021-11-19 08:58:34 +0000 uuid(3): Document return values PR: 204449 MFC after: 3 days Reported by: Michael Cress --- lib/libc/uuid/uuid.3 | 63 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 54 insertions(+), 9 deletions(-) diff --git a/lib/libc/uuid/uuid.3 b/lib/libc/uuid/uuid.3 index 4fa41dec98bd..108ee34f213c 100644 --- a/lib/libc/uuid/uuid.3 +++ b/lib/libc/uuid/uuid.3 @@ -25,7 +25,7 @@ .\" .\" $FreeBSD$ .\" -.Dd March 1, 2012 +.Dd November 19, 2021 .Dt UUID 3 .Os .Sh NAME @@ -68,20 +68,12 @@ The and .Fn uuid_create_nil functions create UUIDs. -The -.Fn uuid_compare , -.Fn uuid_equal -and -.Fn uuid_is_nil -functions can be used to test UUIDs. To convert from the binary representation to the string representation or vice versa, use .Fn uuid_to_string or .Fn uuid_from_string respectively. -A 16-bit hash value can be obtained by calling -.Fn uuid_hash . .Pp The .Fn uuid_to_string @@ -111,6 +103,49 @@ functions decode a UUID from an octet stream in little-endian and big-endian byte-order, respectively. These routines are not part of the DCE RPC API. They are provided for convenience. +.Pp +The +.Fn uuid_compare +and +.Fn uuid_equal +functions compare two UUIDs for equality. +UUIDs are equal if pointers +.Fa a +and +.Fa b +are equal or both +.Dv NULL , +or if the structures +.Fa a +and +.Fa b +point to are equal. +.Fn uuid_compare +returns 0 if the UUIDs are equal, -1 if +.Fa a +is less than +.Fa b , +and 1 if +.Fa a +is greater than +.Fa b . +.Fn uuid_equal +returns 1 if the UUIDs are equal, 0 if they are +not equal. +.Pp +The +.Fn uuid_is_nil +function compares a UUID to +.Dv NULL . +The function returns 1 if +.Fa u +is +.Dv NULL +or if the UUID consists of all zeros, and zero otherwise. +.Pp +The +.Fn uuid_hash +function returns a 16-bit hash value for the specified UUID. .Sh RETURN VALUES The successful or unsuccessful completion of the function is returned in the @@ -127,6 +162,16 @@ The string representation of an UUID is not valid. .It Dv uuid_s_no_memory The function can not allocate memory to store an UUID representation. .El +.Pp +.Fn uuid_compare , +.Fn uuid_equal , +.Fn uuid_is_nil , +and +.Fn uuid_hash +always set +.Fa status +to +.Dv uuid_s_ok . .Sh SEE ALSO .Xr uuidgen 1 , .Xr uuidgen 2