| 1 |
.\" SPDX-License-Identifier: 0BSD |
| 2 |
.\" |
| 3 |
.Dd December 8, 2025 |
| 4 |
.ds doc-volume-operating-system OSSP |
| 5 |
.Dt UUID 1 |
| 6 |
.Os ossp-uuid 1.6.6 |
| 7 |
. |
| 8 |
.Sh NAME |
| 9 |
.Nm uuid |
| 10 |
.Nd generate, convert, and decode Universally Unique IDentifiers |
| 11 |
.Sh SYNOPSIS |
| 12 |
.Nm |
| 13 |
.Op Fl n Ar count |
| 14 |
.Op Fl o Ar outfile |
| 15 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 16 |
.Op Fl v Cm 1 |
| 17 |
.Op Fl m1 |
| 18 |
. |
| 19 |
.Nm |
| 20 |
.Op Fl n Ar count |
| 21 |
.Op Fl o Ar outfile |
| 22 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 23 |
.Fl v Cm 3 |
| 24 |
.Ar uuid Ns \&| Ns Cm nil Ns \&| Ns Cm max Ns \&| Ns Cm ns:\& Ns Brq Cm DNS Ns \&| Ns Cm URL Ns \&| Ns Cm OID Ns \&| Ns Cm X500 |
| 25 |
.Ar data |
| 26 |
. |
| 27 |
.Nm |
| 28 |
.Op Fl n Ar count |
| 29 |
.Op Fl o Ar outfile |
| 30 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 31 |
.Fl v Cm 4 |
| 32 |
. |
| 33 |
.Nm |
| 34 |
.Op Fl n Ar count |
| 35 |
.Op Fl o Ar outfile |
| 36 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 37 |
.Fl v Cm 5 |
| 38 |
.Ar uuid Ns \&| Ns Cm nil Ns \&| Ns Cm max Ns \&| Ns Cm ns:\& Ns Brq Cm DNS Ns \&| Ns Cm URL Ns \&| Ns Cm OID Ns \&| Ns Cm X500 |
| 39 |
.Ar data |
| 40 |
. |
| 41 |
.Nm |
| 42 |
.Op Fl n Ar count |
| 43 |
.Op Fl o Ar outfile |
| 44 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 45 |
.Fl v Cm 6 |
| 46 |
. |
| 47 |
.Nm |
| 48 |
.Op Fl n Ar count |
| 49 |
.Op Fl o Ar outfile |
| 50 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 51 |
.Fl v Cm 7 |
| 52 |
.Pp |
| 53 |
. |
| 54 |
.Nm |
| 55 |
.Fl d |
| 56 |
.Op Fl o Ar outfile |
| 57 |
.Op Cm \h'\w'\|-r\fR|\fP'u' Ns Fl F Cm \h'\w'BIN\fR|\fP'u'STR Ns \&| Ns Cm SIV |
| 58 |
.Ar uuid |
| 59 |
. |
| 60 |
.Nm |
| 61 |
.Fl d |
| 62 |
.Op Fl o Ar outfile |
| 63 |
.Op Fl r Ns \&| Ns Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 64 |
.Sy - |
| 65 |
. |
| 66 |
.Sh DESCRIPTION |
| 67 |
By default, generates a UUID (Universally Unique Identifier), |
| 68 |
of a version specified by |
| 69 |
.Fl v |
| 70 |
.Pq default Sy 1 |
| 71 |
in the canonical |
| 72 |
.Cm STR Ns ing |
| 73 |
format. |
| 74 |
.br |
| 75 |
With |
| 76 |
.Fl d , |
| 77 |
decodes |
| 78 |
.Ar uuid |
| 79 |
.Pq or reads it in from the standard input stream if Qq Sy - , |
| 80 |
yielding something akin to |
| 81 |
.Bd -literal -compact -offset 2n |
| 82 |
encode: STR: 92a3d3de-6bbf-11ef-9f5b-774ebb537938 |
| 83 |
SIV: 194917928982963228599463962120788605240 |
| 84 |
decode: variant: DCE 1.1, ISO/IEC 11578:1996 |
| 85 |
version: 1 (time and node based) |
| 86 |
content: time: 2024-09-05 19:46:41.491043.0 UTC |
| 87 |
clock: 8027 (usually random) |
| 88 |
node: 77:4e:bb:53:79:38 (local multicast) |
| 89 |
.Ed |
| 90 |
or |
| 91 |
.Bd -literal -compact -offset 2n |
| 92 |
encode: STR: 7e017d98-cecc-41f6-8030-552d23cd38e6 |
| 93 |
SIV: 167490467173639937831846401373276813542 |
| 94 |
decode: variant: DCE 1.1, ISO/IEC 11578:1996 |
| 95 |
version: 4 (random data based) |
| 96 |
content: 7E:01:7D:98:CE:CC:01:F6:00:30:55:2D:23:CD:38:E6 |
| 97 |
(no semantics: random data only) |
| 98 |
.Ed |
| 99 |
.Pp |
| 100 |
A UUID is a 128-bit (16-byte) number whose format (method of generation) |
| 101 |
makes it very likely that it will be unique, both spatially and temporally. |
| 102 |
This makes them well-suited for identifying anything from ephemera like database queries to databases themselves. |
| 103 |
.Pp |
| 104 |
The three principal |
| 105 |
.Fl F Ns ormats |
| 106 |
are: |
| 107 |
.Bl -tag -compact -offset 2n -width ".Cm SIV Pq Single Integer Value" |
| 108 |
.It Cm STR Ns ing |
| 109 |
.Li 01234567-890a-bcde-f012-3456789abcde |
| 110 |
(hexadecimal string broken up by dashes) |
| 111 |
. |
| 112 |
.It Cm SIV Pq Single Integer Value |
| 113 |
128-bit decimal integer |
| 114 |
. |
| 115 |
.It Cm BIN Ns ary or \&"raw" |
| 116 |
the 16 bytes of the UUID in big endian order (most significant first) |
| 117 |
.El |
| 118 |
.Pp |
| 119 |
UUIDs come in a few |
| 120 |
.Fl v Ns ersions : |
| 121 |
.Bl -tag -compact -offset 2n -width ".Sy 4" |
| 122 |
.It Sy 1 |
| 123 |
based on the current time (to the precision of 100ns), |
| 124 |
and the host's MAC address |
| 125 |
(this implementation uses the MAC address of the first NIC it finds, unless |
| 126 |
.Fl m , |
| 127 |
in which case random data is substituted for the MAC) |
| 128 |
. |
| 129 |
.It Sy 6 |
| 130 |
very similar, but the most significant (slowest-changing) parts of the timestamp are stored first, |
| 131 |
which improves locality in some database applications |
| 132 |
.Pp |
| 133 |
. |
| 134 |
.It Sy 7 |
| 135 |
contains the current |
| 136 |
.Em \s[-1z]UNIX\s0 |
| 137 |
time \(em versions |
| 138 |
.Sy 1 |
| 139 |
and |
| 140 |
.Sy 6 |
| 141 |
encode a UUID time which is off by like 400 years \(em (to the precision of 1ms), |
| 142 |
then 10 bytes of random data. |
| 143 |
.br |
| 144 |
.Em This version should be preferred to 1 and 6.\& |
| 145 |
.Pp |
| 146 |
. |
| 147 |
.It Sy 3 |
| 148 |
hashes the "namespace" (first argument, either a |
| 149 |
.Cm STR Ns ing-format UUID or a well-known name (see below)) |
| 150 |
and the "name" (second argument, arbitrary data) with the |
| 151 |
.Xr MD5 3 |
| 152 |
digest, and uses that directly (a few branding bytes are replaced to identify the format) |
| 153 |
. |
| 154 |
.It Sy 5 |
| 155 |
the same as version |
| 156 |
.Sy 3 , |
| 157 |
but uses the first 16 bytes of the |
| 158 |
.Xr SHA1 3 |
| 159 |
digest |
| 160 |
.Pp |
| 161 |
. |
| 162 |
.It Sy 4 |
| 163 |
just random data |
| 164 |
.El |
| 165 |
.Pp |
| 166 |
The namespaces understood when generating version 3 and 5 UUIDs are: |
| 167 |
.Bl -tag -compact -offset 2n -width ".Cm ns:X500" |
| 168 |
.It Ar uuid |
| 169 |
(any valid |
| 170 |
.Cm STR Ns ingified |
| 171 |
UUID) |
| 172 |
.It Cm nil |
| 173 |
.Li 00000000-0000-0000-0000-000000000000 |
| 174 |
\(em the special all-zero UUID |
| 175 |
. |
| 176 |
.It Cm max |
| 177 |
.Li ffffffff-ffff-ffff-ffff-ffffffffffff |
| 178 |
\(em the special all-bits-set/sorts-after-everything sentinel UUID |
| 179 |
. |
| 180 |
.It Cm ns:DNS |
| 181 |
.Li 6ba7b810-9dad-11d1-80b4-00c04fd430c8 |
| 182 |
\(em for fully-qualified domain names |
| 183 |
. |
| 184 |
.It Cm ns:URL |
| 185 |
.Li 6ba7b811-9dad-11d1-80b4-00c04fd430c8 |
| 186 |
\(em for URLs |
| 187 |
. |
| 188 |
.It Cm ns:OID |
| 189 |
.Li 6ba7b812-9dad-11d1-80b4-00c04fd430c8 |
| 190 |
\(em for ISO OIDs |
| 191 |
. |
| 192 |
.It Cm ns:X500 |
| 193 |
.Li 6ba7b814-9dad-11d1-80b4-00c04fd430c8 |
| 194 |
\(em for X.500 Distinguished Names |
| 195 |
.El |
| 196 |
. |
| 197 |
.Sh OPTIONS |
| 198 |
.Bl -tag -compact -width ".Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV" |
| 199 |
.It Fl n Ar count |
| 200 |
Generate |
| 201 |
.Ar count |
| 202 |
UUIDs. |
| 203 |
Defaults to |
| 204 |
.Sy 1 . |
| 205 |
. |
| 206 |
.It Fl o Ar outfile |
| 207 |
Write to |
| 208 |
.Ar outfile . |
| 209 |
. |
| 210 |
.It Fl F Cm BIN Ns \&| Ns Cm STR Ns \&| Ns Cm SIV |
| 211 |
Produce output in the given format. |
| 212 |
Defaults to |
| 213 |
.Cm STR . |
| 214 |
. |
| 215 |
.It Fl r |
| 216 |
.Fl F Cm BIN |
| 217 |
. |
| 218 |
.It Fl v Cm 1 Ns \&| Ns Cm 3 Ns \&| Ns Cm 4 Ns \&| Ns Cm 5 Ns \&| Ns Cm 6 Ns \&| Ns Cm 7 |
| 219 |
Version to generate. |
| 220 |
Defaults to |
| 221 |
.Cm 1 . |
| 222 |
. |
| 223 |
.It Fl m |
| 224 |
.Fl v Cm 1 Ns \&| Ns Cm 6 |
| 225 |
only: |
| 226 |
ignore the current host's MAC addresses, use random data instead |
| 227 |
(this may still happen if the if a MAC can't be determined or all MACs are multicast). |
| 228 |
. |
| 229 |
.It Fl 1 |
| 230 |
.Fl v Cm 1 |
| 231 |
only, |
| 232 |
.Ar count |
| 233 |
>1 only: |
| 234 |
generate each UUID independently. |
| 235 |
Version 1 UUIDs have a field that increases monotonically within a session; thus, for example, in |
| 236 |
.Bd -literal -compact -offset 2n |
| 237 |
.Li $ Nm Fl n Ar 4 |
| 238 |
366ab5a3-6bc4-11ef-a31a-0026b986fdd4 |
| 239 |
366ab5ce-6bc4-11ef-a31b-0026b986fdd4 |
| 240 |
366ab5f8-6bc4-11ef-a31c-0026b986fdd4 |
| 241 |
366ab621-6bc4-11ef-a31d-0026b986fdd4 |
| 242 |
\(ha\(ha\(ha\(ha |
| 243 |
.Ed |
| 244 |
the highlighted column |
| 245 |
.Em starts |
| 246 |
random, but then increments. |
| 247 |
.Fl 1 |
| 248 |
generates each UUID de novo. |
| 249 |
.Pp |
| 250 |
. |
| 251 |
.It Fl d |
| 252 |
Decode and parse |
| 253 |
.Ar uuid . |
| 254 |
.Fl F |
| 255 |
sets which format to |
| 256 |
.Em read . |
| 257 |
.Fl F Cm BIN |
| 258 |
is only available when reading from the standard input stream |
| 259 |
.Pq Qq Sy - . |
| 260 |
.El |
| 261 |
. |
| 262 |
.Sh EXAMPLES |
| 263 |
A web site can be uniquely identified with a version 5 (SHA-1), namespace |
| 264 |
.Cm ns:DNS |
| 265 |
UUID, and a web-page \(em |
| 266 |
.Cm ns:URL |
| 267 |
(note that this information cannot be extracted, and only serves as a way to avoid collisions for otherwise-identical names): |
| 268 |
.Bd -literal -compact |
| 269 |
.Li $ Nm Fl v Cm 5 ns:DNS Ar hinfo.network.\& |
| 270 |
f50b485f-ac66-591d-b95f-2c946c5a5668 |
| 271 |
.Li $ Nm Fl v Cm 5 ns:URL Ar https://hinfo.network |
| 272 |
8cebc56f-51d0-5323-a031-1b9258de14f8 |
| 273 |
.Li $ Nm Fl d Ar 8cebc56f-51d0-5323-a031-1b9258de14f8 |
| 274 |
encode: STR: f50b485f-ac66-591d-b95f-2c946c5a5668 |
| 275 |
SIV: 325719442146270326702531202385345926760 |
| 276 |
decode: variant: DCE 1.1, ISO/IEC 11578:1996 |
| 277 |
version: 5 (name based, SHA-1) |
| 278 |
content: F5:0B:48:5F:AC:66:09:1D:39:5F:2C:94:6C:5A:56:68 |
| 279 |
(not decipherable: truncated SHA-1 message digest only) |
| 280 |
.Ed |
| 281 |
.Pp |
| 282 |
.Bd -literal -compact |
| 283 |
.Li $ Nm Fl v Cm 7 |
| 284 |
0191c41a-9de1-7f96-b8cb-88e4348ee74c |
| 285 |
.Li $ Nm Fl d Ar 0191c41a-9de1-7f96-b8cb-88e4348ee74c |
| 286 |
encode: STR: 0191c41a-9de1-7f96-b8cb-88e4348ee74c |
| 287 |
SIV: 2086088501348764349551890213853128524 |
| 288 |
decode: variant: DCE 1.1, ISO/IEC 11578:1996 |
| 289 |
version: 7 (UNIX time + random data) |
| 290 |
content: time: 2024-09-05 21:32:44.385 UTC |
| 291 |
random: 0F:96:38:CB:88:E4:34:8E:E7:4C |
| 292 |
.Ed |
| 293 |
. |
| 294 |
.Sh SEE ALSO |
| 295 |
.Xr uuid 3 , |
| 296 |
.Xr OSSP::uuid 3 |
| 297 |
. |
| 298 |
.Sh STANDARDS |
| 299 |
.Lk https://datatracker.ietf.org/doc/html/rfc9562 "RFC 9562: Universally Unique IDentifiers (UUIDs)" |
| 300 |
supersedes all previous standards with an unbecoming brevity. |
| 301 |
.Pp |
| 302 |
There are many Versions, but only one useful Variant. |