git: f6842865d336 - main - uuid(3): Document return values
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Fri, 19 Nov 2021 08:58:55 UTC
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 <felix.the.red@gmail.com> AuthorDate: 2021-11-19 08:42:49 +0000 Commit: Guangyuan Yang <ygy@FreeBSD.org> CommitDate: 2021-11-19 08:58:34 +0000 uuid(3): Document return values PR: 204449 MFC after: 3 days Reported by: Michael Cress <michael.cress@cress.us> --- 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