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 March 1, 2012 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. 71The 72.Fn uuid_compare , 73.Fn uuid_equal 74and 75.Fn uuid_is_nil 76functions can be used to test UUIDs. 77To convert from the binary representation to the string representation or 78vice versa, use 79.Fn uuid_to_string 80or 81.Fn uuid_from_string 82respectively. 83A 16-bit hash value can be obtained by calling 84.Fn uuid_hash . 85.Pp 86The 87.Fn uuid_to_string 88function set 89.Fa *str 90to be a pointer to a buffer sufficiently large to hold the string. 91This pointer should be passed to 92.Xr free 3 93to release the allocated storage when it is no longer needed. 94.Pp 95The 96.Fn uuid_enc_le 97and 98.Fn uuid_enc_be 99functions encode a binary representation of a UUID into an octet stream 100in little-endian and big-endian byte-order, respectively. 101The destination buffer must be pre-allocated by the caller, and must be 102large enough to hold the 16-octet binary UUID. 103These routines are not part of the DCE RPC API. 104They are provided for convenience. 105.Pp 106The 107.Fn uuid_dec_le 108and 109.Fn uuid_dec_be 110functions decode a UUID from an octet stream in little-endian and 111big-endian byte-order, respectively. 112These routines are not part of the DCE RPC API. 113They are provided for convenience. 114.Sh RETURN VALUES 115The successful or unsuccessful completion of the function is returned in 116the 117.Fa status 118argument. 119Possible values are: 120.Bl -tag -width ".Dv uuid_s_invalid_string_uuid" 121.It Dv uuid_s_ok 122The function completed successfully. 123.It Dv uuid_s_bad_version 124The UUID does not have a known version. 125.It Dv uuid_s_invalid_string_uuid 126The string representation of an UUID is not valid. 127.It Dv uuid_s_no_memory 128The function can not allocate memory to store an UUID representation. 129.El 130.Sh SEE ALSO 131.Xr uuidgen 1 , 132.Xr uuidgen 2 133.Sh STANDARDS 134The UUID functions conform to the DCE 1.1 RPC specification. 135.Sh BUGS 136This manpage can be improved. 137