1 '\" te 2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. 3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. 4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. 5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] 6 .TH UUID_CLEAR 3UUID "Jan 16, 2006" 7 .SH NAME 8 uuid_clear, uuid_compare, uuid_copy, uuid_generate, uuid_generate_random, 9 uuid_generate_time, uuid_is_null, uuid_parse, uuid_time, uuid_unparse \- 10 universally unique identifier (UUID) operations 11 .SH SYNOPSIS 12 .LP 13 .nf 14 cc [ \fIflag \&.\|.\|.\fR ] \fIfile\fR\&.\|.\|. \fB-luuid\fR [ \fIlibrary \&.\|.\|.\fR ] 15 #include <uuid/uuid.h> 16 17 \fBvoid\fR \fBuuid_clear\fR(\fBuuid_t\fR \fIuu\fR); 18 .fi 19 20 .LP 21 .nf 22 \fBint\fR \fBuuid_compare\fR(\fBuuid_t\fR \fIuu1\fR, \fBuuid_t\fR \fIuu2\fR); 23 .fi 24 25 .LP 26 .nf 27 \fBvoid\fR \fBuuid_copy\fR(\fBuuid_t\fR \fIdst\fR, \fBuuid_t\fR \fIsrc\fR); 28 .fi 29 30 .LP 31 .nf 32 \fBvoid\fR \fBuuid_generate\fR(\fBuuid_t\fR \fIout\fR); 33 .fi 34 35 .LP 36 .nf 37 \fBvoid\fR \fBuuid_generate_random\fR(\fBuuid_t\fR \fIout\fR); 38 .fi 39 40 .LP 41 .nf 42 \fBvoid\fR \fBuuid_generate_time\fR(\fBuuid_t\fR \fIout\fR); 43 .fi 44 45 .LP 46 .nf 47 \fBint\fR \fBuuid_is_null\fR(\fBuuid_t\fR \fIuu\fR); 48 .fi 49 50 .LP 51 .nf 52 \fBint\fR \fBuuid_parse\fR(\fBchar *\fR\fIin\fR, \fBuuid_t\fR \fIuu\fR); 53 .fi 54 55 .LP 56 .nf 57 \fBtime_t\fR \fBuuid_time\fR(\fBuuid_t\fR \fIuu\fR, \fBstruct timeval *\fR\fIret_tv\fR); 58 .fi 59 60 .LP 61 .nf 62 \fBvoid\fR \fBuuid_unparse\fR(\fBuuid_t\fR \fIuu\fR, \fBchar *\fR\fIout\fR); 63 .fi 64 65 .SH DESCRIPTION 66 .sp 67 .LP 68 The \fBuuid_clear()\fR function sets the value of the specified universally 69 unique identifier (UUID) variable \fIuu\fR to the \fINULL\fR value. 70 .sp 71 .LP 72 The \fBuuid_compare()\fR function compares the two specified UUID variables 73 \fIuu1\fR and \fIuu2\fR to each other. It returns an integer less than, equal 74 to, or greater than zero if \fIuu1\fR is found to be, respectively, 75 lexicographically less than, equal, or greater than \fIuu2\fR. 76 .sp 77 .LP 78 The \fBuuid_copy()\fR function copies the UUID variable \fIsrc\fR to \fIdst\fR. 79 .sp 80 .LP 81 The \fBuuid_generate()\fR function creates a new UUID that is generated based 82 on high-quality randomness from \fB/dev/urandom\fR, if available. If 83 \fB/dev/urandom\fR is not available, \fBuuid_generate()\fR calls 84 \fBuuid_generate_time()\fR. Because the use of this algorithm provides 85 information about when and where the UUID was generated, it could cause privacy 86 problems for some applications. 87 .sp 88 .LP 89 The \fBuuid_generate_random()\fR function produces a UUID with a random or 90 pseudo-randomly generated time and Ethernet MAC address that corresponds to a 91 DCE version 4 UUID. 92 .sp 93 .LP 94 The \fBuuid_generate_time()\fR function uses the current time and the local 95 Ethernet MAC address (if available, otherwise a MAC address is fabricated) that 96 corresponds to a DCE version 1 UUID. If the UUID is not guaranteed to be 97 unique, the multicast bit is set (the high-order bit of octet number 10). 98 .sp 99 .LP 100 The \fBuuid_is_null()\fR function compares the value of the specified UUID 101 variable \fIuu\fR to the \fINULL\fR value. If the value is equal to the 102 \fINULL\fR UUID, 1 is returned. Otherwise 0 is returned. 103 .sp 104 .LP 105 The \fBuuid_parse()\fR function converts the UUID string specified by \fIin\fR 106 to the internal \fBuuid_t\fR format. The input UUID is a string of the form 107 \fBcefa7a9c-1dd2-11b2-8350-880020adbeef\fR. In \fBprintf\fR(3C) format, the 108 string is "\fB%08x-%04x-%04x-%04x-%012x\fR", 36 bytes plus the trailing null 109 character. If the input string is parsed successfully, \fB0\fR is returned and 110 the UUID is stored in the location pointed to by \fIuu\fR. Otherwise \fB-1\fR 111 is returned. 112 .sp 113 .LP 114 The \fBuuid_time()\fR function extracts the time at which the specified UUID 115 \fIuu\fR was created. Since the UUID creation time is encoded within the UUID, 116 this function can reasonably be expected to extract the creation time only for 117 UUIDs created with the \fBuuid_generate_time()\fR function. The time at which 118 the UUID was created, in seconds since January 1, 1970 GMT (the epoch), is 119 returned (see \fBtime\fR(2)). The time at which the UUID was created, in 120 seconds and microseconds since the epoch is also stored in the location pointed 121 to by \fBret_tv\fR (see \fBgettimeofday\fR(3C)). 122 .sp 123 .LP 124 The \fBuuid_unparse()\fR function converts the specified UUID \fIuu\fR from the 125 internal binary format to a string of the length defined in the \fBuuid.h\fR 126 macro, \fBUUID_PRINTABLE_STRING_LENGTH\fR, which includes the trailing null 127 character. The resulting value is stored in the character string pointed to by 128 \fIout\fR. 129 .SH ATTRIBUTES 130 .sp 131 .LP 132 See \fBattributes\fR(5) for descriptions of the following attributes: 133 .sp 134 135 .sp 136 .TS 137 box; 138 c | c 139 l | l . 140 ATTRIBUTE TYPE ATTRIBUTE VALUE 141 _ 142 Interface Stability Evolving 143 _ 144 MT-Level Safe 145 .TE 146 147 .SH SEE ALSO 148 .sp 149 .LP 150 \fBinetd\fR(1M), \fBtime\fR(2), \fBgettimeofday\fR(3C), \fBlibuuid\fR(3LIB), 151 \fBprintf\fR(3C), \fBattributes\fR(5)