diff options
Diffstat (limited to 'doc/src/sgml/uuid-ossp.sgml')
| -rw-r--r-- | doc/src/sgml/uuid-ossp.sgml | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml new file mode 100644 index 0000000..26bfb90 --- /dev/null +++ b/doc/src/sgml/uuid-ossp.sgml @@ -0,0 +1,242 @@ +<!-- doc/src/sgml/uuid-ossp.sgml --> + +<sect1 id="uuid-ossp" xreflabel="uuid-ossp"> + <title>uuid-ossp</title> + + <indexterm zone="uuid-ossp"> + <primary>uuid-ossp</primary> + </indexterm> + + <para> + The <filename>uuid-ossp</filename> module provides functions to generate universally + unique identifiers (UUIDs) using one of several standard algorithms. There + are also functions to produce certain special UUID constants. + This module is only necessary for special requirements beyond what is + available in core <productname>PostgreSQL</productname>. See <xref + linkend="functions-uuid"/> for built-in ways to generate UUIDs. + </para> + + <para> + This module is considered <quote>trusted</quote>, that is, it can be + installed by non-superusers who have <literal>CREATE</literal> privilege + on the current database. + </para> + + <sect2> + <title><literal>uuid-ossp</literal> Functions</title> + + <para> + <xref linkend="uuid-ossp-functions"/> shows the functions available to + generate UUIDs. + The relevant standards ITU-T Rec. X.667, ISO/IEC 9834-8:2005, and + <ulink url="https://tools.ietf.org/html/rfc4122">RFC 4122</ulink> + specify four algorithms for generating UUIDs, identified by the + version numbers 1, 3, 4, and 5. (There is no version 2 algorithm.) + Each of these algorithms could be suitable for a different set of + applications. + </para> + + <table id="uuid-ossp-functions"> + <title>Functions for UUID Generation</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="func_table_entry"><para role="func_signature"> + Function + </para> + <para> + Description + </para></entry> + </row> + </thead> + + <tbody> + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm><primary>uuid_generate_v1</primary></indexterm> + <function>uuid_generate_v1</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Generates a version 1 UUID. This involves the MAC + address of the computer and a time stamp. Note that UUIDs of this + kind reveal the identity of the computer that created the identifier + and the time at which it did so, which might make it unsuitable for + certain security-sensitive applications. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm><primary>uuid_generate_v1mc</primary></indexterm> + <function>uuid_generate_v1mc</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Generates a version 1 UUID, but uses a random multicast + MAC address instead of the real MAC address of the computer. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm><primary>uuid_generate_v3</primary></indexterm> + <function>uuid_generate_v3</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> ) + <returnvalue>uuid</returnvalue> + </para> + <para> + Generates a version 3 UUID in the given namespace using + the specified input name. The namespace should be one of the special + constants produced by the <function>uuid_ns_*()</function> functions + shown in <xref linkend="uuid-ossp-constants"/>. (It could be any UUID + in theory.) The name is an identifier in the selected namespace. + </para> + <para> + For example: + +<programlisting> +SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org'); +</programlisting> + + The name parameter will be MD5-hashed, so the cleartext cannot be + derived from the generated UUID. + The generation of UUIDs by this method has no random or + environment-dependent element and is therefore reproducible. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_generate_v4</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Generates a version 4 UUID, which is derived entirely + from random numbers. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_generate_v5</function> ( <parameter>namespace</parameter> <type>uuid</type>, <parameter>name</parameter> <type>text</type> ) + <returnvalue>uuid</returnvalue> + </para> + <para> + Generates a version 5 UUID, which works like a version 3 + UUID except that SHA-1 is used as a hashing method. Version 5 should + be preferred over version 3 because SHA-1 is thought to be more secure + than MD5. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + + <table id="uuid-ossp-constants"> + <title>Functions Returning UUID Constants</title> + <tgroup cols="1"> + <thead> + <row> + <entry role="func_table_entry"><para role="func_signature"> + Function + </para> + <para> + Description + </para></entry> + </row> + </thead> + + <tbody> + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_nil</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Returns a <quote>nil</quote> UUID constant, which does not occur as a + real UUID. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_ns_dns</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Returns a constant designating the DNS namespace for UUIDs. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_ns_url</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Returns a constant designating the URL namespace for UUIDs. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_ns_oid</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Returns a constant designating the ISO object identifier (OID) namespace for + UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs + used in <productname>PostgreSQL</productname>.) + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <function>uuid_ns_x500</function> () + <returnvalue>uuid</returnvalue> + </para> + <para> + Returns a constant designating the X.500 distinguished name (DN) + namespace for UUIDs. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title>Building <filename>uuid-ossp</filename></title> + + <para> + Historically this module depended on the OSSP UUID library, which accounts + for the module's name. While the OSSP UUID library can still be found + at <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>, it is not well + maintained, and is becoming increasingly difficult to port to newer + platforms. <filename>uuid-ossp</filename> can now be built without the OSSP + library on some platforms. On FreeBSD and some other BSD-derived + platforms, suitable UUID creation functions are included in the + core <filename>libc</filename> library. On Linux, macOS, and some other + platforms, suitable functions are provided in the <filename>libuuid</filename> + library, which originally came from the <literal>e2fsprogs</literal> project + (though on modern Linux it is considered part + of <literal>util-linux-ng</literal>). When invoking <filename>configure</filename>, + specify <option>--with-uuid=bsd</option> to use the BSD functions, + or <option>--with-uuid=e2fs</option> to + use <literal>e2fsprogs</literal>' <filename>libuuid</filename>, or + <option>--with-uuid=ossp</option> to use the OSSP UUID library. + More than one of these libraries might be available on a particular + machine, so <filename>configure</filename> does not automatically choose one. + </para> + </sect2> + + <sect2> + <title>Author</title> + + <para> + Peter Eisentraut <email>peter_e@gmx.net</email> + </para> + + </sect2> + +</sect1> |