php-doc-en/functions/filesystem.xml

 <reference id="ref.filesystem">
  <title>Filesystem functions</title>
  <titleabbrev>Filesystem</titleabbrev>

  <refentry id="function.basename">
   <refnamediv>
    <refname>basename</refname>
    <refpurpose>
     Return filename component of path
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>basename</function></funcdef>
     <paramdef>string <parameter>path</parameter></paramdef>
    </funcsynopsis>
    <para>
     Given a string containing a path to a file, this function will
     return the base name of the file.
    </para>
    <para>
     On Windows, both slash (<literal>/</literal>) and backslash
     (<literal>\</literal>) are used as path separator character.  In
     other environments, it is the forward slash
     (<literal>/</literal>).
    </para>
    <para>
     <example>
      <title><function>basename</function> example</title>
      <programlisting role="php">
$path = "/home/httpd/html/index.php3";
$file = basename($path); // $file is set to "index.php3"
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>dirname</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.chgrp">
   <refnamediv>
    <refname>chgrp</refname>
    <refpurpose>Change file group</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>chgrp</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>mixed <parameter>group</parameter></paramdef>
    </funcsynopsis>
    <para>
     Attempts to change the group of the file filename to group. Only
     the superuser may change the group of a file arbitrarily; other
     users may change the group of a file to any group of which that
     user is a member.
    </para>
    <para>
     Returns true on success; otherwise returns false.
    </para>
    <para>
     See also <function>chown</function> and
     <function>chmod</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.chmod">
   <refnamediv>
    <refname>chmod</refname>
    <refpurpose>Change file mode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>chmod</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>int <parameter>mode</parameter></paramdef>
    </funcsynopsis>
    <para>
     Attempts to change the mode of the file specified by
     <parameter>filename</parameter> to that given in
     <parameter>mode</parameter>.
    </para>
    <para>
     Note that <parameter>mode</parameter> is not automatically
     assumed to be an octal value. To ensure the expected operation,
     you need to prefix <parameter>mode</parameter> with a zero (0):
     <informalexample>
      <programlisting role="php">
chmod( "/somedir/somefile", 755 );   // decimal; probably incorrect       
chmod( "/somedir/somefile", 0755 );  // octal; correct value of mode
      </programlisting>
     </informalexample>
    </para>
    <para>
     Returns true on success and false otherwise.
    </para>
    <para>
     See also <function>chown</function> and
     <function>chgrp</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.chown">
   <refnamediv>
    <refname>chown</refname>
    <refpurpose>change file owner</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>chown</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>mixed <parameter>user</parameter></paramdef>
    </funcsynopsis>
    <para>
     Attempts to change the owner of the file filename to user
     user. Only the superuser may change the owner of a file.
    </para>
    <para>
     Returns true on success; otherwise returns false.
     <note>
      <simpara>On Windows, does nothing and returns true.
      </simpara>
     </note>
    </para>
    <para>
     See also <function>chown</function> and
     <function>chmod</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.clearstatcache">
   <refnamediv>
    <refname>clearstatcache</refname>
    <refpurpose>Clear file stat cache</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>clearstatcache</function></funcdef>
     <void/>
    </funcsynopsis>
    <para>
     Invoking the <systemitem>stat</systemitem> or
     <systemitem>lstat</systemitem> system call on most systems is
     quite expensive. Therefore, the result of the last call to any of
     the status functions (listed below) is stored for use on the next
     such call using the same filename. If you wish to force a new
     status check, for instance if the file is being checked many
     times and may change or disappear, use this function to clear the
     results of the last call from memory.
    </para>
    <para>
     This value is only cached for the lifetime of a single request.
    </para>
    <para>
     Affected functions include <function>stat</function>,
     <function>lstat</function>,
     <function>file_exists</function>,
     <function>is_writeable</function>,
     <function>is_readable</function>,
     <function>is_executable</function>,
     <function>is_file</function>,
     <function>is_dir</function>,
     <function>is_link</function>,
     <function>filectime</function>,
     <function>fileatime</function>,
     <function>filemtime</function>,
     <function>fileinode</function>,
     <function>filegroup</function>,
     <function>fileowner</function>,
     <function>filesize</function>,
     <function>filetype</function>, and
     <function>fileperms</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.copy">
   <refnamediv>
    <refname>copy</refname>
    <refpurpose>Copy file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>copy</function></funcdef>
     <paramdef>string <parameter>source</parameter></paramdef>
     <paramdef>string <parameter>dest</parameter></paramdef>
    </funcsynopsis>
    <para>
     Makes a copy of a file.  Returns true if the copy succeeded,
     false otherwise.
     <example>
      <title><function>copy</function> example</title>
      <programlisting role="php">
