1.\" Copyright (c) 2002 Marcel Moolenaar 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/lib/libc/sys/uuidgen.2,v 1.8 2005/07/31 03:30:44 keramida Exp $ 26.\" $DragonFly: src/lib/libc/sys/uuidgen.2,v 1.1 2007/06/16 19:57:13 dillon Exp $ 27.\" 28.Dd May 26, 2002 29.Dt UUIDGEN 2 30.Os 31.Sh NAME 32.Nm uuidgen 33.Nd generate universally unique identifiers 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In sys/uuid.h 38.Ft int 39.Fn uuidgen "struct uuid *store" "int count" 40.Sh DESCRIPTION 41The 42.Fn uuidgen 43system call generates 44.Fa count 45universally unique identifiers (UUIDs) and writes them to the buffer 46pointed to by 47.Fa store . 48The identifiers are generated according to the syntax and semantics of the 49DCE version 1 variant of universally unique identifiers. 50See below for a more in-depth description of the identifiers. 51When no IEEE 802 52address is available for the node field, a random multicast address is 53generated for each invocation of the system call. 54According to the algorithm of generating time-based UUIDs, this will also 55force a new random clock sequence, thereby increasing the likelihood for 56the identifier to be unique. 57.Pp 58When multiple identifiers are to be generated, the 59.Fn uuidgen 60system call will generate a set of identifiers that is dense in such a way 61that there is no identifier that is larger than the smallest identifier in the 62set and smaller than the largest identifier in the set and that is not already 63in the set. 64.Pp 65Universally unique identifiers, also known as globally unique identifiers 66(GUIDs), have a binary representation of 128-bits. 67The grouping and meaning of these bits is described by the following 68structure and its description of the fields that follow it: 69.Bd -literal 70struct uuid { 71 uint32_t time_low; 72 uint16_t time_mid; 73 uint16_t time_hi_and_version; 74 uint8_t clock_seq_hi_and_reserved; 75 uint8_t clock_seq_low; 76 uint8_t node[_UUID_NODE_LEN]; 77}; 78.Ed 79.Bl -tag -width ".Va clock_seq_hi_and_reserved" 80.It Va time_low 81The least significant 32 bits of a 60-bit timestamp. 82This field is stored in the native byte-order. 83.It Va time_mid 84The least significant 16 bits of the most significant 28 bits of the 60-bit 85timestamp. 86This field is stored in the native byte-order. 87.It Va time_hi_and_version 88The most significant 12 bits of the 60-bit timestamp multiplexed with a 4-bit 89version number. 90The version number is stored in the most significant 4 bits of the 16-bit 91field. 92This field is stored in the native byte-order. 93.It Va clock_seq_hi_and_reserved 94The most significant 6 bits of a 14-bit sequence number multiplexed with a 952-bit variant value. 96Note that the width of the variant value is determined by the variant itself. 97Identifiers generated by the 98.Fn uuidgen 99system call have variant value 10b. 100the variant value is stored in the most significant bits of the field. 101.It Va clock_seq_low 102The least significant 8 bits of a 14-bit sequence number. 103.It Va node 104The 6-byte IEEE 802 (MAC) address of one of the interfaces of the node. 105If no such interface exists, a random multi-cast address is used instead. 106.El 107.Pp 108The binary representation is sensitive to byte ordering. 109Any multi-byte field is to be stored in the local or native byte-order and 110identifiers must be converted when transmitted to hosts that do not agree 111on the byte-order. 112The specification does not however document what this means in concrete 113terms and is otherwise beyond the scope of this system call. 114.Sh RETURN VALUES 115.Rv -std 116.Sh ERRORS 117The 118.Fn uuidgen 119system call can fail with: 120.Bl -tag -width Er 121.It Bq Er EFAULT 122The buffer pointed to by 123.Fa store 124could not be written to for any or all identifiers. 125.It Bq Er EINVAL 126The 127.Fa count 128argument is less than 1 or larger than the hard upper limit of 2048. 129.El 130.Sh SEE ALSO 131.Xr uuidgen 1 , 132.Xr uuid 3 133.Sh STANDARDS 134The identifiers are represented and generated in conformance with the DCE 1.1 135RPC specification. 136The 137.Fn uuidgen 138system call is itself not part of the specification. 139.Sh HISTORY 140The 141.Fn uuidgen 142system call first appeared in 143.Fx 5.0 . 144