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: src/lib/libc/uuid/uuid.3,v 1.7 2008/08/14 22:23:16 emax Exp $ 27.\" $DragonFly: src/lib/libc/uuid/uuid.3,v 1.8 2008/08/21 21:41:55 swildner Exp $ 28.\" 29.Dd August 13, 2008 30.Dt UUID 3 31.Os 32.Sh NAME 33.Nm uuid_addr_lookup , 34.Nm uuid_compare , 35.Nm uuid_create , 36.Nm uuid_create_nil , 37.Nm uuid_equal , 38.Nm uuid_from_string , 39.Nm uuid_hash , 40.Nm uuid_is_nil , 41.Nm uuid_name_lookup , 42.Nm uuid_reset_lookup , 43.Nm uuid_to_string 44.Nd DCE 1.1 compliant UUID functions 45.Sh LIBRARY 46.Lb libc 47.Sh SYNOPSIS 48.In uuid.h 49.Ft void 50.Fn uuid_addr_lookup "const uuid_t *u" "char **strp" "uint32_t *status" 51.Ft int32_t 52.Fn uuid_compare "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 53.Ft void 54.Fn uuid_create "uuid_t *uuid" "uint32_t *status" 55.Ft void 56.Fn uuid_create_nil "uuid_t *uuid" "uint32_t *status" 57.Ft int32_t 58.Fn uuid_equal "const uuid_t *uuid1" "const uuid_t *uuid2" "uint32_t *status" 59.Ft void 60.Fn uuid_from_string "const char *str" "uuid_t *uuid" "uint32_t *status" 61.Ft uint16_t 62.Fn uuid_hash "const uuid_t *uuid" "uint32_t *status" 63.Ft int32_t 64.Fn uuid_is_nil "const uuid_t *uuid" "uint32_t *status" 65.Ft void 66.Fn uuid_name_lookup "uuid_t *u" "const char *str" "uint32_t *status" 67.Ft void 68.Fn uuid_reset_lookup "void" 69.Ft void 70.Fn uuid_to_string "const uuid_t *uuid" "char **str" "uint32_t *status" 71.Ft void 72.Fn uuid_enc_le "void *buf" "const uuid_t *uuid" 73.Ft void 74.Fn uuid_dec_le "const void *buf" "uuid_t *" 75.Ft void 76.Fn uuid_enc_be "void *buf" "const uuid_t *uuid" 77.Ft void 78.Fn uuid_dec_be "const void *buf" "uuid_t *" 79.Sh DESCRIPTION 80The family of DCE 1.1 compliant UUID functions allow applications to operate 81on universally unique identifiers, or UUIDs. 82The 83.Fn uuid_create 84and 85.Fn uuid_create_nil 86functions create UUIDs. 87The 88.Fn uuid_compare , 89.Fn uuid_equal 90and 91.Fn uuid_is_nil 92functions can be used to test UUIDs. 93To convert from the binary representation to the string representation or 94vice versa, use 95.Fn uuid_to_string 96or 97.Fn uuid_from_string 98respectively. 99A 16-bit hash value can be obtained by calling 100.Fn uuid_hash . 101.Pp 102String equivalents to UUIDs may be available. 103The 104.Fn uuid_addr_lookup 105function will lookup the symbolic name given a UUID. 106The variable 107.Fa *strp 108should be initialized to 109.Dv NULL . 110Successive calls to 111.Fn uuid_addr_lookup 112will free the previous contents prior to doing the lookup. 113The last string may be freed by calling the function with a 114.Dv NULL 115UUID. 116If a lookup fails, 117.Fa *strp 118will be set to 119.Dv NULL 120and 121.Fa *status 122(if 123.Fa status 124is not 125.Dv NULL ) 126will be set to 127.Dv uuid_s_not_found . 128Otherwise 129.Fa *strp 130will be assigned to the symbolic name and 131.Fa *status 132will be set to 133.Dv uuid_s_ok . 134.Pp 135The 136.Fn uuid_name_lookup 137function will lookup a UUID given a symbolic name. 138The contents of the uuid will be zeroed out if a lookup fails. 139.Pp 140The 141.Fn uuid_reset_lookup 142function will clear its in-memory cache of UUID<->NAME conversions. 143The next lookup will reload the cache. 144.Pp 145The 146.Fn uuid_enc_le 147and 148.Fn uuid_enc_be 149functions encode a binary representation of a UUID into an octet stream 150in little-endian and big-endian byte-order, respectively. 151The destination buffer must be pre-allocated by the caller, and must be 152large enough to hold the 16-octet binary UUID. 153These routines are not part of the DCE RPC API. 154They are provided for convenience. 155.Pp 156The 157.Fn uuid_dec_le 158and 159.Fn uuid_dec_be 160functions decode a UUID from an octet stream in little-endian and 161big-endian byte-order, respectively. 162These routines are not part of the DCE RPC API. 163They are provided for convenience. 164.Sh RETURN VALUES 165The successful or unsuccessful completion of the function is returned in the 166.Fa status 167argument. 168Possible values are: 169.Bl -tag -width ".Dv uuid_s_invalid_string_uuid" 170.It Dv uuid_s_ok 171The function completed successfully. 172.It Dv uuid_s_bad_version 173The UUID does not have a known version. 174.It Dv uuid_s_invalid_string_uuid 175The string representation of an UUID is not valid. 176.It Dv uuid_s_no_memory 177The meaning of the code escaped the writers mind. 178.It Dv uuid_s_not_found 179A UUID lookup failed. 180.El 181.Sh FILES 182.Bl -tag -width ".Pa /etc/defaults/uuids" 183.It Pa /etc/defaults/uuids 184A list of UUIDs and their symbolic names provided by the OS vendor. 185.It Pa /etc/uuids 186A list of UUIDs and their symbolic names provided by the system administrator. 187.El 188.Sh SEE ALSO 189.Xr uuidgen 1 , 190.Xr uuidgen 2 , 191.Xr uuids 5 192.Sh STANDARDS 193The UUID functions conform to the DCE 1.1 RPC specification. 194