if ( !copy($file, $file.'.bak') ) {
    print("failed to copy $file...&lt;br>\n");
}
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>rename</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.delete">
   <refnamediv>
    <refname>delete</refname>
    <refpurpose>A dummy manual entry</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>void <function>delete</function></funcdef>
     <paramdef>string <parameter>file</parameter></paramdef>
    </funcsynopsis>
     <para>
      This is a dummy manual entry to satisfy those people who are
      looking for <function>unlink</function> or
      <function>unset</function> in the wrong place.</para>
     <para>
      See also: <function>unlink</function> to delete files,
      <function>unset</function> to delete variables.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dirname">
   <refnamediv>
    <refname>dirname</refname>
    <refpurpose>Return directory name component of path</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>dirname</function></funcdef>
     <paramdef>string <parameter>path</parameter></paramdef>
    </funcsynopsis>
    <para>
     Given a string containing a path to a file, this function will
     return the name of the directory.</para>
    <para>
     On Windows, both slash (<literal>/</literal>) and backslash
     (<literal>\</literal>) are used as path separator character.  In
     other environments, it is the forward slash
     (<literal>/</literal>).</para>
    <para>
     <example>
      <title><function>dirname</function> example</title>
      <programlisting role="php">
$path = "/etc/passwd";
$file = dirname($path); // $file is set to "/etc"
      </programlisting>
     </example>
    </para>
    <para>
     See also: <function>basename</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.diskfreespace">
   <refnamediv>
    <refname>diskfreespace</refname>
    <refpurpose>Return available space in directory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>float <function>diskfreespace</function></funcdef>
     <paramdef>string <parameter>directory</parameter></paramdef>
    </funcsynopsis>
    <para>
     Given a string containing a directory, this function will return
     the number of bytes available on the corresponding disk.
    </para>
    <para>
     <example>
      <title><function>diskfreespace</function> example</title>
      <programlisting role="php">
$df = diskfreespace("/"); // $df contains the number of bytes 
                          // available on "/"
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fclose">
   <refnamediv>
    <refname>fclose</refname>
    <refpurpose>Close an open file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fclose</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <para>
     The file pointed to by fp is closed.
    </para>
    <para>
     Returns true on success and false on failure.
    </para>
    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function> or
     <function>fsockopen</function>.
    </para> 
   </refsect1>
  </refentry>

  <refentry id="function.feof">
   <refnamediv>
    <refname>feof</refname>
    <refpurpose>Test for end-of-file on a file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>feof</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the file pointer is at EOF or an error occurs;
     otherwise returns false.
    </para>
    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function>,
     <function>popen</function>, or <function>fsockopen</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fgetc">
   <refnamediv>
    <refname>fgetc</refname>
    <refpurpose>Get character from file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>fgetc</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns a string containing a single character read from the
     file pointed to by fp.  Returns FALSE on EOF (as does
     <function>feof</function>).</para>
    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function>,
     <function>popen</function>, or <function>fsockopen</function>.
    </para>
    <para> 
     See also <function>fread</function>, <function>fopen</function>,
     <function>popen</function>, <function>fsockopen</function>, and
     <function>fgets</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fgetcsv">
   <refnamediv>
    <refname>fgetcsv</refname>
    <refpurpose>
     Get line from file pointer and parse for CSV fields
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>fgetcsv</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
     <paramdef>string 
      <parameter>
       <optional>delimiter</optional>
      </parameter>
     </paramdef>
    </funcsynopsis>
    <simpara>
     Similar to fgets() except that fgetcsv() parses the line it reads
     for fields in CSV format and returns an array containing the
     fields read.  The field delimiter is a comma, unless you specifiy
     another delimiter with the optional third parameter.
    </simpara>
    <simpara>
     fp must be a valid file pointer to a file successfully opened by
     <function>fopen</function>, <function>popen</function>, or
     <function>fsockopen</function>
    </simpara>
    <simpara>
     length must be greater than the longest line to be found in the
     CSV file (allowing for trailing line-end characters).
    </simpara>
    <simpara>
     fgetcsv() returns false on error, including end of file.
    </simpara>
    <simpara>
     NB A blank line in a CSV file will be returned as an array
     comprising just one single null field, and will not be treated as
     an error.
    </simpara>
    <example>
     <title>
      <function>Fgetcsv</function> example - Read and print entire
      contents of a CSV file
     </title>
     <programlisting role="php">
$row = 1;
$fp = fopen ("test.csv","r");
while ($data = fgetcsv ($fp, 1000, ",")) {
    $num = count ($data);
    print "&lt;p> $num fields in line $row: &lt;br>";
    $row++;
    for ($c=0; $c<$num; $c++) {
        print $data[$c] . "&lt;br>";
    }
}
fclose ($fp);
     </programlisting>
    </example>
   </refsect1>
  </refentry>

  <refentry id="function.fgets">
   <refnamediv>
    <refname>fgets</refname>
    <refpurpose>Get line from file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>fgets</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns a string of up to length - 1 bytes read from the file
     pointed to by fp. Reading ends when length - 1 bytes have been
     read, on a newline (which is included in the return value), or on
     EOF (whichever comes first).
    </para>
    <para>
     If an error occurs, returns false.
    </para>
    <para>
     Common Pitfalls:
    </para>
    <simpara>
     People used to the 'C' semantics of fgets should note the
     difference in how EOF is returned.
    </simpara>
    <simpara>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function>,
     <function>popen</function>, or
     <function>fsockopen</function>.
    </simpara>
    <para>
     A simple example follows:
     <example> 
      <title>Reading a file line by line</title>
      <programlisting role="php">
