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