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 , 31.Nm uuid_create , 32.Nm uuid_create_nil , 33.Nm uuid_equal , 34.Nm uuid_from_string , 35.Nm uuid_hash , 36.Nm uuid_is_nil , 37.Nm uuid_to_string 38.Nd DCE 1.1 compliant UUID functions 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In uuid.h 43.Ft int32_t 44.Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 45.Ft void 46.Fn uuid_create "uuid_t *uuid" "uint32_t *status" 47.Ft void 48.Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status" 49.Ft int32_t 50.Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 51.Ft void 52.Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status" 53.Ft uint16_t 54.Fn uuid_hash "const uuid_t *uuid" "uint32_t *status" 55.Ft int32_t 56.Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status" 57.Ft void 58.Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status" 59.Ft void 60.Fn uuid_enc_le "void *buf" "const uuid_t *uuid" 61.Ft void 62.Fn uuid_dec_le "const void *buf" "uuid_t *" 63.Ft void 64.Fn uuid_enc_be "void *buf" "const uuid_t *uuid" 65.Ft void 66.Fn uuid_dec_be "const void *buf" "uuid_t *" 67.Sh DESCRIPTION 68The family of DCE 1.1 compliant UUID functions allow applications to operate 69on universally unique identifiers, or UUIDs. 70The 71.Fn uuid_create 72and 73.Fn uuid_create_nil 74functions create UUIDs. 75To convert from the binary representation to the string representation or 76vice versa, use 77.Fn uuid_to_string 78or 79.Fn uuid_from_string 80respectively. 81.Pp 82The 83.Fn uuid_to_string 84function set 85.Fa *str 86to be a pointer to a buffer sufficiently large to hold the string. 87This pointer should be passed to 88.Xr free 3 89to release the allocated storage when it is no longer needed. 90.Pp 91The 92.Fn uuid_enc_le 93and 94.Fn uuid_enc_be 95functions encode a binary representation of a UUID into an octet stream 96in little-endian and big-endian byte-order, respectively. 97The destination buffer must be pre-allocated by the caller, and must be 98large enough to hold the 16-octet binary UUID. 99These routines are not part of the DCE RPC API. 100They are provided for convenience. 101.Pp 102The 103.Fn uuid_dec_le 104and 105.Fn uuid_dec_be 106functions decode a UUID from an octet stream in little-endian and 107big-endian byte-order, respectively. 108These routines are not part of the DCE RPC API. 109They are provided for convenience. 110.Pp 111The 112.Fn uuid_compare 113and 114.Fn uuid_equal 115functions compare two UUIDs for equality. 116UUIDs are equal if pointers 117.Fa a 118and 119.Fa b 120are equal or both 121.Dv NULL , 122or if the structures 123.Fa a 124and 125.Fa b 126point to are equal. 127.Fn uuid_compare 128returns 0 if the UUIDs are equal, -1 if 129.Fa a 130is less than 131.Fa b , 132and 1 if 133.Fa a 134is greater than 135.Fa b . 136.Fn uuid_equal 137returns 1 if the UUIDs are equal, 0 if they are 138not equal. 139.Pp 140The 141.Fn uuid_is_nil 142function compares a UUID to 143.Dv NULL . 144The function returns 1 if 145.Fa u 146is 147.Dv NULL 148or if the UUID consists of all zeros, and zero otherwise. 149.Pp 150The 151.Fn uuid_hash 152function returns a 16-bit hash value for the specified UUID. 153.Sh RETURN VALUES 154The successful or unsuccessful completion of the function is returned in 155the 156.Fa status 157argument. 158Possible values are: 159.Bl -tag -width ".Dv uuid_s_invalid_string_uuid" 160.It Dv uuid_s_ok 161The function completed successfully. 162.It Dv uuid_s_bad_version 163The UUID does not have a known version. 164.It Dv uuid_s_invalid_string_uuid 165The string representation of an UUID is not valid. 166.It Dv uuid_s_no_memory 167The function can not allocate memory to store an UUID representation. 168.El 169.Pp 170.Fn uuid_compare , 171.Fn uuid_equal , 172.Fn uuid_is_nil , 173and 174.Fn uuid_hash 175always set 176.Fa status 177to 178.Dv uuid_s_ok . 179.Sh SEE ALSO 180.Xr uuidgen 1 , 181.Xr uuidgen 2 182.Sh STANDARDS 183The UUID functions conform to the DCE 1.1 RPC specification. 184.Sh BUGS 185This manpage can be improved. 186