<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.tempnam">
 <refnamediv>
  <refname>tempnam</refname>
  <refpurpose>Create file with unique file name</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>tempnam</methodname>
   <methodparam><type>string</type><parameter>dir</parameter></methodparam>
   <methodparam><type>string</type><parameter>prefix</parameter></methodparam>
  </methodsynopsis>
  <para>
   Creates a file with a unique filename, with access permission set to 0600, in the specified directory.
   If the directory does not exist or is not writable, <function>tempnam</function> may
   generate a file in the system's temporary directory, and return
   the full path to that file, including its name.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>dir</parameter></term>
     <listitem>
      <para>
       The directory where the temporary filename will be created.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>prefix</parameter></term>
     <listitem>
      <para>
       The prefix of the generated temporary filename.
      </para>
      <note>
       <simpara>
        Windows uses only the first three characters of prefix.
       </simpara>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the new temporary filename (with path), or &false; on
   failure.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>4.0.3</entry>
       <entry>
        This function's behavior changed in 4.0.3. The temporary file is also
        created to avoid a race condition where the file might appear in the
        filesystem between the time the string was generated and before
        the script gets around to creating the file. Note, that you need
        to remove the file in case you need it no more, it is not done
        automatically.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>tempnam</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$tmpfname = tempnam("/tmp", "FOO");

$handle = fopen($tmpfname, "w");
fwrite($handle, "writing to tempfile");
fclose($handle);

// do here something

unlink($tmpfname);
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <simpara>
    If PHP cannot create a file in the specified <parameter>dir</parameter>
    parameter, it falls back on the system default. On NTFS this also happens
    if the specified <parameter>dir</parameter> contains more than 65534 files.
   </simpara>
  </note>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>tmpfile</function></member>
    <member><function>sys_get_temp_dir</function></member>
    <member><function>unlink</function></member>
   </simplelist>
  </para>
 </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
-->