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