<?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, <function>tempnam</function> may
   generate a file in the system's temporary directory, and return
   the name of that.
  </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, 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.6</entry>
       <entry>
        Prior to PHP 4.0.6, the behaviour of the
        <function>tempnam</function> function was system dependent. On
        Windows the <varname>TMP</varname> environment variable will override the
        <parameter>dir</parameter> parameter, on Linux the <varname>TMPDIR</varname>
        environment variable has precedence, while SVR4 will always use
        your <parameter>dir</parameter> parameter if the directory it
        points to exists. Consult your system documentation on the
        tempnam(3) function if in doubt.
       </entry>
      </row>
      <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
-->