git: c8342584596a - stable/13 - uuid(3): Document return values

From: Guangyuan Yang <>
Date: Mon, 22 Nov 2021 00:43:49 UTC
The branch stable/13 has been updated by ygy (doc, ports committer):


commit c8342584596a0354df6414a0747afe0dfed485e0
Author:     Felix Johnson <>
AuthorDate: 2021-11-19 08:42:49 +0000
Commit:     Guangyuan Yang <>
CommitDate: 2021-11-22 00:43:31 +0000

    uuid(3): Document return values
    PR:             204449
    Reported by:    Michael Cress <>
    (cherry picked from commit f6842865d3367217f2df3e5ae7ecb5b66caf9451)
 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
@@ -68,20 +68,12 @@ The
 .Fn uuid_create_nil
 functions create UUIDs.
-.Fn uuid_compare ,
-.Fn uuid_equal
-.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
 .Fn uuid_from_string
-A 16-bit hash value can be obtained by calling
-.Fn uuid_hash .
 .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.
+.Fn uuid_compare
+.Fn uuid_equal
+functions compare two UUIDs for equality.
+UUIDs are equal if pointers
+.Fa a
+.Fa b
+are equal or both
+.Dv NULL ,
+or if the structures
+.Fa a
+.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.
+.Fn uuid_is_nil
+function compares a UUID to
+.Dv NULL .
+The function returns 1 if
+.Fa u
+or if the UUID consists of all zeros, and zero otherwise.
+.Fn uuid_hash
+function returns a 16-bit hash value for the specified UUID.
 The successful or unsuccessful completion of the function is returned in
@@ -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.
+.Fn uuid_compare ,
+.Fn uuid_equal ,
+.Fn uuid_is_nil ,
+.Fn uuid_hash
+always set
+.Fa status
+.Dv uuid_s_ok .
 .Xr uuidgen 1 ,
 .Xr uuidgen 2