1.\" 2.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved. 3.\" Copyright 2014 Andrew Stormont. 4.\" Copyright 2021 Oxide Computer Company 5.\" 6.\" The contents of this file are subject to the terms of the 7.\" Common Development and Distribution License (the "License"). 8.\" You may not use this file except in compliance with the License. 9.\" 10.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 11.\" or http://www.opensolaris.org/os/licensing. 12.\" See the License for the specific language governing permissions 13.\" and limitations under the License. 14.\" 15.\" When distributing Covered Code, include this CDDL HEADER in each 16.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 17.\" If applicable, add the following below this CDDL HEADER, with the 18.\" fields enclosed by brackets "[]" replaced with your own identifying 19.\" information: Portions Copyright [yyyy] [name of copyright owner] 20.\" 21.Dd November 30, 2021 22.Dt UUID_CLEAR 3UUID 23.Os 24.Sh NAME 25.Nm uuid_clear , 26.Nm uuid_compare , 27.Nm uuid_copy , 28.Nm uuid_generate , 29.Nm uuid_generate_random , 30.Nm uuid_generate_time , 31.Nm uuid_is_null , 32.Nm uuid_parse , 33.Nm uuid_time , 34.Nm uuid_unparse , 35.Nm uuid_unparse_lower , 36.Nm uuid_unparse_upper 37.Nd universally unique identifier (UUID) operations 38.Sh LIBRARY 39.Lb libuuid 40.Sh SYNOPSIS 41.In uuid/uuid.h 42.Ft void 43.Fo uuid_clear 44.Fa "uuid_t uu" 45.Fc 46.Ft int 47.Fo uuid_compare 48.Fa "uuid_t uu1" 49.Fa "uuid_t uu2" 50.Fc 51.Ft void 52.Fo uuid_copy 53.Fa "uuid_t dst" 54.Fa "uuid_t src" 55.Fc 56.Ft void 57.Fo uuid_generate 58.Fa "uuid_t out" 59.Fc 60.Ft void 61.Fo uuid_generate_random 62.Fa "uuid_t out" 63.Fc 64.Ft void 65.Fo uuid_generate_time 66.Fa "uuid_t out" 67.Fc 68.Ft int 69.Fo uuid_is_null 70.Fa "uuid_t uu" 71.Fc 72.Ft int 73.Fo uuid_parse 74.Fa "char *int" 75.Fa "uuid_t uu" 76.Fc 77.Ft time_t 78.Fo uuid_time 79.Fa "uuid_t uu" 80.Fa "struct timeval *ret_tv" 81.Fc 82.Ft void 83.Fo uuid_unparse 84.Fa "uuid_t uu" 85.Fa "char *out" 86.Fc 87.Ft void 88.Fo uuid_unparse_lower 89.Fa "uuid_t uu" 90.Fa "char *out" 91.Fc 92.Ft void 93.Fo uuid_unparse_upper 94.Fa "uuid_t uu" 95.Fa "char *out" 96.Fc 97.Sh DESCRIPTION 98The 99.Fn uuid_clear 100function sets the value of the specified universally unique identifier 101.Pq UUID 102variable 103.Fa uu 104to the NULL value. 105.Pp 106The 107.Fn uuid_compare 108function compares the two specified UUID variables 109.Fa uu1 110and 111.Fa uu2 112to each other. 113It returns an integer less than, equal to, or greater than zero if 114.Fa uu1 115is found to be, respectively, lexicographically less than, equal, or greater 116than 117.Fa uu2 . 118.Pp 119The 120.Fn uuid_copy 121function copies the UUID variable 122.Fa src 123to 124.Fa dst . 125.Pp 126The 127.Fn uuid_generate 128and 129.Fn uuid_generate_random 130functions create a new UUID that is generated based on high-quality randomness 131utilizing the 132.Xr arc4random 3C 133function. 134These correspond to a DCE version 4 UUID. 135On some implementations it is possible that the 136.Fn uuid_generate 137function will fall back to generating a version 1 UUID. 138While in our current implementation this is not possible, applications should 139not assume a guaranteed format when calling the 140.Fn uuid_generate 141function. 142.Pp 143The 144.Fn uuid_generate_time 145function uses the current time and the local Ethernet MAC address 146.Pq if available, otherwise a MAC address is fabricated 147that corresponds to a DCE version 1 UUID. 148If the UUID is not guaranteed to be unique, the multicast bit is set 149.Pq the high-order bit of octet number 10 . 150.Pp 151The 152.Fn uuid_is_null 153function compares the value of the specified UUID variable 154.Fa uu 155to the NULL value. 156If the value is equal to the NULL UUID, 157.Sy 1 158is returned. 159Otherwise 160.Sy 0 161is returned. 162.Pp 163The 164.Fn uuid_parse 165function converts the UUID string specified by 166.Fa in 167to the internal 168.Vt uuid_t 169format. 170The input UUID is a string of the form 171.Sy cefa7a9c-1dd2-11b2-8350-880020adbeef . 172In 173.Xr printf 3C 174format, the string is 175.Dq Sy %08x-%04x-%04x-%04x-%012x , 17636 bytes plus the trailing null character. 177If the input string is parsed successfully, 178.Sy 0 179is returned and the UUID is stored in the location pointed to by 180.Fa uu . 181Otherwise 182.Sy -1 183is returned. 184.Pp 185The 186.Fn uuid_time 187function extracts the time at which the specified UUID 188.Fa uu 189was created. 190Since the UUID creation time is encoded within the UUID, this function can 191reasonably be expected to extract the creation time only for UUIDs created with 192the 193.Fn uuid_generate_time 194function. 195The time at which the UUID was created, in seconds since January 1, 1970 GMT 196.Pq the epoch , 197is returned 198.Po 199see 200.Xr time 2 201.Pc . 202The time at which the UUID was created, in seconds and microseconds since the 203epoch is also stored in the location pointed to by 204.Fa ret_tv 205.Po 206see 207.Xr gettimeofday 3C 208.Pc . 209.Pp 210The 211.Fn uuid_unparse 212and 213.Fn uuid_unparse_lower 214functions convert the specified UUID 215.Fa uu 216from the internal binary format to a lower case string of the length defined in 217the 218.In uuid/uuid.h 219macro, 220.Dv UUID_PRINTABLE_STRING_LENGTH , 221which includes the trailing null character. 222The resulting value is stored in the character string pointed to by 223.Fa out . 224.Pp 225The uuid_unparse_upper 226function converts the specified UUID 227.Fa uu 228from the internal binary format to a upper case string of the length defined in 229the 230.In uuid/uuid.h 231macro, 232.Dv UUID_PRINTABLE_STRING_LENGTH , 233which includes the trailing null character. 234The resulting value is stored in the character string pointed to by 235.Fa out . 236.Sh INTERFACE STABILITY 237.Sy Evolving 238.Sh MT-LEVEL 239.Sy Safe 240.Sh SEE ALSO 241.Xr time 2 , 242.Xr arc4random 3C , 243.Xr gettimeofday 3C , 244.Xr printf 3C , 245.Xr libuuid 3LIB , 246.Xr attributes 7 247