1.\" $OpenBSD: uuid_compare.3,v 1.1 2019/08/30 17:34:36 deraadt Exp $ 2.\" $NetBSD: uuid.3,v 1.7 2008/05/02 18:11:05 martin Exp $ 3.\" 4.\" Copyright (c) 2004 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Jason R. Thorpe. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" Copyright (c) 2002 Marcel Moolenaar 32.\" Copyright (c) 2002 Hiten Mahesh Pandya 33.\" All rights reserved. 34.\" 35.\" Redistribution and use in source and binary forms, with or without 36.\" modification, are permitted provided that the following conditions 37.\" are met: 38.\" 1. Redistributions of source code must retain the above copyright 39.\" notice, this list of conditions and the following disclaimer. 40.\" 2. Redistributions in binary form must reproduce the above copyright 41.\" notice, this list of conditions and the following disclaimer in the 42.\" documentation and/or other materials provided with the distribution. 43.\" 44.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 45.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 46.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 47.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 48.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 49.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 50.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 51.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 52.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 53.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 54.\" SUCH DAMAGE. 55.\" 56.\" $FreeBSD: src/lib/libc/uuid/uuid.3,v 1.4 2003/08/08 19:12:28 marcel Exp $ 57.\" 58.Dd $Mdocdate: August 30 2019 $ 59.Dt UUID_COMPARE 3 60.Os 61.Sh NAME 62.Nm uuid_compare , uuid_create , uuid_create_nil , uuid_equal , 63.Nm uuid_from_string , uuid_hash , uuid_is_nil , uuid_to_string , 64.Nm uuid_enc_le , uuid_dec_le , uuid_enc_be , uuid_dec_be 65.Nd Universally Unique Identifier routines 66.Sh SYNOPSIS 67.In uuid.h 68.Ft int32_t 69.Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 70.Ft void 71.Fn uuid_create "uuid_t *uuid" "uint32_t *status" 72.Ft void 73.Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status" 74.Ft int32_t 75.Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 76.Ft void 77.Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status" 78.Ft uint16_t 79.Fn uuid_hash "const uuid_t *uuid" "uint32_t *status" 80.Ft int32_t 81.Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status" 82.Ft void 83.Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status" 84.Ft void 85.Fn uuid_enc_le "void *buf" "const uuid_t *uuid" 86.Ft void 87.Fn uuid_dec_le "const void *buf" "uuid_t *" 88.Ft void 89.Fn uuid_enc_be "void *buf" "const uuid_t *uuid" 90.Ft void 91.Fn uuid_dec_be "const void *buf" "uuid_t *" 92.Sh DESCRIPTION 93These routines provide for the creation and manipulation of Universally 94Unique Identifiers 95.Pq UUIDs , 96also referred to as Globally Unique Identifiers 97.Pq GUIDs . 98.Pp 99The 100.Fn uuid_compare 101function compares two UUIDs. 102It returns \-1 if 103.Fa uuid1 104precedes 105.Fa uuid2 , 1060 if they are equal, or 1 if 107.Fa uuid1 108follows 109.Fa uuid2 . 110.Pp 111The 112.Fn uuid_create 113function creates a new UUID. 114Storage for the new UUID must be pre-allocated by the caller. 115.Pp 116The 117.Fn uuid_create_nil 118function creates a nil-valued UUID. 119Storage for the new UUID must be pre-allocated by the caller. 120.Pp 121The 122.Fn uuid_equal 123function compares two UUIDs to determine if they are equal. 124It returns 1 if they are equal, and 0 if they are not equal. 125.Pp 126The 127.Fn uuid_from_string 128function parses a 36-character string representation of a UUID and 129converts it to binary representation. 130Storage for the UUID must be pre-allocated by the caller. 131.Pp 132The 133.Fn uuid_hash 134function generates a hash value for the specified UUID. 135Note that the hash value is not a cryptographic hash, and should not be 136assumed to be unique given two different UUIDs. 137.Pp 138The 139.Fn uuid_is_nil 140function returns 1 if the UUID is nil-valued and 0 if it is not. 141.Pp 142The 143.Fn uuid_to_string 144function converts a UUID from binary representation to string representation. 145Storage for the string is dynamically allocated and returned via the 146.Fa str 147argument. 148This pointer should be passed to 149.Xr free 3 150to release the allocated storage when it is no longer needed. 151.Pp 152The 153.Fn uuid_enc_le 154and 155.Fn uuid_enc_be 156functions encode a binary representation of a UUID into an octet stream 157in little-endian and big-endian byte order, respectively. 158The destination buffer must be pre-allocated by the caller, and must be 159large enough to hold the 16-octet binary UUID. 160.Pp 161The 162.Fn uuid_dec_le 163and 164.Fn uuid_dec_be 165functions decode a UUID from an octet stream in little-endian and 166big-endian byte order, respectively. 167.Sh RETURN VALUES 168The 169.Fn uuid_compare , 170.Fn uuid_create , 171.Fn uuid_create_nil , 172.Fn uuid_equal , 173.Fn uuid_from_string , 174.Fn uuid_hash , 175.Fn uuid_is_nil , 176and 177.Fn uuid_to_string 178functions return successful or unsuccessful completion status in the 179.Fa status 180argument unless it is 181.Dv NULL . 182Possible values are: 183.Bl -tag -width ".Dv uuid_s_invalid_string_uuid" 184.It Dv uuid_s_ok 185The function completed successfully. 186.It Dv uuid_s_bad_version 187The UUID does not have a known version. 188.It Dv uuid_s_invalid_string_uuid 189The string representation of a UUID is not valid. 190.It Dv uuid_s_no_memory 191Memory could not be allocated for the operation. 192.El 193.\" .Sh SEE ALSO 194.\" .Xr uuidgen 1 195.Sh STANDARDS 196The 197.Fn uuid_compare , 198.Fn uuid_create , 199.Fn uuid_create_nil , 200.Fn uuid_equal , 201.Fn uuid_from_string , 202.Fn uuid_hash , 203.Fn uuid_is_nil , 204and 205.Fn uuid_to_string 206functions are compatible with the DCE 1.1 RPC specification. 207.Pp 208.Fn uuid_create 209generates version 4 UUIDs, 210specified by section 4.4 of RFC 4122. 211