Debian Codegraph @

upstream/debian-unstable/man1/uuid.1

raw
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.