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