$fd = fopen ("/tmp/inputfile.txt", "r");
while (!feof($fd)) {
    $buffer = fgets($fd, 4096);
    echo $buffer;
}
fclose ($fd);
      </programlisting>
     </example>
    </para>
    <para> 
     See also <function>fread</function>, <function>fopen</function>,
     <function>popen</function>, <function>fgetc</function>, and
     <function>fsockopen</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fgetss">
   <refnamediv>
    <refname>fgetss</refname>
    <refpurpose>
     Get line from file pointer and strip HTML tags
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>fgetss</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
     <paramdef>string 
      <parameter>
       <optional>allowable_tags</optional>
      </parameter>
     </paramdef>
    </funcsynopsis>
    <para>
     Identical to <function>fgets</function>, except that fgetss
     attempts to strip any HTML and PHP tags from the text it
     reads.
    </para>
    <para>
     You can use the optional third parameter to specify tags which
     should not be stripped.
     <note>
      <para>
       <parameter>allowable_tags</parameter> was added in PHP 3.0.13,
       PHP4B3.
      </para> 
     </note>
    </para>
    <para>
     See also <function>fgets</function>, <function>fopen</function>,
     <function>fsockopen</function>, <function>popen</function>, and
     <function>strip_tags</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.file">
   <refnamediv>
    <refname>file</refname> 
    <refpurpose>read entire file into an array</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>file</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>int 
      <parameter><optional>use_include_path</optional></parameter>
     </paramdef>
    </funcsynopsis>

    <para> 
     Identical to <function>readfile</function>, except that
     <function>file</function> returns the file in an array. Each
     element of the array corresponds to a line in the file, with the
     newline still attached.
    </para>

    <para>
     You can use the optional second parameter and set it to "1", if
     you want to search for the file in the <link
     linkend="ini.include-path">include_path</link>, too.
    </para>

    <para>
     <informalexample>
      <programlisting>
&lt;?php
// get a web page into an array and print it out
$fcontents = file( 'http://www.php.net' );
while ( list( $line_num, $line ) = each( $fcontents ) ) {
   echo "&lt;b&gt;Line $line_num:&lt;/b&gt; " . htmlspecialchars( $line ) . "&lt;br&gt;\n";
}

