1.\" Copyright (c) 2002 Marcel Moolenaar 2.\" Copyright (c) 2002 Hiten Mahesh Pandya 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 19.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 20.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 21.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 22.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd November 19, 2021 27.Dt UUID 3 28.Os 29.Sh NAME 30.Nm uuid_compare , uuid_create , uuid_create_nil , uuid_equal , 31.Nm uuid_from_string , uuid_hash , uuid_is_nil , uuid_to_string 32.Nd DCE 1.1 compliant UUID functions 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In uuid.h 37.Ft int32_t 38.Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 39.Ft void 40.Fn uuid_create "uuid_t *uuid" "uint32_t *status" 41.Ft void 42.Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status" 43.Ft int32_t 44.Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 45.Ft void 46.Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status" 47.Ft uint16_t 48.Fn uuid_hash "const uuid_t *uuid" "uint32_t *status" 49.Ft int32_t 50.Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status" 51.Ft void 52.Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status" 53.Ft void 54.Fn uuid_enc_le "void *buf" "const uuid_t *uuid" 55.Ft void 56.Fn uuid_dec_le "const void *buf" "uuid_t *" 57.Ft void 58.Fn uuid_enc_be "void *buf" "const uuid_t *uuid" 59.Ft void 60.Fn uuid_dec_be "const void *buf" "uuid_t *" 61.Sh DESCRIPTION 62The family of DCE 1.1 compliant UUID functions allow applications to operate 63on universally unique identifiers, or UUIDs. 64The 65.Fn uuid_create 66and 67.Fn uuid_create_nil 68functions create UUIDs. 69To convert from the binary representation to the string representation or 70vice versa, use 71.Fn uuid_to_string 72or 73.Fn uuid_from_string 74respectively. 75.Pp 76The 77.Fn uuid_to_string 78function set 79.Fa *str 80to be a pointer to a buffer sufficiently large to hold the string. 81This pointer should be passed to 82.Xr free 3 83to release the allocated storage when it is no longer needed. 84.Pp 85The 86.Fn uuid_enc_le 87and 88.Fn uuid_enc_be 89functions encode a binary representation of a UUID into an octet stream 90in little-endian and big-endian byte-order, respectively. 91The destination buffer must be pre-allocated by the caller, and must be 92large enough to hold the 16-octet binary UUID. 93These routines are not part of the DCE RPC API. 94They are provided for convenience. 95.Pp 96The 97.Fn uuid_dec_le 98and 99.Fn uuid_dec_be 100functions decode a UUID from an octet stream in little-endian and 101big-endian byte-order, respectively. 102These routines are not part of the DCE RPC API. 103They are provided for convenience. 104.Pp 105The 106.Fn uuid_compare 107and 108.Fn uuid_equal 109functions compare two UUIDs for equality. 110UUIDs are equal if pointers 111.Fa a 112and 113.Fa b 114are equal or both 115.Dv NULL , 116or if the structures 117.Fa a 118and 119.Fa b 120point to are equal. 121.Fn uuid_compare 122returns 0 if the UUIDs are equal, -1 if 123.Fa a 124is less than 125.Fa b , 126and 1 if 127.Fa a 128is greater than 129.Fa b . 130.Fn uuid_equal 131returns 1 if the UUIDs are equal, 0 if they are 132not equal. 133.Pp 134The 135.Fn uuid_is_nil 136function compares a UUID to 137.Dv NULL . 138The function returns 1 if 139.Fa u 140is 141.Dv NULL 142or if the UUID consists of all zeros, and zero otherwise. 143.Pp 144The 145.Fn uuid_hash 146function returns a 16-bit hash value for the specified UUID. 147.Sh RETURN VALUES 148The successful or unsuccessful completion of the function is returned in 149the 150.Fa status 151argument. 152Possible values are: 153.Bl -tag -width ".Dv uuid_s_invalid_string_uuid" 154.It Dv uuid_s_ok 155The function completed successfully. 156.It Dv uuid_s_bad_version 157The UUID does not have a known version. 158.It Dv uuid_s_invalid_string_uuid 159The string representation of an UUID is not valid. 160.It Dv uuid_s_no_memory 161The function can not allocate memory to store an UUID representation. 162.El 163.Pp 164.Fn uuid_compare , 165.Fn uuid_equal , 166.Fn uuid_is_nil , 167and 168.Fn uuid_hash 169always set 170.Fa status 171to 172.Dv uuid_s_ok . 173.Sh SEE ALSO 174.Xr uuidgen 1 , 175.Xr uuidgen 2 176.Sh STANDARDS 177The UUID functions conform to the DCE 1.1 RPC specification. 178.Sh BUGS 179This manpage can be improved. 180