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