| blob | 17202686267dab3491c4acb4b45fb87a835ad230 |
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
94 These routines provide for the creation and manipulation of Universally
95 Unique Identifiers
96 .Pq UUIDs ,
97 also referred to as Globally Unique Identifiers
98 .Pq GUIDs .
99 .Pp
100 The
101 .Fn uuid_compare
102 function compares two UUIDs.
103 It returns \-1 if
104 .Fa uuid1
105 precedes
106 .Fa uuid2 ,
107 0 if they are equal, or 1 if
108 .Fa uuid1
109 follows
110 .Fa uuid2 .
111 .Pp
112 The
113 .Fn uuid_create
114 function creates a new UUID.
115 Storage for the new UUID must be pre-allocated by the caller.
116 .Pp
117 The
118 .Fn uuid_create_nil
119 function creates a nil-valued UUID.
120 Storage for the new UUID must be pre-allocated by the caller.
121 .Pp
122 The
123 .Fn uuid_equal
124 function compares two UUIDs to determine if they are equal.
125 It returns 1 if they are equal, and 0 if they are not equal.
126 .Pp
127 The
128 .Fn uuid_from_string
129 function parses a 36-character string representation of a UUID and
130 converts it to binary representation.
131 Storage for the UUID must be pre-allocated by the caller.
132 .Pp
133 The
134 .Fn uuid_hash
135 function generates a hash value for the specified UUID.
136 Note that the hash value is not a cryptographic hash, and should not be
137 assumed to be unique given two different UUIDs.
138 .Pp
139 The
140 .Fn uuid_is_nil
141 function returns 1 if the UUID is nil-valued and 0 if it is not.
142 .Pp
143 The
144 .Fn uuid_to_string
145 function converts a UUID from binary representation to string representation.
146 Storage for the string is dynamically allocated and returned via the
147 .Fa str
148 argument.
149 This pointer should be passed to
150 .Xr free 3
151 to release the allocated storage when it is no longer needed.
152 .Pp
153 The
154 .Fn uuid_enc_le
155 and
156 .Fn uuid_enc_be
157 functions encode a binary representation of a UUID into an octet stream
158 in little-endian and big-endian byte-order, respectively.
159 The destination buffer must be pre-allocated by the caller, and must be
160 large enough to hold the 16-octet binary UUID.
161 .Pp
162 The
163 .Fn uuid_dec_le
164 and
165 .Fn uuid_dec_be
166 functions decode a UUID from an octet stream in little-endian and
167 big-endian byte-order, respectively.
168 .Sh RETURN VALUES
169 The
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 ,
177 and
178 .Fn uuid_to_string
179 functions return successful or unsuccessful completion status in the
180 .Fa status
181 argument.
182 Possible values are:
183 .Pp
184 .Bl -tag -width ".Dv uuid_s_invalid_string_uuid"
185 .It Dv uuid_s_ok
186 The function completed successfully.
187 .It Dv uuid_s_bad_version
188 The UUID does not have a known version.
189 .It Dv uuid_s_invalid_string_uuid
190 The string representation of a UUID is not valid.
191 .It Dv uuid_s_no_memory
192 Memory could not be allocated for the operation.
193 .El
194 .Sh SEE ALSO
195 .Xr uuidgen 1 ,
196 .Xr uuidgen 2
197 .Sh STANDARDS
198 The
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 ,
206 and
207 .Fn uuid_to_string
208 functions are compatible with the DCE 1.1 RPC specification.
209 .Sh HISTORY
210 The UUID functions first appeared in
211 .Nx 3.0 .