===============
uuid-ossp
===============


.. container:: sect1
   :name: UUID-OSSP

   .. container:: titlepage

      .. container::

         .. container::

            .. rubric:: uuid-ossp
               :name: uuid-ossp
               :class: title

   .. container:: toc


   ``uuid-ossp``\ 模块提供函数使用几种标准算法之一产生通用唯一标识符（UUID）。还提供产生某些特殊
   UUID 常量的函数。

   .. container:: sect2
      :name: id-1.11.7.53.4

      .. container:: titlepage

         .. container::

            .. container::

               .. rubric:: ``uuid-ossp`` 函数
                  :name: uuid-ossp-函数
                  :class: title

      `用于 UUID 产生的函数 <uuid-ossp.html#UUID-OSSP-FUNCTIONS>`__\ 展示了可用来产生
      UUID 的函数。相关标准 ITU-T Rec. X.667、ISO/IEC 9834-8:2005 以及
      RFC 4122 指定了四种用于产生 UUID 的算法，分别用版本号 1、3、4、5
      标识（没有版本 2
      的算法）。这些算法中的每一个都适合于不同的应用集合。

      .. container:: table
         :name: UUID-OSSP-FUNCTIONS

         **用于 UUID 产生的函数**

         .. container:: table-contents

            +----------------------------------+----------------------------------+
            | 函数                             | 描述                             |
            +==================================+==================================+
            | ``uuid_generate_v1()``           | 这个函数产生一个版本 1 的        |
            |                                  | UUID。这涉及到计算机的 MAC       |
            |                                  | 地址和一个时间戳。注意这种 UUID  |
            |                                  | 会泄露产生该标识符的             |
            |                                  | 计算机标识以及产生的时间，因此它 |
            |                                  | 不适合某些对安全性很敏感的应用。 |
            +----------------------------------+----------------------------------+
            | ``uuid_generate_v1mc()``         | 这个函数产生一个版本 1 的        |
            |                                  | UUID，但是使用一个随机广播 MAC   |
            |                                  | 地址而不是该计算机真实的 MAC     |
            |                                  | 地址。                           |
            +----------------------------------+----------------------------------+
            | uuid_generate\                   | 这个函数使用指定的输入名         |
            | _v3(namespace uuid, name text)   | 称在给定的名字空间中产生一个版本 |
            |                                  | 3 的                             |
            |                                  | UUID。该名字空间应该             |
            |                                  | 是由\ ``uuid_ns_*()``\ 函数（如  |
            |                                  | \ `表 <uuid-ossp.html#UUID-      |
            |                                  | OSSP-CONSTANTS>`__\ 所示）产生的 |
            |                                  | 特殊常量之一（理论上它可以是任意 |
            |                                  | UUID）。名称                     |
            |                                  | 是选择的名字空间中的一个标识符。 |
            |                                  |                                  |
            |                                  | 例如：                           |
            |                                  |                                  |
            |                                  | .. code:: programlisting         |
            |                                  |                                  |
            |                                  |    SELECT                        |
            |                                  |    uuid_generate_v3(uuid_ns_url()|
            |                                  |    ,'http://www.oushudb.com');   |
            |                                  |                                  |
            |                                  | 名称参数将使用 MD5               |
            |                                  | 进行哈希，因此从产生的 UUID      |
            |                                  | 中得不到明文。采用这种方法的     |
            |                                  | UUID                             |
            |                                  | 生成没有随机性并且不涉及依赖     |
            |                                  | 于环境的元素，因此是可以重现的。 |
            +----------------------------------+----------------------------------+
            | ``uuid_generate_v4()``           | 这个函数产生一个版本 4 的        |
            |                                  | UUID，它完全从随机数产生。       |
            +----------------------------------+----------------------------------+
            | uuid_generate\                   | 这个函数产生一个版本 5 的        |
            | _v5(namespace uuid, name text)   | UUID，它和版本 3 的 UUID         |
            |                                  | 相似，但是采用的是 SHA-1         |
            |                                  | 作为哈希方法。版本 5 比版本 3    |
            |                                  | 更好，因为 SHA-1 被认为比 MD5    |
            |                                  | 更安全。                         |
            +----------------------------------+----------------------------------+

      .. container:: table
         :name: UUID-OSSP-CONSTANTS

         **返回 UUID 常量的函数**

         .. container:: table-contents

            +--------------------+------------------------------------------------+
            | ``uuid_nil()``     | 一个“nil” UUID 常量，它不作为一个真正的 UUID   |
            |                    | 发生。                                         |
            +--------------------+------------------------------------------------+
            | ``uuid_ns_dns()``  | 为 UUID 指定 DNS 名字空间的常量。              |
            +--------------------+------------------------------------------------+
            | ``uuid_ns_url()``  | 为 UUID 指定 URL 名字空间的常量。              |
            +--------------------+------------------------------------------------+
            | ``uuid_ns_oid()``  | 为 UUID 指定 ISO 对象标识符（OID）             |
            |                    | 名字空间的常量（这属于 ASN.1                   |
            |                    | OID，它与OushuDB使用的 OID 无关）。            |
            +--------------------+------------------------------------------------+
            | ``uuid_ns_x500()`` | 为 UUID 指定 X.500                             |
            |                    | 可识别名（DN）名字空间的常量。Constant         |
            |                    | designating the X.500 distinguished name (DN)  |
            |                    | namespace for UUIDs.                           |
            +--------------------+------------------------------------------------+

   .. hidden-container:: sect2
      :name: id-1.11.7.53.5

      .. container:: titlepage

         .. container::

            .. container::

               .. rubric:: 编译\ ``uuid-ossp``
                  :name: 编译uuid-ossp
                  :class: title

      在历史上这个模块依赖于 OSSP UUID
      库，这也是这个模块名称的由来。虽然
      现在还能在\ http://www.ossp.org/pkg/lib/uuid/\ 上 找到 OSSP UUID
      库，但是它已经不再被维护并且越来越难以被一直到新的平台。
      ``uuid-ossp``\ 现在在一些平台上可以脱离 OSSP 库被编译。在
      FreeBSD、NetBSD 和一些其他源自 BSD 的平台上，在核心的\ ``libc``
      库中已经包括了合适的 UUID 创建函数。在
      Linux、macOS和一些其他平台上，
      ``libuuid``\ 库中提供了合适的函数，它最初是来自于
      ``e2fsprogs``\ 项目（不过在现代 Linux 上它被认为是
      ``util-linux-ng``\ 的一部分）。在调用\ ``configure``\ 时，
      指定\ ``--with-uuid=bsd``\ 可使用 BSD 的函数，指定
      ``--with-uuid=e2fs``\ 会使用\ ``e2fsprogs``\ 的
      ``libuuid``\ ，指定\ ``--with-uuid=ossp``\ 则会 使用 OSSP UUID
      库。在一台特定的机器上可能会存在多种上述的库，因此
      ``configure``\ 不会自动选择其中一个。

      .. note::

         .. rubric:: 注意
            :name: 注意
            :class: title

         如果你只需要随机生成（版本4）的
         UUID，可以考虑使用\ `pgcrypto <pgcrypto.html>`__
         模块中的\ ``gen_random_uuid()``\ 函数。

   .. hidden-container:: sect2
      :name: id-1.11.7.53.6

      .. container:: titlepage

         .. container::

            .. container::

               .. rubric:: 作者
                  :name: 作者
                  :class: title

      Peter Eisentraut ``<peter_e@gmx.net>``