File: uuid.3

package info (click to toggle)
ossp-uuid 1.6.2-1.5
  • links: PTS, VCS
  • area: main
  • in suites: buster, jessie, jessie-kfreebsd, sid, stretch
  • size: 2,376 kB
  • ctags: 770
  • sloc: sh: 12,148; ansic: 4,778; makefile: 377; perl: 357; cpp: 256; php: 95; xml: 35
file content (578 lines) | stat: -rw-r--r-- 28,713 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` 
.    ds C' 
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title ".::uuid 3"
.TH .::uuid 3 "OSSP uuid 1.6.2" "04-Jul-2008" "Universally Unique Identifier"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
\&\fB\s-1OSSP\s0 uuid\fR \- \fBUniversally Unique Identifier\fR
.SH "VERSION"
.IX Header "VERSION"
\&\s-1OSSP\s0 uuid \s-11.6.2 (04-Jul-2008)\s0
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1OSSP\s0 uuid\fR is a \s-1ISO\-C:1999\s0 application programming interface (\s-1API\s0) and
corresponding command line interface (\s-1CLI\s0) for the generation of \s-1DCE\s0
1.1, \s-1ISO/IEC\s0 11578:1996 and \s-1IETF\s0 \s-1RFC\-4122\s0 compliant \fIUniversally Unique
Identifier\fR (\s-1UUID\s0). It supports \s-1DCE\s0 1.1 variant UUIDs of version 1 (time
and node based), version 3 (name based, \s-1MD5\s0), version 4 (random number
based) and version 5 (name based, \s-1SHA\-1\s0). Additional \s-1API\s0 bindings are
provided for the languages \s-1ISO\-\*(C+:1998\s0, Perl:5 and \s-1PHP:4/5\s0. Optional
backward compatibility exists for the ISO-C \s-1DCE\-1\s0.1 and Perl Data::UUID
APIs.
.PP
UUIDs are 128 bit numbers which are intended to have a high likelihood
of uniqueness over space and time and are computationally difficult
to guess. They are globally unique identifiers which can be locally
generated without contacting a global registration authority. UUIDs
are intended as unique identifiers for both mass tagging objects
with an extremely short lifetime and to reliably identifying very
persistent objects across a network.
.PP
This is the ISO-C application programming interface (\s-1API\s0) of \fB\s-1OSSP\s0 uuid\fR.
.Sh "\s-1UUID\s0 Binary Representation"
.IX Subsection "UUID Binary Representation"
According to the \s-1DCE\s0 1.1, \s-1ISO/IEC\s0 11578:1996 and \s-1IETF\s0 \s-1RFC\-4122\s0
standards, a \s-1DCE\s0 1.1 variant \s-1UUID\s0 is a 128 bit number defined out of 7
fields, each field a multiple of an octet in size and stored in network
byte order:
.PP
.Vb 11
\&                                                    [4]
\&                                                   version
\&                                                 \-\->|  |<\-\-
\&                                                    |  |
\&                                                    |  |  [16]
\&                [32]                      [16]      |  |time_hi
\&              time_low                  time_mid    | _and_version
\&    |<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->||<\-\-\-\-\-\-\-\-\-\-\-\->||<\-\-\-\-\-\-\-\-\-\-\-\->|
\&    | MSB                          ||              ||  |           |
\&    | /                            ||              ||  |           |
\&    |/                             ||              ||  |           |
\&
\&    +\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-+~~
\&    |  15  ||  14  ||  13  ||  12  ||  11  ||  10  |####9  ||   8  |
\&    | MSO  ||      ||      ||      ||      ||      |####   ||      |
\&    +\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-+~~
\&    7654321076543210765432107654321076543210765432107654321076543210
\&
\&  ~~+\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-+
\&    ##* 7  ||   6  ||   5  ||   4  ||   3  ||   2  ||   1  ||   0  |
\&    ##*    ||      ||      ||      ||      ||      ||      ||  LSO |
\&  ~~+\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-++\-\-\-\-\-\-+
\&    7654321076543210765432107654321076543210765432107654321076543210
\&
\&    | |    ||      ||                                             /|
\&    | |    ||      ||                                            / |
\&    | |    ||      ||                                          LSB |
\&    |<\-\-\-\->||<\-\-\-\->||<\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\->|
\&    |clk_seq clk_seq                      node
\&    |_hi_res _low                         [48]
\&    |[5\-6]    [8]
\&    | |
\& \-\->| |<\-\-
\&  variant
\&   [2\-3]
.Ve
.PP
An example of a \s-1UUID\s0 binary representation is the octet stream \f(CW\*(C`0xF8
0x1D 0x4F 0xAE 0x7D 0xEC 0x11 0xD0 0xA7 0x65 0x00 0xA0 0xC9 0x1E 0x6B
0xF6\*(C'\fR. The binary representation format is exactly what the \fB\s-1OSSP\s0 uuid\fR
\&\s-1API\s0 functions \fBuuid_import\fR() and \fBuuid_export\fR() deal with under
\&\f(CW\*(C`UUID_FMT_BIN\*(C'\fR.
.Sh "\s-1UUID\s0 \s-1ASCII\s0 String Representation"
.IX Subsection "UUID ASCII String Representation"
According to the \s-1DCE\s0 1.1, \s-1ISO/IEC\s0 11578:1996 and \s-1IETF\s0 \s-1RFC\-4122\s0
standards, a \s-1DCE\s0 1.1 variant \s-1UUID\s0 is represented as an \s-1ASCII\s0 string
consisting of 8 hexadecimal digits followed by a hyphen, then three
groups of 4 hexadecimal digits each followed by a hyphen, then 12
hexadecimal digits. Formally, the string representation is defined by
the following grammar:
.PP
.Vb 10
\& uuid                        = <time_low> "\-"
\&                               <time_mid> "\-"
\&                               <time_high_and_version> "\-"
\&                               <clock_seq_high_and_reserved>
\&                               <clock_seq_low> "\-"
\&                               <node>
\& time_low                    = 4*<hex_octet>
\& time_mid                    = 2*<hex_octet>
\& time_high_and_version       = 2*<hex_octet>
\& clock_seq_high_and_reserved = <hex_octet>
\& clock_seq_low               = <hex_octet>
\& node                        = 6*<hex_octet>
\& hex_octet                   = <hex_digit> <hex_digit>
\& hex_digit                   = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
\&                              |"a"|"b"|"c"|"d"|"e"|"f"
\&                              |"A"|"B"|"C"|"D"|"E"|"F"
.Ve
.PP
An example of a \s-1UUID\s0 string representation is the \s-1ASCII\s0 string
"\f(CW\*(C`f81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\*(C'\fR". The string representation
format is exactly what the \fB\s-1OSSP\s0 uuid\fR \s-1API\s0 functions \fBuuid_import\fR()
and \fBuuid_export\fR() deal with under \f(CW\*(C`UUID_FMT_STR\*(C'\fR.
.PP
Notice: a corresponding \s-1URL\s0 can be generated out of a \s-1ASCII\s0 string
representation of an \s-1UUID\s0 by prefixing with "\f(CW\*(C`urn:uuid:\*(C'\fR\*(L" as in
\&\*(R"\f(CW\*(C`urn:uuid:f81d4fae\-7dec\-11d0\-a765\-00a0c91e6bf6\*(C'\fR".
.Sh "\s-1UUID\s0 Single Integer Value Representation"
.IX Subsection "UUID Single Integer Value Representation"
According to the \s-1ISO/IEC\s0 11578:1996 and ITU-T Rec. X.667 standards, a
\&\s-1DCE\s0 1.1 variant \s-1UUID\s0 can be also represented as a single integer value
consisting of a decimal number with up to 39 digits.
.PP
An example of a \s-1UUID\s0 single integer value representation is the decimal
number "\f(CW329800735698586629295641978511506172918\fR". The string
representation format is exactly what the \fB\s-1OSSP\s0 uuid\fR \s-1API\s0 functions
\&\fBuuid_import\fR() and \fBuuid_export\fR() deal with under \f(CW\*(C`UUID_FMT_SIV\*(C'\fR.
.PP
Notice: a corresponding \s-1ISO\s0 \s-1OID\s0 can be generated under the
\&\*(L"{\fIjoint\-iso\-itu\-t\fR\|(2) uuid(25)}\*(R" arc out of a single integer value
representation of a \s-1UUID\s0 by prefixing with "\f(CW2.25.\fR\*(L". An example \s-1OID\s0
is \*(R"\f(CW2.25.329800735698586629295641978511506172918\fR\*(L". Additionally,
an \s-1URL\s0 can be generated by further prefixing with \*(R"\f(CW\*(C`urn:oid:\*(C'\fR\*(L" as in
\&\*(R"\f(CW\*(C`urn:oid:2.25.329800735698586629295641978511506172918\*(C'\fR".
.Sh "\s-1UUID\s0 Variants and Versions"
.IX Subsection "UUID Variants and Versions"
A \s-1UUID\s0 has a variant and version. The variant defines the layout of the
\&\s-1UUID\s0. The version defines the content of the \s-1UUID\s0. The \s-1UUID\s0 variant
supported in \fB\s-1OSSP\s0 uuid\fR is the \s-1DCE\s0 1.1 variant only. The \s-1DCE\s0 1.1 \s-1UUID\s0
variant versions supported in \fB\s-1OSSP\s0 uuid\fR are:
.IP "\fBVersion 1\fR (time and node based)" 4
.IX Item "Version 1 (time and node based)"
These are the classical UUIDs, created out of a 60\-bit system time,
a 14\-bit local clock sequence and 48\-bit system \s-1MAC\s0 address. The \s-1MAC\s0
address can be either the real one of a physical network interface card
(\s-1NIC\s0) or a random multi-cast \s-1MAC\s0 address. Version 1 UUIDs are usually
used as one-time global unique identifiers.
.IP "\fBVersion 3\fR (name based, \s-1MD5\s0)" 4
.IX Item "Version 3 (name based, MD5)"
These are UUIDs which are based on the 128\-bit \s-1MD5\s0 message digest of the
concatenation of a 128\-bit namespace \s-1UUID\s0 and a name string of arbitrary
length. Version 3 UUIDs are usually used for non-unique but repeatable
message digest identifiers.
.IP "\fBVersion 4\fR (random data based)" 4
.IX Item "Version 4 (random data based)"
These are UUIDs which are based on just 128\-bit of random data. Version
4 UUIDs are usually used as one-time local unique identifiers.
.IP "\fBVersion 5\fR (name based, \s-1SHA\-1\s0)" 4
.IX Item "Version 5 (name based, SHA-1)"
These are UUIDs which are based on the 160\-bit \s-1SHA\-1\s0 message digest of the
concatenation of a 128\-bit namespace \s-1UUID\s0 and a name string of arbitrary
length. Version 5 UUIDs are usually used for non-unique but repeatable
message digest identifiers.
.Sh "\s-1UUID\s0 Uniqueness"
.IX Subsection "UUID Uniqueness"
Version 1 UUIDs are guaranteed to be unique through combinations of
hardware addresses, time stamps and random seeds. There is a reference
in the \s-1UUID\s0 to the hardware (\s-1MAC\s0) address of the first network interface
card (\s-1NIC\s0) on the host which generated the \s-1UUID\s0 \*(-- this reference
is intended to ensure the \s-1UUID\s0 will be unique in space as the \s-1MAC\s0
address of every network card is assigned by a single global authority
(\s-1IEEE\s0) and is guaranteed to be unique. The next component in a \s-1UUID\s0
is a timestamp which, as clock always (should) move forward, will
be unique in time. Just in case some part of the above goes wrong
(the hardware address cannot be determined or the clock moved steps
backward), there is a random clock sequence component placed into the
\&\s-1UUID\s0 as a \*(L"catch-all\*(R" for uniqueness.
.PP
Version 3 and version 5 UUIDs are guaranteed to be inherently globally
unique if the combination of namespace and name used to generate them is
unique.
.PP
Version 4 UUIDs are not guaranteed to be globally unique, because they
are generated out of locally gathered pseudo-random numbers only.
Nevertheless there is still a high likelihood of uniqueness over space
and time and that they are computationally difficult to guess.
.Sh "Nil \s-1UUID\s0"
.IX Subsection "Nil UUID"
There is a special \fINil\fR \s-1UUID\s0 consisting of all octets set to zero in
the binary representation. It can be used as a special \s-1UUID\s0 value which does
not conflict with real UUIDs.
.SH "APPLICATION PROGRAMMING INTERFACE"
.IX Header "APPLICATION PROGRAMMING INTERFACE"
The ISO-C Application Programming Interface (\s-1API\s0) of \fB\s-1OSSP\s0 uuid\fR
consists of the following components.
.Sh "\s-1CONSTANTS\s0"
.IX Subsection "CONSTANTS"
The following constants are provided:
.IP "\fB\s-1UUID_VERSION\s0\fR" 4
.IX Item "UUID_VERSION"
The hexadecimal encoded \fB\s-1OSSP\s0 uuid\fR version. This allows compile-time
checking of the \fB\s-1OSSP\s0 uuid\fR version. For run-time checking use
\&\fBuuid_version\fR() instead.
.Sp
The hexadecimal encoding for a version "$\fIv\fR.$\fIr\fR$\fIt\fR$\fIl\fR" is
calculated with the \fB\s-1GNU\s0 shtool\fR \fBversion\fR command and is (in
Perl-style for concise description) "sprintf('0x%x%02x%d%02x', $\fIv\fR,
$\fIr\fR, {qw(s 9 . 2 b 1 a 0)}\->{$\fIt\fR}, ($\fIt\fR eq 's' ? 99 : $\fIl\fR))\*(L",
i.e., the version 0.9.6 is encoded as \*(R"0x009206".
.IP "\fB\s-1UUID_LEN_BIN\s0\fR, \fB\s-1UUID_LEN_STR\s0\fR, \fB\s-1UUID_LEN_SIV\s0\fR" 4
.IX Item "UUID_LEN_BIN, UUID_LEN_STR, UUID_LEN_SIV"
The number of octets of the \s-1UUID\s0 binary and string representations.
Notice that the lengths of the string representation (\fB\s-1UUID_LEN_STR\s0\fR)
and the lengths of the single integer value representation
(\fB\s-1UUID_LEN_SIV\s0\fR) does \fInot\fR include the necessary \f(CW\*(C`NUL\*(C'\fR termination
character.
.IP "\fB\s-1UUID_MAKE_V1\s0\fR, \fB\s-1UUID_MAKE_V3\s0\fR, \fB\s-1UUID_MAKE_V4\s0\fR, \fB\s-1UUID_MAKE_V5\s0\fR, \fB\s-1UUID_MAKE_MC\s0\fR" 4
.IX Item "UUID_MAKE_V1, UUID_MAKE_V3, UUID_MAKE_V4, UUID_MAKE_V5, UUID_MAKE_MC"
The \fImode\fR bits for use with \fBuuid_make\fR(). The \fB\s-1UUID_MAKE_V\s0\fR\fIN\fR
specify which \s-1UUID\s0 version to generate. The \fB\s-1UUID_MAKE_MC\s0\fR forces the
use of a random multi-cast \s-1MAC\s0 address instead of the real physical \s-1MAC\s0
address in version 1 UUIDs.
.IP "\fB\s-1UUID_RC_OK\s0\fR, \fB\s-1UUID_RC_ARG\s0\fR, \fB\s-1UUID_RC_MEM\s0\fR, \fB\s-1UUID_RC_SYS\s0\fR, \fB\s-1UUID_RC_INT\s0\fR, \fB\s-1UUID_RC_IMP\s0\fR" 4
.IX Item "UUID_RC_OK, UUID_RC_ARG, UUID_RC_MEM, UUID_RC_SYS, UUID_RC_INT, UUID_RC_IMP"
The possible numerical return-codes of \s-1API\s0 functions.
The \f(CW\*(C`UUID_RC_OK\*(C'\fR indicates success, the others indicate errors.
Use \fBuuid_error\fR() to translate them into string versions.
.IP "\fB\s-1UUID_FMT_BIN\s0\fR, \fB\s-1UUID_FMT_STR\s0\fR, \fB\s-1UUID_FMT_SIV\s0\fR, \fB\s-1UUID_FMT_TXT\s0\fR" 4
.IX Item "UUID_FMT_BIN, UUID_FMT_STR, UUID_FMT_SIV, UUID_FMT_TXT"
The \fIfmt\fR formats for use with \fBuuid_import\fR() and \fBuuid_export\fR().
The \fB\s-1UUID_FMT_BIN\s0\fR indicates the \s-1UUID\s0 binary representation (of
length \fB\s-1UUID_LEN_BIN\s0\fR), the \fB\s-1UUID_FMT_STR\s0\fR indicates the \s-1UUID\s0 string
representation (of length \fB\s-1UUID_LEN_STR\s0\fR), the \fB\s-1UUID_FMT_SIV\s0\fR
indicates the \s-1UUID\s0 single integer value representation (of maximum
length \fB\s-1UUID_LEN_SIV\s0\fR) and the \fB\s-1UUID_FMT_TXT\s0\fR indicates the textual
description (of arbitrary length) of a \s-1UUID\s0.
.Sh "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
The following functions are provided:
.IP "uuid_rc_t \fBuuid_create\fR(uuid_t **\fIuuid\fR);" 4
.IX Item "uuid_rc_t uuid_create(uuid_t **uuid);"
Create a new \s-1UUID\s0 object and store a pointer to it in \f(CW\*(C`*\*(C'\fR\fIuuid\fR.
A \s-1UUID\s0 object consists of an internal representation of a \s-1UUID\s0, the
internal \s-1PRNG\s0 and \s-1MD5\s0 generator contexts, and cached \s-1MAC\s0 address and
timestamp information. The initial \s-1UUID\s0 is the \fINil\fR \s-1UUID\s0.
.IP "uuid_rc_t \fBuuid_destroy\fR(uuid_t *\fIuuid\fR);" 4
.IX Item "uuid_rc_t uuid_destroy(uuid_t *uuid);"
Destroy \s-1UUID\s0 object \fIuuid\fR.
.IP "uuid_rc_t \fBuuid_clone\fR(const uuid_t *\fIuuid\fR, uuid_t **\fIuuid_clone\fR);" 4
.IX Item "uuid_rc_t uuid_clone(const uuid_t *uuid, uuid_t **uuid_clone);"
Clone \s-1UUID\s0 object \fIuuid\fR and store new \s-1UUID\s0 object in \fIuuid_clone\fR.
.IP "uuid_rc_t \fBuuid_isnil\fR(const uuid_t *\fIuuid\fR, int *\fIresult\fR);" 4
.IX Item "uuid_rc_t uuid_isnil(const uuid_t *uuid, int *result);"
Checks whether the \s-1UUID\s0 in \fIuuid\fR is the \fINil\fR \s-1UUID\s0.
If this is the case, it returns \fItrue\fR in \f(CW\*(C`*\*(C'\fR\fIresult\fR.
Else it returns \fIfalse\fR in \f(CW\*(C`*\*(C'\fR\fIresult\fR.
.IP "uuid_rc_t \fBuuid_compare\fR(const uuid_t *\fIuuid\fR, const uuid_t *\fIuuid2\fR, int *\fIresult\fR);" 4
.IX Item "uuid_rc_t uuid_compare(const uuid_t *uuid, const uuid_t *uuid2, int *result);"
Compares the order of the two UUIDs in \fIuuid1\fR and \fIuuid2\fR
and returns the result in \f(CW\*(C`*\*(C'\fR\fIresult\fR: \f(CW\*(C`\-1\*(C'\fR if \fIuuid1\fR is
smaller than \fIuuid2\fR, \f(CW0\fR if \fIuuid1\fR is equal to \fIuuid2\fR
and \f(CW+1\fR if \fIuuid1\fR is greater than \fIuuid2\fR.
.IP "uuid_rc_t \fBuuid_import\fR(uuid_t *\fIuuid\fR, uuid_fmt_t \fIfmt\fR, const void *\fIdata_ptr\fR, size_t \fIdata_len\fR);" 4
.IX Item "uuid_rc_t uuid_import(uuid_t *uuid, uuid_fmt_t fmt, const void *data_ptr, size_t data_len);"
Imports a \s-1UUID\s0 \fIuuid\fR from an external representation of format \fIfmt\fR.
The data is read from the buffer at \fIdata_ptr\fR which contains at least
\&\fIdata_len\fR bytes.
.Sp
The format of the external representation is specified by \fIfmt\fR and the
minimum expected length in \fIdata_len\fR depends on it. Valid values for
\&\fIfmt\fR are \fB\s-1UUID_FMT_BIN\s0\fR, \fB\s-1UUID_FMT_STR\s0\fR and \fB\s-1UUID_FMT_SIV\s0\fR.
.IP "uuid_rc_t \fBuuid_export\fR(const uuid_t *\fIuuid\fR, uuid_fmt_t \fIfmt\fR, void *\fIdata_ptr\fR, size_t *\fIdata_len\fR);" 4
.IX Item "uuid_rc_t uuid_export(const uuid_t *uuid, uuid_fmt_t fmt, void *data_ptr, size_t *data_len);"
Exports a \s-1UUID\s0 \fIuuid\fR into an external representation of format
\&\fIfmt\fR. Valid values for \fIfmt\fR are \fB\s-1UUID_FMT_BIN\s0\fR, \fB\s-1UUID_FMT_STR\s0\fR,
\&\fB\s-1UUID_FMT_SIV\s0\fR and \fB\s-1UUID_FMT_TXT\s0\fR.
.Sp
The data is written to the buffer whose location is obtained
by dereferencing \fIdata_ptr\fR after a \*(L"cast\*(R" to the appropriate
pointer-to-pointer type. Hence the generic pointer argument \fIdata_ptr\fR
is expected to be a pointer to a \*(L"pointer of a particular type\*(R", i.e.,
it has to be of type "\f(CW\*(C`unsigned char **\*(C'\fR" for \fB\s-1UUID_FMT_BIN\s0\fR and
"\f(CW\*(C`char **\*(C'\fR" for \fB\s-1UUID_FMT_STR\s0\fR, \fB\s-1UUID_FMT_SIV\s0\fR and \fB\s-1UUID_FMT_TXT\s0\fR.
.Sp
The buffer has to be room for at least \f(CW\*(C`*\*(C'\fR\fIdata_len\fR bytes. If the
value of the pointer after \*(L"casting\*(R" and dereferencing \fIdata_ptr\fR
is \f(CW\*(C`NULL\*(C'\fR, \fIdata_len\fR is ignored as input and a new buffer is
allocated and returned in the pointer after \*(L"casting\*(R" and dereferencing
\&\fIdata_ptr\fR (the caller has to \fIfree\fR\|(3) it later on).
.Sp
If \fIdata_len\fR is not \f(CW\*(C`NULL\*(C'\fR, the number of available bytes in the
buffer has to be provided in \f(CW\*(C`*\*(C'\fR\fIdata_len\fR and the number of actually
written bytes are returned in \f(CW\*(C`*\*(C'\fR\fIdata_len\fR again. The minimum
required buffer length depends on the external representation as
specified by \fIfmt\fR and is at least \fB\s-1UUID_LEN_BIN\s0\fR for \fB\s-1UUID_FMT_BIN\s0\fR,
\&\fB\s-1UUID_LEN_STR\s0\fR for \fB\s-1UUID_FMT_STR\s0\fR and \fB\s-1UUID_LEN_SIV\s0\fR for
\&\fB\s-1UUID_FMT_SIV\s0\fR. For \fB\s-1UUID_FMT_TXT\s0\fR a buffer of unspecified length is
required and hence it is recommended to allow \fB\s-1OSSP\s0 uuid\fR to allocate
the buffer as necessary.
.IP "uuid_rc_t \fBuuid_load\fR(uuid_t *\fIuuid\fR, const char *\fIname\fR);" 4
.IX Item "uuid_rc_t uuid_load(uuid_t *uuid, const char *name);"
Loads a pre-defined \s-1UUID\s0 value into the \s-1UUID\s0 object \fIuuid\fR. The
following \fIname\fR arguments are currently known:
.RS 4
.IP "\fIname\fR      \fI\s-1UUID\s0\fR" 4
.IX Item "name      UUID"
.PD 0
.IP "nil       00000000\-0000\-0000\-0000\-000000000000" 4
.IX Item "nil       00000000-0000-0000-0000-000000000000"
.IP "ns:DNS    6ba7b810\-9dad\-11d1\-80b4\-00c04fd430c8" 4
.IX Item "ns:DNS    6ba7b810-9dad-11d1-80b4-00c04fd430c8"
.IP "ns:URL    6ba7b811\-9dad\-11d1\-80b4\-00c04fd430c8" 4
.IX Item "ns:URL    6ba7b811-9dad-11d1-80b4-00c04fd430c8"
.IP "ns:OID    6ba7b812\-9dad\-11d1\-80b4\-00c04fd430c8" 4
.IX Item "ns:OID    6ba7b812-9dad-11d1-80b4-00c04fd430c8"
.IP "ns:X500   6ba7b814\-9dad\-11d1\-80b4\-00c04fd430c8" 4
.IX Item "ns:X500   6ba7b814-9dad-11d1-80b4-00c04fd430c8"
.RE
.RS 4
.PD
.Sp
The "\f(CW\*(C`ns:\*(C'\fR\fI\s-1XXX\s0\fR" are names of pre-defined name-space UUIDs for use in
the generation of \s-1DCE\s0 1.1 version 3 and version 5 UUIDs.
.RE
.IP "uuid_rc_t \fBuuid_make\fR(uuid_t *\fIuuid\fR, unsigned int \fImode\fR, ...);" 4
.IX Item "uuid_rc_t uuid_make(uuid_t *uuid, unsigned int mode, ...);"
Generates a new \s-1UUID\s0 in \fIuuid\fR according to \fImode\fR and optional
arguments (dependent on \fImode\fR).
.Sp
If \fImode\fR contains the \f(CW\*(C`UUID_MAKE_V1\*(C'\fR bit, a \s-1DCE\s0 1.1 variant \s-1UUID\s0 of
version 1 is generated. Then optionally the bit \f(CW\*(C`UUID_MAKE_MC\*(C'\fR forces
the use of random multi-cast \s-1MAC\s0 address instead of the real physical
\&\s-1MAC\s0 address (the default). The \s-1UUID\s0 is generated out of the 60\-bit current
system time, a 12\-bit clock sequence and the 48\-bit \s-1MAC\s0 address.
.Sp
If \fImode\fR contains the \f(CW\*(C`UUID_MAKE_V3\*(C'\fR or \f(CW\*(C`UUID_MAKE_V5\*(C'\fR bit, a \s-1DCE\s0
1.1 variant \s-1UUID\s0 of version 3 or 5 is generated and two additional
arguments are expected: first, a namespace \s-1UUID\s0 object (\f(CW\*(C`uuid_t *\*(C'\fR).
Second, a name string of arbitrary length (\f(CW\*(C`const char *\*(C'\fR). The \s-1UUID\s0 is
generated out of the 128\-bit \s-1MD5\s0 or 160\-bit \s-1SHA\-1\s0 from the concatenated
octet stream of namespace \s-1UUID\s0 and name string.
.Sp
If \fImode\fR contains the \f(CW\*(C`UUID_MAKE_V4\*(C'\fR bit, a \s-1DCE\s0 1.1 variant \s-1UUID\s0
of version 4 is generated. The \s-1UUID\s0 is generated out of 128\-bit random
data.
.IP "char *\fBuuid_error\fR(uuid_rc_t \fIrc\fR);" 4
.IX Item "char *uuid_error(uuid_rc_t rc);"
Returns a constant string representation corresponding to the
return-code \fIrc\fR for use in displaying \fB\s-1OSSP\s0 uuid\fR errors.
.IP "unsigned long \fBuuid_version\fR(void);" 4
.IX Item "unsigned long uuid_version(void);"
Returns the hexadecimal encoded \fB\s-1OSSP\s0 uuid\fR version as compiled into
the library object files. This allows run-time checking of the \fB\s-1OSSP\s0
uuid\fR version. For compile-time checking use \f(CW\*(C`UUID_VERSION\*(C'\fR instead.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The following shows an example usage of the \s-1API\s0. Error handling is
omitted for code simplification and has to be re-added for production
code.
.PP
.Vb 5
\& /* generate a DCE 1.1 v1 UUID from system environment */
\& char *uuid_v1(void)
\& {
\&     uuid_t *uuid;
\&     char *str;
\&
\&     uuid_create(&uuid);
\&     uuid_make(uuid, UUID_MAKE_V1);
\&     str = NULL;
\&     uuid_export(uuid, UUID_FMT_STR, &str, NULL);
\&     uuid_destroy(uuid);
\&     return str;
\& }
\&
\& /* generate a DCE 1.1 v3 UUID from an URL */
\& char *uuid_v3(const char *url)
\& {
\&     uuid_t *uuid;
\&     uuid_t *uuid_ns;
\&     char *str;
\&
\&     uuid_create(&uuid);
\&     uuid_create(&uuid_ns);
\&     uuid_load(uuid_ns, "ns:URL");
\&     uuid_make(uuid, UUID_MAKE_V3, uuid_ns, url);
\&     str = NULL;
\&     uuid_export(uuid, UUID_FMT_STR, &str, NULL);
\&     uuid_destroy(uuid_ns);
\&     uuid_destroy(uuid);
\&     return str;
\& }
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The following are references to \fB\s-1UUID\s0\fR documentation and specifications:
.IP "\(bu" 4
\&\fBA Universally Unique IDentifier (\s-1UUID\s0) \s-1URN\s0 Namespace\fR,
P. Leach, M. Mealling, R. Salz,
\&\s-1IETF\s0 \s-1RFC\-4122\s0,
July 2005, 32 pages,
http://www.ietf.org/rfc/rfc4122.txt
.IP "\(bu" 4
Information Technology \*(-- Open Systems Interconnection (\s-1OSI\s0),
\&\fBProcedures for the operation of \s-1OSI\s0 Registration Authorities:
Generation and Registration of Universally Unique Identifiers (UUIDs)
and their Use as \s-1ASN\s0.1 Object Identifier Components\fR,
\&\s-1ISO/IEC\s0 9834\-8:2004 / ITU-T Rec. X.667, 2004,
December 2004, 25 pages,
http://www.itu.int/ITU\-T/studygroups/com17/oid/X.667\-E.pdf
.IP "\(bu" 4
\&\fB\s-1DCE\s0 1.1: Remote Procedure Call\fR,
appendix \fBUniversally Unique Identifier\fR,
Open Group Technical Standard
Document Number C706, August 1997, 737 pages,
(supersedes C309 \s-1DCE:\s0 Remote Procedure Call 8/1994,
which was basis for \s-1ISO/IEC\s0 11578:1996 specification),
http://www.opengroup.org/publications/catalog/c706.htm
.IP "\(bu" 4
Information technology \*(-- Open Systems Interconnection (\s-1OSI\s0),
\&\fBRemote Procedure Call (\s-1RPC\s0)\fR,
\&\s-1ISO/IEC\s0 11578:1996,
August 2001, 570 pages, (\s-1CHF\s0 340,00),
http://www.iso.ch/cate/d2229.html
.IP "\(bu" 4
\&\fB\s-1HTTP\s0 Extensions for Distributed Authoring (WebDAV)\fR,
section \fB6.4.1 Node Field Generation Without the \s-1IEEE\s0 802 Address\fR,
\&\s-1IETF\s0 \s-1RFC\-2518\s0,
February 1999, 94 pages,
http://www.ietf.org/rfc/rfc2518.txt
.IP "\(bu" 4
\&\fB\s-1DCE\s0 1.1 compliant \s-1UUID\s0 functions\fR,
FreeBSD manual pages \fIuuid\fR\|(3) and \fIuuidgen\fR\|(2),
http://www.freebsd.org/cgi/man.cgi?query=uuid&manpath=FreeBSD+6.0\-RELEASE
.SH "HISTORY"
.IX Header "HISTORY"
\&\fB\s-1OSSP\s0 uuid\fR was implemented in January 2004 by Ralf S. Engelschall
<rse@engelschall.com>. It was prompted by the use of UUIDs
in the \fB\s-1OSSP\s0 as\fR and \fBOpenPKG\fR projects. It is a clean room
implementation intended to be strictly standards compliant and maximum
portable.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIuuid\fR\|(1), \fIuuid\-config\fR\|(1), \fIOSSP::uuid\fR\|(3).