<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.uniqid" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>uniqid</refname>
  <refpurpose>Generate a unique ID</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>uniqid</methodname>
   <methodparam choice="opt"><type>string</type><parameter>prefix</parameter><initializer>""</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>more_entropy</parameter><initializer>&false;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Gets a prefixed unique identifier based on the current time in
   microseconds.
  </para>
  &caution.cryptographically-insecure;
  <warning>
    <para>
     This function does not guarantee uniqueness of return
     value. Since most systems adjust system clock by NTP or like,
     system time is changed constantly. Therefore, it is possible that
     this function does not return unique ID for the
     process/thread. Use <parameter>more_entropy</parameter> to
     increase likelihood of uniqueness.
    </para>
  </warning>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>prefix</parameter></term>
     <listitem>
      <para>
       Can be useful, for instance, if you generate identifiers
       simultaneously on several hosts that might happen to generate the
       identifier at the same microsecond.
      </para>
      <para>
       With an empty <parameter>prefix</parameter>, the returned string will
       be 13 characters long.  If <parameter>more_entropy</parameter> is
       &true;, it will be 23 characters.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>more_entropy</parameter></term>
     <listitem>
      <para>
       If set to &true;, <function>uniqid</function> will add additional
       entropy (using the combined linear congruential generator) at the end
       of the return value, which increases the likelihood that the result
       will be unique.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns timestamp based unique identifier as a string.
  </para>
  <warning>
   <para>
     This function tries to create unique identifier, but it does not
     guarantee 100% uniqueness of return value.
   </para>
  </warning>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>uniqid</function> Example</title>
    <programlisting role="php">
<![CDATA[
<?php
/* A uniqid, like: 4b3403665fea6 */
printf("uniqid(): %s\r\n", uniqid());

/* We can also prefix the uniqid, this the same as 
 * doing:
 *
 * $uniqid = $prefix . uniqid();
 * $uniqid = uniqid($prefix);
 */
printf("uniqid('php_'): %s\r\n", uniqid('php_'));

/* We can also activate the more_entropy parameter, which is 
 * required on some systems, like Cygwin. This makes uniqid()
 * produce a value like: 4b340550242239.64159797
 */
printf("uniqid('', true): %s\r\n", uniqid('', true));
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Under Cygwin, the <parameter>more_entropy</parameter> must be set 
    to &true; for this function to work.
   </para>
  </note>

 </refsect1>
 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><function>random_bytes</function></member>
  </simplelist>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