// get a web page into a string
$fcontents = join( '', file( 'http://www.php.net' ) );
?&gt;
      </programlisting>
     </informalexample>
    </para>

    <para> 
     See also <function>readfile</function>,
     <function>fopen</function>, and <function>popen</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.file-exists">
   <refnamediv>
    <refname>file_exists</refname>
    <refpurpose>Check whether a file exists</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>file_exists</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>

    <simpara>
     Returns true if the file specified by
     <parameter>filename</parameter> exists; false otherwise.
    </simpara>

    <simpara>
     <function>file_exists</function> will not work on remote files;
     the file to be examined must be accessible via the server's
     filesystem.
    </simpara>

    <simpara>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </simpara>

   </refsect1>
  </refentry>


  <refentry id="function.fileatime">
   <refnamediv>
    <refname>fileatime</refname>
    <refpurpose>Get last access time of file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fileatime</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>

    <simpara> 
     Returns the time the file was last accessed, or false in case of
     an error. The time is returned as a Unix timestamp.
    </simpara>

    <simpara>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </simpara>

   </refsect1>
  </refentry>


  <refentry id="function.filectime">
   <refnamediv>
    <refname>filectime</refname>
    <refpurpose>Get inode change time of file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>filectime</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the time the file was last changed, or false in case of
     an error. The time is returned as a Unix timestamp.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.filegroup">
   <refnamediv>
    <refname>filegroup</refname>
    <refpurpose>Get file group</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>filegroup</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>    
     Returns the group ID of the owner of the file, or false in case
     of an error. The group ID is returned in numerical format, use
     <function>posix_getgrgid</function> to resolve it to a group name.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.fileinode">
   <refnamediv>
    <refname>fileinode</refname>
    <refpurpose>Get file inode</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fileinode</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns the inode number of the file, or false in case of an
     error.</para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.filemtime">
   <refnamediv>
    <refname>filemtime</refname>
    <refpurpose>Get file modification time</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>filemtime</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the time the file was last modified, or false in case of
     an error. The time is returned as a Unix timestamp.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fileowner">
   <refnamediv>
    <refname>fileowner</refname>
    <refpurpose>Get file owner</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fileowner</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>    
     Returns the user ID of the owner of the file, or false in case of
     an error. The user ID is returned in numerical format, use
     <function>posix_getpwuid</function> to resolve it to a username.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.fileperms">
   <refnamediv>
    <refname>fileperms</refname>
    <refpurpose>Get file permissions</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fileperms</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>    
     Returns the permissions on the file, or false in case of an error.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.filesize">
   <refnamediv>
    <refname>filesize</refname>
    <refpurpose>Get file size</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>filesize</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Returns the size of the file, or false in case of an error.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.filetype">
   <refnamediv>
    <refname>filetype</refname>
    <refpurpose>Get file type</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>filetype</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>    
     Returns the type of the file. Possible values are fifo, char,
     dir, block, link, file, and unknown.</para> <para> Returns false
     if an error occurs.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.flock">
   <refnamediv>
    <refname>flock</refname>
    <refpurpose>Portable advisory file locking</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>flock</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>operation</parameter></paramdef>
    </funcsynopsis>
    <simpara>
     PHP supports a portable way of locking complete files in an
     advisory way (which means all accessing programs have to use the
     same way of locking or it will not work).
    </simpara>
    <simpara>
     <function>flock</function> operates on <parameter>fp</parameter>
     which must be an open file
     pointer. <parameter>operation</parameter> is one of the following
     values:
    </simpara>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
	To acquire a shared lock (reader), set
	<parameter>operation</parameter> to 1.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	To acquire an exclusive lock (writer), set
	<parameter>operation</parameter> to 2.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	To release a lock (shared or exclusive), set
	<parameter>operation</parameter> to 3.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	If you don't want <function>flock</function> to block while
	locking, add 4 to <parameter>operation</parameter>.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <simpara>
     <function>flock</function> allows you to perform a simple
     reader/writer model which can be used on virtually every platform
     (including most Unices and even Windows).
    </simpara>
    <simpara>
     <function>flock</function> returns true on success and false on
     error (e.g. when a lock could not be acquired).
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.fopen">
   <refnamediv>
    <refname>fopen</refname>
    <refpurpose>Open file or URL</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fopen</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>string <parameter>mode</parameter></paramdef>
     <paramdef>int 
      <parameter>
       <optional>use_include_path</optional>
      </parameter>
     </paramdef>
    </funcsynopsis>
    <simpara>
     If <parameter>filename</parameter> begins with "http://" (not
     case sensitive), an HTTP 1.0 connection is opened to the
     specified server and a file pointer is returned to the beginning
     of the text of the response.
    </simpara>
    <simpara>
     Does not handle HTTP redirects, so you must include trailing
     slashes on directories.
    </simpara>
    <simpara>
     If <parameter>filename</parameter> begins with "ftp://" (not case
     sensitive), an ftp connection to the specified server is opened
     and a pointer to the requested file is returned. If the server
     does not support passive mode ftp, this will fail. You can open
     files for either reading and writing via ftp (but not both
     simultaneously).
    </simpara>
    <simpara>
     If <parameter>filename</parameter> is one of "php://stdin",
     "php://stdout", or "php://stderr", the corresponding stdio
     stream will be opened.  (This was introduced in PHP 3.0.13;
     in earlier versions, a filename such as "/dev/stdin" or
     "/dev/fd/0" must be used to access the stdio streams.)
    </simpara>
    <simpara>
     If <parameter>filename</parameter> begins with anything else, the
     file will be opened from the filesystem, and a file pointer to
     the file opened is returned.
    </simpara>
    <simpara>
     If the open fails, the function returns false.
    </simpara>
    <para>
     <parameter>mode</parameter> may be any of the following:
     <itemizedlist>
      <listitem>
       <simpara>
	'r' - Open for reading only; place the file pointer at the
	beginning of the file.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	'r+' - Open for reading and writing; place the file pointer at
	the beginning of the file.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	'w' - Open for writing only; place the file pointer at the
	beginning of the file and truncate the file to zero length.
	If the file does not exist, attempt to create it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	'w+' - Open for reading and writing; place the file pointer at
	the beginning of the file and truncate the file to zero
	length.  If the file does not exist, attempt to create it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	'a' - Open for writing only; place the file pointer at the end
	of the file. If the file does not exist, attempt to create
	it.
       </simpara>
      </listitem>
      <listitem>
       <simpara>
	'a+' - Open for reading and writing; place the file pointer at
	the end of the file. If the file does not exist, attempt to
	create it.
       </simpara>
      </listitem>
     </itemizedlist>
     As well, <parameter>mode</parameter> may contain the letter
     'b'. This is useful only on systems which differentiate between
     binary and text files (i.e., it's useless on Unix). If not
     needed, this will be ignored.
    </para>
    <para>
     You can use the optional third parameter and set it to "1", if
     you want to search for the file in the <link
     linkend="ini.include-path">include_path</link>, too.
    </para>
    <para>
     <example>
      <title>fopen() example</title>
      <programlisting role="php">
$fp = fopen("/home/rasmus/file.txt", "r");
$fp = fopen("http://www.php.net/", "r");
$fp = fopen("ftp://user:password@example.com/", "w");
      </programlisting>
     </example>
    </para>
    <simpara>
     If you are experiencing problems with reading and writing to
     files and you're using the server module version of PHP, remember
     to make sure that the files and directories you're using are
     accessible to the server process.
    </simpara>
    <para>
     On the Windows platform, be careful to escape any backslashes
     used in the path to the file, or use forward slashes.
     <informalexample>
      <programlisting role="php"> 
$fp = fopen("c:\\data\\info.txt", "r");
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     See also <function>fclose</function>,
     <function>fsockopen</function>, and <function>popen</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.fpassthru">
   <refnamediv>
    <refname>fpassthru</refname> 
    <refpurpose>
     Output all remaining data on a file pointer
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fpassthru</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <simpara>
     Reads to EOF on the given file pointer and writes the results to
     standard output.
    </simpara>
    <simpara>
     If an error occurs, <function>fpassthru</function> returns
     false.
    </simpara>
    <simpara>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function>,
     <function>popen</function>, or <function>fsockopen</function>.
     The file is closed when <function>fpassthru</function> is done
     reading it (leaving <parameter>fp</parameter> useless).
    </simpara>
    <simpara>
     If you just want to dump the contents of a file to stdout you may
     want to use the <function>readfile</function>, which saves you
     the <function>fopen</function> call.
    </simpara>
    <simpara>
     See also <function>readfile</function>,
     <function>fopen</function>, <function>popen</function>, and
     <function>fsockopen</function>
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.fputs">
   <refnamediv>
    <refname>fputs</refname>
    <refpurpose>Write to a file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fputs</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>string <parameter>str</parameter></paramdef>
     <paramdef>int 
      <parameter>
       <optional>length</optional>
      </parameter>
     </paramdef>
    </funcsynopsis>
    <para>
     <function>fputs</function> is an alias to
     <function>fwrite</function>, and is identical in every way.  Note
     that the <parameter>length</parameter> parameter is optional and
     if not specified the entire string will be written.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fread">
   <refnamediv>
    <refname>fread</refname>
    <refpurpose>Binary-safe file read</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>fread</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>length</parameter></paramdef>
    </funcsynopsis>
    <simpara>
     <function>fread</function> reads up to
     <parameter>length</parameter> bytes from the file pointer
     referenced by <parameter>fp</parameter>. Reading stops when
     <parameter>length</parameter> bytes have been read or EOF is
     reached, whichever comes first.
    </simpara> 
    <para>
     <informalexample>
      <programlisting role="php">
// get contents of a file into a string
$filename = "/usr/local/something.txt";
$fd = fopen ($filename, "r");
$contents = fread ($fd, filesize ($filename));
fclose ($fd);
      </programlisting>
     </informalexample>
    </para>
    <simpara>
     See also <function>fwrite</function>, <function>fopen</function>,
     <function>fsockopen</function>, <function>popen</function>,
     <function>fgets</function>, <function>fgetss</function>,
     <function>file</function>, and <function>fpassthru</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.fseek">
   <refnamediv>
    <refname>fseek</refname>
    <refpurpose>Seek on a file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fseek</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>offset</parameter></paramdef>
     <paramdef>int <parameter><optional>whence</optional></parameter></paramdef>
    </funcsynopsis>
    <para>
     Sets the file position indicator for the file referenced by
     <parameter>fp</parameter>.The new position, measured in bytes
     from the beginning of the file, is obtained by adding
     <parameter>offset</parameter> to the position specified by
     <parameter>whence</parameter>, whose values are defined as
     follows:
     <simplelist>
      <member>SEEK_SET - Set position equal to
      <parameter>offset</parameter> bytes.</member> <member>SEEK_CUR -
      Set position to current location plus
      <parameter>offset</parameter>.</member> <member>SEEK_END - Set
      position to end-of-file plus
      <parameter>offset</parameter>.</member>
     </simplelist>
    </para>
    <para>If <parameter>whence is not specified, it is assumed to be
    SEEK_SET.</parameter>
    </para>
    <para>
     Upon success, returns 0; otherwise, returns -1. Note that seeking
     past EOF is not considered an error.
    </para>
    <para>
     May not be used on file pointers returned by
     <function>fopen</function> if they use the "http://" or "ftp://"
     formats.
    </para>
    <note>
      <para>
      The <parameter>whence</parameter> argument was added after PHP 4.0 RC1.
      </para>
     </note>
    <para>
     See also <function>ftell</function> and
     <function>rewind</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ftell">
   <refnamediv>
    <refname>ftell</refname>
    <refpurpose>Tell file pointer read/write position</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>ftell</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns the position of the file pointer referenced by fp; i.e.,
     its offset into the file stream.
    </para>
    <para>
     If an error occurs, returns false.
    </para>
    <para>
     The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function> or
     <function>popen</function>.
    </para>
    <para> 
     See also <function>fopen</function>, <function>popen</function>,
     <function>fseek</function> and <function>rewind</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.ftruncate">
   <refnamediv>
    <refname>ftruncate</refname>
    <refpurpose>
     Truncate a file to a given length.
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>ftruncate</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>size</parameter></paramdef>
    </funcsynopsis>
    <para>
     Takes the filepointer, fp, and truncates the file to length, size.
     This function returns true on success and false on failure.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.fwrite">
   <refnamediv>
    <refname>fwrite</refname>
    <refpurpose>Binary-safe file write</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fwrite</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>string <parameter>string</parameter></paramdef>
     <paramdef>int 
      <parameter>
       <optional>length</optional>
      </parameter>
     </paramdef>
    </funcsynopsis>
    <simpara>
     <function>fwrite</function> writes the contents of
     <parameter>string</parameter> to the file stream pointed to by
     <parameter>fp</parameter>. If the <parameter>length</parameter>
     argument is given, writing will stop after
     <parameter>length</parameter> bytes have been written or the end
     of <parameter>string</parameter> is reached, whichever comes
     first.
    </simpara>
    <simpara>
     Note that if the <parameter>length</parameter> argument is given,
     then the <link
     linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
     configuration option will be ignored and no slashes will be
     stripped from <parameter>string</parameter>.
    </simpara>
    <simpara>
     See also <function>fread</function>, <function>fopen</function>,
     <function>fsockopen</function>, <function>popen</function>, and
     <function>fputs</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.set-file-buffer">
   <refnamediv>
    <refname>set_file_buffer</refname>
    <refpurpose>
     Sets file buffering on the given file pointer
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>fwrite</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
     <paramdef>int <parameter>buffer</parameter></paramdef>
    </funcsynopsis>
    <simpara>
     <function>set_file_buffer</function> sets the buffering for write
     operations on the given filepointer <parameter>fp</parameter> to
     <parameter>buffer</parameter> bytes.  If
     <parameter>buffer</parameter> is 0 then write operations are
     unbuffered.
    </simpara>
    <simpara>
     The function returns 0 on success, or EOF if the request cannot
     be honored.
    </simpara>
    <simpara>
     Note that the default for any fopen with calling set_file_buffer
     is 8K.
    </simpara>
    <simpara>
     See also <function>fopen</function>.
    </simpara>
   </refsect1>
  </refentry>

  <refentry id="function.is-dir">
   <refnamediv>
    <refname>is_dir</refname>
    <refpurpose>Tells whether the filename is a directory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>is_dir</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the filename exists and is a directory.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <para>
     See also <function>is_file</function> and
     <function>is_link</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-executable">
   <refnamediv>
    <refname>is_executable</refname>
    <refpurpose>Tells whether the filename is executable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>is_executable</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the filename exists and is executable.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <para>
     See also <function>is_file</function> and
     <function>is_link</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-file">
   <refnamediv>
    <refname>is_file</refname>
    <refpurpose>
     Tells whether the filename is a regular file
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>is_file</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the filename exists and is a regular file.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <para>
     See also <function>is_dir</function> and
     <function>is_link</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-link">
   <refnamediv>
    <refname>is_link</refname>
    <refpurpose>
     Tells whether the filename is a symbolic link
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>is_link</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the filename exists and is a symbolic link.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <para>
     See also <function>is_dir</function> and
     <function>is_file</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.is-readable">
   <refnamediv>
    <refname>is_readable</refname>
    <refpurpose>
     Tells whether the filename is readable
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>is_readable</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the filename exists and is readable.
    </para>
    <para>
     Keep in mind that PHP may be accessing the file as the user
     id that the web server runs as (often 'nobody'). Safe mode
     limitations are not taken into account.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <para>
     See also <function>is_writeable</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.is-writeable">
   <refnamediv>
    <refname>is_writeable</refname>
    <refpurpose>Tells whether the filename is writeable</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>bool <function>is_writeable</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Returns true if the filename exists and is writeable.  The
     filename argument may be a directory name allowing you to check
     if a directory is writeable.
    </para>
    <para>
     Keep in mind that PHP may be accessing the file as the user id
     that the web server runs as (often 'nobody'). Safe mode
     limitations are not taken into account.
    </para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
    <para>
     See also <function>is_readable</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.link">
   <refnamediv>
    <refname>link</refname>
    <refpurpose>Create a hard link</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>link</function></funcdef>
     <paramdef>string <parameter>target</parameter></paramdef>
     <paramdef>string <parameter>link</parameter></paramdef>
    </funcsynopsis>
    <para>
    <function>Link</function> creates a hard link.</para>
    <para>
     See also the <function>symlink</function> to create soft links,
     and <function>readlink</function> along with
     <function>linkinfo</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.linkinfo">
   <refnamediv>
    <refname>linkinfo</refname>
    <refpurpose>Get information about a link</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>linkinfo</function></funcdef>
     <paramdef>string <parameter>path</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>Linkinfo</function> returns the st_dev field of the
     UNIX C stat structure returned by the lstat system call.  This
     function is used to verify if a link (pointed to by
     <parameter>path</parameter>) really exists (using the same method
     as the S_ISLNK macro defined in stat.h).  Returns 0 or FALSE in
     case of error.
    </para>
    <para>
     See also <function>symlink</function>, <function>link</function>,
     and <function>readlink</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.mkdir">
   <refnamediv>
    <refname>mkdir</refname>
    <refpurpose>Make directory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>mkdir</function></funcdef>
     <paramdef>string <parameter>pathname</parameter></paramdef>
     <paramdef>int <parameter>mode</parameter></paramdef>
    </funcsynopsis>
    <para>
     Attempts to create the directory specified by pathname.
    </para>
    <para>
     Note that you probably want to specify the mode as an
     octal number, which means it should have a leading zero.
     <informalexample>
      <programlisting role="php">
mkdir ("/path/to/my/dir", 0700);
      </programlisting>
     </informalexample>
    </para>
    <para>
     Returns true on success and false on failure.
    </para>
    <para>
     See also <function>rmdir</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.pclose">
   <refnamediv>
    <refname>pclose</refname>
    <refpurpose>Close process file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>pclose</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Closes a file pointer to a pipe opened by
     <function>popen</function>.
    </para> 
    <para> 
     The file pointer must be valid, and must have been returned by a
     successful call to <function>popen</function>.
    </para> 
    <para>
     Returns the termination status of the process that was
     run.
    </para>
    <para>
     See also <function>popen</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.popen">
   <refnamediv>
    <refname>popen</refname>
    <refpurpose>Open process file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>popen</function></funcdef>
     <paramdef>string <parameter>command</parameter></paramdef>
     <paramdef>string <parameter>mode</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Opens a pipe to a process executed by forking the command given
     by command.
    </para>
    <para> 
     Returns a file pointer identical to that returned by
     <function>fopen</function>, except that it is unidirectional (may
     only be used for reading or writing) and must be closed with
     <function>pclose</function>. This pointer may be used with
     <function>fgets</function>, <function>fgetss</function>, and
     <function>fputs</function>.
    </para>
    <para>
     If an error occurs, returns false.
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
$fp = popen ("/bin/ls", "r");
      </programlisting>
     </informalexample>
    </para>
    <para>
     See also <function>pclose</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readfile">
   <refnamediv>
    <refname>readfile</refname>
    <refpurpose>Output a file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>readfile</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>int 
      <parameter>
       <optional>use_include_path</optional>
      </parameter>
     </paramdef>
    </funcsynopsis>
    <para>
     Reads a file and writes it to standard output.
    </para>
    <para>
     Returns the number of bytes read from the file. If an error
     occurs, false is returned and unless the function was called as
     @readfile, an error message is printed.
    </para>
    <para>
     If <parameter>filename</parameter> begins with "http://"
     (not case sensitive), an HTTP 1.0 connection is opened to the
     specified server and the text of the response is written to
     standard output.
    </para>
    <para>
     Does not handle HTTP redirects, so you must include trailing
     slashes on directories.
    </para>
    <para>
     If <parameter>filename</parameter> begins with "ftp://"
     (not case sensitive), an ftp connection to the specified server is
     opened and the requested file is written to standard output. If the server
     does not support passive mode ftp, this will fail.
    </para>
    <para>
     If <parameter>filename</parameter> begins with neither
     of these strings, the file will be opened from the filesystem and
     its contents written to standard output.
    </para>
    <para>
     You can use the optional second parameter and set it to "1", if
     you want to search for the file in the <link
     linkend="ini.include-path">include_path</link>, too.
    </para>
    <para>
     See also <function>fpassthru</function>,
     <function>file</function>, <function>fopen</function>,
     <function>include</function>, <function>require</function>, and
     <function>virtual</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.readlink">
   <refnamediv>
    <refname>readlink</refname>
    <refpurpose>Return the target of a symbolic link</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>readlink</function></funcdef>
     <paramdef>string <parameter>path</parameter></paramdef>
    </funcsynopsis>
    <para>
    <function>Readlink</function> does the same as the readlink C
    function and returns the contents of the symbolic link path or 0
    in case of error.
    </para>
    <para>
     See also <function>symlink</function>,
     <function>readlink</function> and
     <function>linkinfo</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.rename">
   <refnamediv>
    <refname>rename</refname>
    <refpurpose>Rename a file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>rename</function></funcdef>
     <paramdef>string <parameter>oldname</parameter></paramdef>
     <paramdef>string <parameter>newname</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Attempts to rename <parameter>oldname</parameter> to
     <parameter>newname</parameter>.
    </para> 
    <para> 
     Returns true on success and false on failure.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.rewind">
   <refnamediv>
    <refname>rewind</refname>
    <refpurpose>Rewind the position of a file pointer</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>rewind</function></funcdef>
     <paramdef>int <parameter>fp</parameter></paramdef>
    </funcsynopsis>
    <para>    
     Sets the file position indicator for fp to the beginning of the
     file stream.</para> <para> If an error occurs, returns 0.</para>
     <para> The file pointer must be valid, and must point to a file
     successfully opened by <function>fopen</function>.
    </para>
    <para>
     See also <function>fseek</function> and
     <function>ftell</function>.
    </para>
   </refsect1>
  </refentry>


  <refentry id="function.rmdir">
   <refnamediv>
    <refname>rmdir</refname>
    <refpurpose>Remove directory</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>rmdir</function></funcdef>
     <paramdef>string <parameter>dirname</parameter></paramdef>
    </funcsynopsis>
    <para> 
     Attempts to remove the directory named by pathname. The directory
     must be empty, and the relevant permissions must permit.
     this.
    </para> 
    <para> 
     If an error occurs, returns 0.
    </para>
    <para>
     See also <function>mkdir</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.stat">
   <refnamediv>
    <refname>stat</refname>
    <refpurpose>Give information about a file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>stat</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Gathers the statistics of the file named by filename.</para>
    <para>
     Returns an array with the statistics of the file with the
     following elements:
     <orderedlist>
      <listitem><simpara>device</simpara></listitem>
      <listitem><simpara>inode</simpara></listitem>
      <listitem><simpara>inode protection mode</simpara></listitem>
      <listitem><simpara>number of links</simpara></listitem>
      <listitem><simpara>user id of owner</simpara></listitem>
      <listitem><simpara>group id owner</simpara></listitem>
      <listitem><simpara>device type if inode device *</simpara></listitem>
      <listitem><simpara>size in bytes</simpara></listitem>
      <listitem><simpara>time of last access</simpara></listitem>
      <listitem><simpara>time of last modification</simpara></listitem>
      <listitem><simpara>time of last change</simpara></listitem>
      <listitem><simpara>blocksize for filesystem I/O *</simpara></listitem>
      <listitem><simpara>number of blocks allocated</simpara></listitem>
     </orderedlist>
     * - only valid on systems supporting the st_blksize type--other
     systems (i.e. Windows) return -1</para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.lstat">
   <refnamediv>
    <refname>lstat</refname>
    <refpurpose>
     Give information about a file or symbolic link
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>array <function>lstat</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Gathers the statistics of the file or symbolic link named by
     filename.  This function is identical to the
     <function>stat</function> function except that if the
     <parameter>filename</parameter> parameter is a symbolic link, the
     status of the symbolic link is returned, not the status of the
     file pointed to by the symbolic link.
    </para>
    <para>
     Returns an array with the statistics of the file with the
     following elements:
     <orderedlist>
      <listitem><simpara>device</simpara></listitem>
      <listitem><simpara>inode</simpara></listitem>
      <listitem><simpara>number of links</simpara></listitem>
      <listitem><simpara>user id of owner</simpara></listitem>
      <listitem><simpara>group id owner</simpara></listitem>
      <listitem><simpara>device type if inode device *</simpara></listitem>
      <listitem><simpara>size in bytes</simpara></listitem>
      <listitem><simpara>time of last access</simpara></listitem>
      <listitem><simpara>time of last modification</simpara></listitem>
      <listitem><simpara>time of last change</simpara></listitem>
      <listitem><simpara>blocksize for filesystem I/O *</simpara></listitem>
      <listitem><simpara>number of blocks allocated</simpara></listitem>
     </orderedlist>
     * - only valid on systems supporting the st_blksize type--other
     systems (i.e. Windows) return -1</para>
    <para>
     The results of this function are cached. See
     <function>clearstatcache</function> for more details.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.symlink">
   <refnamediv>
    <refname>symlink</refname>
    <refpurpose>Create a symbolic link</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>symlink</function></funcdef>
     <paramdef>string <parameter>target</parameter></paramdef>
     <paramdef>string <parameter>link</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>symlink</function> creates a symbolic link
     from the existing <parameter>target</parameter> with
     the specified name <parameter>link</parameter>.
    </para>
    <para>
     See also <function>link</function> to create hard links,
     and <function>readlink</function> along with
     <function>linkinfo</function>.
    </para>
    <note>
     <simpara>
     This function does not work on Windows systems
     </simpara>
    </note>
   </refsect1>
  </refentry>

  <refentry id="function.tempnam">
   <refnamediv>
    <refname>tempnam</refname>
    <refpurpose>create unique file name</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>string <function>tempnam</function></funcdef>
     <paramdef>string <parameter>dir</parameter></paramdef>
     <paramdef>string <parameter>prefix</parameter></paramdef>
    </funcsynopsis>
    <para>
     Creates a unique temporary filename in the specified directory.
     If the directory does not exist, <function>tempnam</function> may
     generate a filename in the system's temporary directory.
    </para>
    <para>
     The behaviour of the <function>tempnam</function> function is
     system dependent. On Windows the TMP environment variable will
     override the <parameter>dir</parameter> parameter, on Linux the
     TMPDIR 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.
    </para>
    <para>
     Returns the new temporary filename, or the null string on
     failure.
     <example>
      <title><function>Tempnam</function> example</title>
      <programlisting role="php">
$tmpfname = tempnam ("/tmp", "FOO");
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.touch">
   <refnamediv>
    <refname>touch</refname>
    <refpurpose>Set modification time of file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>touch</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
     <paramdef>int <parameter>time</parameter></paramdef>
    </funcsynopsis>
    <para>
     Attempts to set the modification time of the file named by
     filename to the value given by time. If the option time is not
     given, uses the present time.
    </para>
    <para>
     If the file does not exist, it is created.
    </para>
    <para>
     Returns true on success and false otherwise.
     <example>
      <title><function>touch</function> example</title>
      <programlisting role="php">
if ( touch($FileName) ) {
  print "$FileName modification time has been changed to todays date and time";
} else {
  print "Sorry Could Not change modification time of $FileName";
}
      </programlisting>
     </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.umask">
   <refnamediv>
    <refname>umask</refname>
    <refpurpose>Changes the current umask</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>umask</function></funcdef>
     <paramdef>int <parameter>mask</parameter></paramdef>
    </funcsynopsis>
    <para>
     <function>Umask</function> sets PHP's umask to mask & 0777 and
     returns the old umask. When PHP is being used as a server module,
     the umask is restored when each request is finished.
    </para>
    <para>
     <function>Umask</function> without arguments simply returns the
     current umask.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.unlink">
   <refnamediv>
    <refname>unlink</refname>
    <refpurpose>Delete a file</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcdef>int <function>unlink</function></funcdef>
     <paramdef>string <parameter>filename</parameter></paramdef>
    </funcsynopsis>
    <para>
     Deletes <parameter>filename</parameter>.  Similar to the Unix C
     unlink() function.
    </para>
    <para>
     Returns 0 or FALSE on an error.
    </para>
    <para>
     See also <function>rmdir</function> for removing directories.
    </para>
    <note>
     <simpara>
     This function may not work on Windows systems.
     </simpara>
    </note>
   </refsect1>
  </refentry>

 </reference>

<!-- 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
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->