> For the complete documentation index, see [llms.txt](https://man.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://man.bsdcn.org/sys/uuidgen.2.md).

# uuidgen(2)

`uuidgen` — 生成通用唯一标识符

## 名称

`uuidgen`

## 库

Lb libc

## 概要

`#include <sys/uuid.h>`

```c
int
uuidgen(struct uuid *store, int count);
```

## 描述

`uuidgen()` 系统调用生成 `count` 个通用唯一标识符（UUID），并将其写入由 `store` 所指向的缓冲区。这些标识符按照 DCE 版本 1 变体的通用唯一标识符的语法和语义生成。有关标识符的更详细描述，请参见下文。当节点字段没有可用的 IEEE 802 地址时，系统调用每次调用都会生成一个随机的多播地址。根据生成基于时间的 UUID 的算法，这也会强制生成一个新的随机时钟序列，从而增加标识符唯一的可能性。

当需要生成多个标识符时，`uuidgen()` 系统调用会生成一组密集的标识符，即在该集合的最小标识符和最大标识符之间不存在尚未包含在集合中的标识符。

通用唯一标识符，也称为全局唯一标识符（GUID），具有 128 位的二进制表示形式。这些位的分组和含义由以下结构及其后随字段的描述来说明：

```c
struct uuid {
	uint32_t	time_low;
	uint16_t	time_mid;
	uint16_t	time_hi_and_version;
	uint8_t		clock_seq_hi_and_reserved;
	uint8_t		clock_seq_low;
	uint8_t		node[_UUID_NODE_LEN];
};
```

**`time_low`** 60 位时间戳的低 32 位。此字段以本机字节序存储。

**`time_mid`** 60 位时间戳中高 28 位的低 16 位。此字段以本机字节序存储。

**`time_hi_and_version`** 60 位时间戳的高 12 位，与 4 位版本号多路复用。版本号存储在该 16 位字段的高 4 位中。此字段以本机字节序存储。

**`clock_seq_hi_and_reserved`** 14 位序列号的高 6 位，与 2 位变体值多路复用。注意，变体值的宽度由变体本身决定。`uuidgen()` 系统调用生成的标识符变体值为 10b。变体值存储在该字段的高位。

**`clock_seq_low`** 14 位序列号的低 8 位。

**`node`** 节点某个接口的 6 字节 IEEE 802（MAC）地址。如果不存在这样的接口，则使用随机的多播地址代替。

二进制表示对字节序敏感。任何多字节字段都应以本机字节序存储，并且在传输到字节序不一致的主机时必须进行转换。然而，规范并未以具体术语说明其含义，且超出本系统调用的讨论范围。

## 返回值

成功完成时返回值 0；否则返回值 -1，并设置全局变量 `errno` 以指示错误。

## 错误

`uuidgen()` 系统调用可能因以下原因失败：

**\[`EFAULT`]** `store` 所指向的缓冲区无法写入任何一个或所有标识符。

**\[`EINVAL`]** `count` 参数小于 1 或大于硬上限 2048。

## 参见

[uuidgen(1)](/man1/uuidgen.1.md), [uuid(3)](/uuid/uuid.3.md)

## 标准

这些标识符的表示和生成符合 DCE 1.1 RPC 规范。`uuidgen()` 系统调用本身不属于该规范的一部分。

## 历史

`uuidgen()` 系统调用首次出现于 FreeBSD 5.0。