.\" Copyright (c) 2002 Marcel Moolenaar
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" %FreeBSD: src/lib/libc/sys/uuidgen.2,v 1.7 2003/06/27 13:41:29 yar Exp %
.\"
.\" $FreeBSD$
.Dd May 26, 2002
.Dt UUIDGEN 2
.Os
.Sh 名称
.Nm uuidgen
.Nd 全世界的に唯一の識別子の生成
.Sh ライブラリ
.Lb libc
.Sh 書式
.In sys/uuid.h
.Ft int
.Fn uuidgen "struct uuid *store" "int count"
.Sh 解説
.Fn uuidgen
システムコールは
.Fa count
個の全世界的に唯一の識別子 (UUID) を生成し、それらを
.Fa store
によって指されるバッファへ書込みます。
この識別子は全世界的に唯一の識別子の異形である DEC version 1 の
文法とセマンティクスに従って生成されます。
この識別子のより詳細な記述は下記を参照してください。
利用可能な node フィールドのための IEEE 802 アドレスが無い場合には、
個々のシステムコールの呼び出し毎に、ランダムなマルチキャストアドレスが
生成されます。
時間基準の UUID の生成のアルゴリズムに従って、
新しいランダムクロックシーケンスを強制します。
それによって、識別子が唯一である可能性が増します。
.Pp
複数の識別子が生成されなければならない時には、
.Fn uuidgen
システムコールは、密度の濃い識別子の集合を生成します。
これの意味するところは、
集合の中で最小の識別子よりも大きくかつ、
集合の中で最大の識別子よりも小さくかつ、
集合の中にまだ存在していないという条件の識別子が存在しないということです。
.Pp
地球規模に唯一の識別子 (GUID) としても知られる全世界的に唯一の識別子は、
128 ビットのバイナリ表現を持っています。
これらのビットの分類と意味は以下の構造体によって記述され、
そのフィールドの説明が続きます:
.Bd -literal
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];
};
.Ed
.Bl -tag -width ".Va clock_seq_hi_and_reserved"
.It Va time_low
60 ビットのタイムスタンプの下位の 32 ビットです。
このフィールドはネイティブのバイトオーダで格納されます。
.It Va time_mid
60 ビットのタイムスタンプの上位 28 ビットのうちの下位の 16 ビットです。
このフィールドはネイティブのバイトオーダで格納されます。
.It Va time_hi_and_version
60 ビットのタイムスタンプの上位 12 ビットと 4 ビットのバージョン番号の
複合されたものです。
バージョン番号は 16 ビットのフィールドの上位 4 ビットに格納されます。
このフィールドはネイティブのバイトオーダで格納されます。
.It Va clock_seq_hi_and_reserved
14 ビットのシーケンス番号の上位 6 ビットと 2 ビットのバリアント値の
複合されたものです。
バリアント値の幅はそのバリアントによって決定されることに注意してください。
.Fn uuidgen
システムコールによって生成される識別子が持つバリアント値は 10b です。
バリアント値はこのフィールドの上位ビットに格納されます。
.It Va clock_seq_low
14 ビットのシーケンス番号の下位 8 ビットです。
.It Va node
そのノードのインタフェースの 1 つの 6 バイトの IEEE 802 (MAC) アドレスです。
そのようなインタフェースが存在しない場合には、ランダムなマルチキャスト
アドレスが代わりに使用されます。
.El
.Pp
バイナリ表現はバイトオーダに対して敏感です。
あらゆるマルチバイトのフィールドは、ローカルまたはネイティブのバイトオーダで
格納されなければならず、また識別子はそのバイトオーダに同意しない
ホストに対して送信されるときに、変換されなければなりません。
しかしながら、この仕様は具体的な用語で文書化されていません。また、
その他の点ではこのシステムコールの範囲を超えています。
.Sh 戻り値
.Rv -std
.Sh エラー
.Fn uuidgen
システムコールは失敗することがあります:
.Bl -tag -width Er
.It Bq Er EFAULT
.Fa store
によって指されるバッファに、どれか 1 つのまたは全ての識別子を書き込めません。
.It Bq Er EINVAL
.Fa count
引数が 1 よりも小さい、またはハード上限の 2048 よりも大きいです。
.El
.Sh 関連項目
.Xr uuidgen 1 ,
.Xr uuid 3
.Sh 規格
この識別子は DCE 1.1 RPC の仕様に適合して表現され、生成されます。
.Fn uuidgen
システムコールそれ自身は仕様の一部ではありません。
.Sh 歴史
.Fn uuidgen
システムコールは
.Fx 5.0
ではじめて登場しました。