mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 10:28:54 +00:00
5cdf44621d
Clarified some things about $HTTP_POST_FILES, PHP 3/PHP 4, and how to test for uploaded file safety. Minor cleanups, too. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@32400 c90b9560-bf6c-de11-be94-00142212c4b1
2539 lines
79 KiB
XML
2539 lines
79 KiB
XML
<reference id="ref.filesystem">
|
|
<title>Filesystem functions</title>
|
|
<titleabbrev>Filesystem</titleabbrev>
|
|
|
|
<refentry id="function.basename">
|
|
<refnamediv>
|
|
<refname>basename</refname>
|
|
<refpurpose>
|
|
Returns filename component of path
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>basename</function></funcdef>
|
|
<paramdef>string <parameter>path</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Changes file group</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>chgrp</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>mixed <parameter>group</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Attempts to change the group of the file
|
|
<parameter>filename</parameter> to
|
|
<parameter>group</parameter>. 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>Changes file mode</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>chmod</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>int <parameter>mode</parameter></paramdef>
|
|
</funcprototype>
|
|
</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, so strings (such as "g+w") will
|
|
not work properly. 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", "u+rwx,go+rx"); // string; 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>Changes file owner</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>chown</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>mixed <parameter>user</parameter></paramdef>
|
|
</funcprototype>
|
|
</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.
|
|
</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>Clears file stat cache</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clearstatcache</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</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>Copies file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>copy</function></funcdef>
|
|
<paramdef>string <parameter>source</parameter></paramdef>
|
|
<paramdef>string <parameter>dest</parameter></paramdef>
|
|
</funcprototype>
|
|
</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...<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>
|
|
<funcprototype>
|
|
<funcdef>void <function>delete</function></funcdef>
|
|
<paramdef>string <parameter>file</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Returns directory name component of path</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>dirname</function></funcdef>
|
|
<paramdef>string <parameter>path</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Returns available space in directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>float <function>diskfreespace</function></funcdef>
|
|
<paramdef>string <parameter>directory</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Given a string containing a directory, this function will return
|
|
the number of bytes available on the corresponding filesystem or
|
|
disk partition.
|
|
</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>Closes an open file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fclose</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Tests for end-of-file on a file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>feof</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets character from file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fgetc</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a string containing a single character read from the
|
|
file pointed to by fp. Returns FALSE on EOF.
|
|
</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>
|
|
Gets line from file pointer and parse for CSV fields
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<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>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<simpara>
|
|
Similar to <function>fgets</function> except that
|
|
<function>fgetcsv</function> parses the line it reads for fields
|
|
in <acronym>CSV</acronym> format and returns an array containing
|
|
the fields read. The field delimiter is a comma, unless you
|
|
specify another delimiter with the optional third parameter.
|
|
</simpara>
|
|
<simpara>
|
|
<parameter>Fp</parameter> 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>
|
|
<function>Fgetcsv</function> returns false on error, including
|
|
end of file.
|
|
</simpara>
|
|
<simpara>
|
|
N.B. A blank line in a CSV file will be returned as an array
|
|
comprising a 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 "<p> $num fields in line $row: <br>";
|
|
$row++;
|
|
for ($c=0; $c<$num; $c++) {
|
|
print $data[$c] . "<br>";
|
|
}
|
|
}
|
|
fclose ($fp);
|
|
</programlisting>
|
|
</example>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fgets">
|
|
<refnamediv>
|
|
<refname>fgets</refname>
|
|
<refpurpose>Gets line from file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fgets</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
<paramdef>int <parameter>length</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>,
|
|
<function>fsockopen</function>, and
|
|
<function>socket_set_timeout</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fgetss">
|
|
<refnamediv>
|
|
<refname>fgetss</refname>
|
|
<refpurpose>
|
|
Gets line from file pointer and strip HTML tags
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<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>
|
|
</funcprototype>
|
|
</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>Reads entire file into an array</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>file</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter><optional>use_include_path</optional></parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</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 role="php">
|
|
<?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 "<b>Line $line_num:</b> " . htmlspecialchars ($line) . "<br>\n";
|
|
}
|
|
|
|
// get a web page into a string
|
|
$fcontents = join ('', file ('http://www.php.net'));
|
|
?>
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
<para>
|
|
See also <function>readfile</function>,
|
|
<function>fopen</function>, <function>fsockopen</function>, and
|
|
<function>popen</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.file-exists">
|
|
<refnamediv>
|
|
<refname>file_exists</refname>
|
|
<refpurpose>Checks whether a file exists</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>file_exists</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets last access time of file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fileatime</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<simpara>
|
|
Note: The atime of a file is supposed to change whenever
|
|
the data blocks of a file are being read. This can be
|
|
costly performancewise when an appliation regularly
|
|
accesses a very large number of files or directories. Some
|
|
Unix filesystems can be mounted with atime updates disabled
|
|
to increase the performance of such applications; USENET
|
|
news spools are a common example. On such filesystems
|
|
this function will be useless.
|
|
</simpara>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.filectime">
|
|
<refnamediv>
|
|
<refname>filectime</refname>
|
|
<refpurpose>Gets inode change time of file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>filectime</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<para>Note: In most Unix filesystem, a file is considered
|
|
changed, when it's Inode data is changed, that is, when
|
|
the permissions, the owner, the group or other metadata
|
|
from the Inode is written to. See also
|
|
<function>filemtime</function> (this is what you want to use
|
|
when you want to create "Last Modified" footers on web pages) and
|
|
<function>fileatime</function>.
|
|
</para>
|
|
<para>Note: In some Unix texts the ctime of a file is being
|
|
referred to as the creation time of the file. This is wrong.
|
|
There is no creation time for Unix files in most Unix
|
|
filesystems.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.filegroup">
|
|
<refnamediv>
|
|
<refname>filegroup</refname>
|
|
<refpurpose>Gets file group</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>filegroup</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets file inode</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fileinode</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets file modification time</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>filemtime</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<para>Note: This function returns the time when the data
|
|
blocks of a file were being written to, that is, the time
|
|
when the content of the file was changed. Use
|
|
<function>date</function> on the result of this function
|
|
to get a printable modification date for use in page footers.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fileowner">
|
|
<refnamediv>
|
|
<refname>fileowner</refname>
|
|
<refpurpose>Gets file owner</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fileowner</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets file permissions</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fileperms</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets file size</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>filesize</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets file type</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>filetype</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>flock</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
<paramdef>int <parameter>operation</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>wouldblock</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</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 LOCK_SH (set to 1 prior to
|
|
PHP 4.0.1).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
To acquire an exclusive lock (writer), set
|
|
<parameter>operation</parameter> to LOCK_EX (set to 2 prior to
|
|
PHP 4.0.1).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
To release a lock (shared or exclusive), set
|
|
<parameter>operation</parameter> to LOCK_UN (set to 3 prior to
|
|
PHP 4.0.1).
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
If you don't want <function>flock</function> to block while
|
|
locking, add LOCK_NB (4 prior to PHP 4.0.1) 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). The optional 3rd
|
|
argument is set to true if the lock would block (EWOULDBLOCK
|
|
errno condition)
|
|
</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>Opens file or URL</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<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>
|
|
</funcprototype>
|
|
</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. A 'Host:' header is sent with the
|
|
request in order to handle name-based virtual hosts.
|
|
</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>
|
|
The <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><function>Fopen</function> example</title>
|
|
<programlisting role="php">
|
|
$fp = fopen ("/home/rasmus/file.txt", "r");
|
|
$fp = fopen ("/home/rasmus/file.gif", "wb");
|
|
$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>,
|
|
<function>socket_set_timeout</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>
|
|
<funcprototype>
|
|
<funcdef>int <function>fpassthru</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Writes to a file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<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>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>string <function>fread</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
<paramdef>int <parameter>length</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>fscanf</function>, <function>file</function>, and
|
|
<function>fpassthru</function>.
|
|
</simpara>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fscanf">
|
|
<refnamediv>
|
|
<refname>fscanf</refname>
|
|
<refpurpose>Parses input from a file according to a format</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>fscanf</function></funcdef>
|
|
<paramdef>int <parameter>handle</parameter></paramdef>
|
|
<paramdef>string <parameter>format</parameter></paramdef>
|
|
<paramdef>string
|
|
<parameter><optional>var1</optional></parameter>...
|
|
</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The function <function>fscanf</function> is similar to
|
|
<function>sscanf</function>, but it takes its input from a file
|
|
associated with <parameter>handle</parameter> and interprets the
|
|
input according to the specified
|
|
<parameter>format</parameter>. If only two parameters were passed
|
|
to this function, the values parsed will be returned as an array.
|
|
Otherwise, if optional parameters are passed, the function will
|
|
return the number of assigned values. The optional parameters
|
|
must be passed by reference.
|
|
<example>
|
|
<title><function>Fscanf</function> Example</title>
|
|
<programlisting role="php">
|
|
$fp = fopen ("users.txt","r");
|
|
while ($userinfo = fscanf ($fp, "%s\t%s\t%s\n")) {
|
|
list ($name, $profession, $countrycode) = $userinfo;
|
|
//... do something with the values
|
|
}
|
|
fclose($fp);
|
|
</programlisting>
|
|
</example>
|
|
<example>
|
|
<title>users.txt</title>
|
|
<programlisting>
|
|
javier argonaut pe
|
|
hiroshi sculptor jp
|
|
robert slacker us
|
|
luigi florist it
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>fread</function>, <function>fgets</function>,
|
|
<function>fgetss</function>, <function>sscanf</function>,
|
|
<function>printf</function>, and <function>sprintf</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.fseek">
|
|
<refnamediv>
|
|
<refname>fseek</refname>
|
|
<refpurpose>Seeks on a file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<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>
|
|
</funcprototype>
|
|
</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.fstat">
|
|
<refnamediv>
|
|
<refname>fstat</refname>
|
|
<refpurpose>
|
|
Gets information about a file using an open file pointer
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>fstat</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Gathers the statistics of the file opened by the file
|
|
pointer fp. This function is similar to the
|
|
<function>stat</function> function except that it operates
|
|
on an open file pointer instead of a 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>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.ftell">
|
|
<refnamediv>
|
|
<refname>ftell</refname>
|
|
<refpurpose>Tells file pointer read/write position</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ftell</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
Truncates a file to a given length.
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>ftruncate</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
<paramdef>int <parameter>size</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<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>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>int <function>set_file_buffer</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
<paramdef>int <parameter>buffer</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<simpara>
|
|
Output using <function>fwrite</function> is normally buffered at
|
|
8K. This means that if there are two processess wanting to write
|
|
to the same output stream (a file), each is paused after 8K of
|
|
data to allow the other to write. <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. This ensures that all writes with
|
|
<function>fwrite</function> are completed before other processes
|
|
are allowed to write to that output stream.
|
|
</simpara>
|
|
<simpara>
|
|
The function returns 0 on success, or EOF if the request cannot
|
|
be honored.
|
|
</simpara>
|
|
<para>
|
|
The following example demonstrates how to use
|
|
<function>set_file_buffer</function> to create an unbuffered stream.
|
|
<example>
|
|
<title><function>set_file_buffer</function> example</title>
|
|
<programlisting role="php">
|
|
$fp=fopen($file, "w");
|
|
if($fp){
|
|
set_file_buffer($fp, 0);
|
|
fputs($fp, $output);
|
|
fclose($fp);
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<simpara>
|
|
See also <function>fopen</function>, <function>fwrite</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_dir</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_executable</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_file</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_link</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_readable</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_writeable</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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.is-uploaded-file">
|
|
<refnamediv>
|
|
<refname>is_uploaded_file</refname>
|
|
<refpurpose>Tells whether the file was uploaded via HTTP POST.</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>is_uploaded_file</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
This function is available only in versions of PHP 3 after PHP
|
|
3.0.16, and in versions of PHP 4 after 4.0.2.
|
|
</para>
|
|
|
|
<para>
|
|
Returns true if the file named by <varname>filename</varname> was
|
|
uploaded via HTTP POST. This is useful to help ensure that a
|
|
malicious user hasn't tried to trick the script into working on
|
|
files upon which it should not be working--for instance,
|
|
<filename>/etc/passwd</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
This sort of check is especially important if there is any chance
|
|
that anything done with uploaded files could reveal their
|
|
contents to the user, or even to other users on the same
|
|
system.
|
|
</para>
|
|
|
|
<para>
|
|
See also <function>move_uploaded_file</function>, and the section
|
|
<link linkend="features.file-upload">Handling file uploads</link>
|
|
for a simple usage example.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.link">
|
|
<refnamediv>
|
|
<refname>link</refname>
|
|
<refpurpose>Create a hard link</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>link</function></funcdef>
|
|
<paramdef>string <parameter>target</parameter></paramdef>
|
|
<paramdef>string <parameter>link</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gets information about a link</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>linkinfo</function></funcdef>
|
|
<paramdef>string <parameter>path</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Makes directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>mkdir</function></funcdef>
|
|
<paramdef>string <parameter>pathname</parameter></paramdef>
|
|
<paramdef>int <parameter>mode</parameter></paramdef>
|
|
</funcprototype>
|
|
</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.move-uploaded-file">
|
|
<refnamediv>
|
|
<refname>move_uploaded_file</refname>
|
|
<refpurpose>Moves an uploaded file to a new location.</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>move_uploaded_file</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>string <parameter>destination</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
This function is available only in versions of PHP 3 after PHP
|
|
3.0.16, and in versions of PHP 4 after 4.0.2.
|
|
</para>
|
|
|
|
<para>
|
|
This function checks to ensure that the file designated by
|
|
<parameter>filename</parameter> is a valid upload file (meaning
|
|
that it was uploaded via PHP's HTTP POST upload mechanism). If
|
|
the file is valid, it will be moved to the filename given by
|
|
<parameter>destination</parameter>.
|
|
</para>
|
|
|
|
<para>
|
|
If <parameter>filename</parameter> is not a valid upload file,
|
|
then no action will occur, and
|
|
<function>move_uploaded_file</function> will return
|
|
<literal>false</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
If <parameter>filename</parameter> is a valid upload file, but
|
|
cannot be moved for some reason, no action will occur, and
|
|
<function>move_uploaded_file</function> will return
|
|
<literal>false</literal>. Additionally, a warning will be issued.
|
|
</para>
|
|
|
|
<para>
|
|
This sort of check is especially important if there is any chance
|
|
that anything done with uploaded files could reveal their
|
|
contents to the user, or even to other users on the same
|
|
system.
|
|
</para>
|
|
|
|
<para>
|
|
See also <function>is_uploaded_file</function>, and the section
|
|
<link linkend="features.file-upload">Handling file uploads</link>
|
|
for a simple usage example.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.pclose">
|
|
<refnamediv>
|
|
<refname>pclose</refname>
|
|
<refpurpose>Closes process file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>pclose</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Opens process file pointer</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>popen</function></funcdef>
|
|
<paramdef>string <parameter>command</parameter></paramdef>
|
|
<paramdef>string <parameter>mode</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Outputs a file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>readfile</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>use_include_path</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</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>Returns the target of a symbolic link</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>readlink</function></funcdef>
|
|
<paramdef>string <parameter>path</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Renames a file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>rename</function></funcdef>
|
|
<paramdef>string <parameter>oldname</parameter></paramdef>
|
|
<paramdef>string <parameter>newname</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>int <function>rewind</function></funcdef>
|
|
<paramdef>int <parameter>fp</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Removes directory</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>rmdir</function></funcdef>
|
|
<paramdef>string <parameter>dirname</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Gives information about a file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>stat</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
Gives information about a file or symbolic link
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>lstat</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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.realpath">
|
|
<refnamediv>
|
|
<refname>realpath</refname>
|
|
<refpurpose>Returns canonicalized absolute pathname</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>realpath</function></funcdef>
|
|
<paramdef>string <parameter>path</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
<function>realpath</function> expands all symbolic links and
|
|
resolves references to '/./', '/../' and extra '/' characters in
|
|
the input <parameter>path</parameter> and return the canonicalized
|
|
absolute pathname. The resulting path will have no symbolic link,
|
|
'/./' or '/../' components.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title><function>realpath</function> example</title>
|
|
<programlisting role="php">
|
|
$real_path = realpath ("../../index.php");
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.symlink">
|
|
<refnamediv>
|
|
<refname>symlink</refname>
|
|
<refpurpose>Creates a symbolic link</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>symlink</function></funcdef>
|
|
<paramdef>string <parameter>target</parameter></paramdef>
|
|
<paramdef>string <parameter>link</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Creates unique file name</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>tempnam</function></funcdef>
|
|
<paramdef>string <parameter>dir</parameter></paramdef>
|
|
<paramdef>string <parameter>prefix</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<para>
|
|
See also <function>tmpfile</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.tmpfile">
|
|
<refnamediv>
|
|
<refname>tmpfile</refname>
|
|
<refpurpose>Creates a temporary file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>tmpfile</function></funcdef>
|
|
<paramdef>void</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Creates a temporary file with an unique name in write mode,
|
|
returning a file handle similar to the one returned by
|
|
<function>fopen</function>.
|
|
The file is automatically removed when closed (using
|
|
<function>fclose</function>), or when the script ends.
|
|
</para>
|
|
<para>
|
|
For details, consult your system documentation on the
|
|
<literal>tmpfile(3)</literal> function, as well as the
|
|
<filename>stdio.h</filename> header file.
|
|
</para>
|
|
<para>
|
|
See also <function>tempnam</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.touch">
|
|
<refnamediv>
|
|
<refname>touch</refname>
|
|
<refpurpose>Sets modification time of file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>touch</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>time</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcprototype>
|
|
</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>
|
|
<funcprototype>
|
|
<funcdef>int <function>umask</function></funcdef>
|
|
<paramdef>int <parameter>mask</parameter></paramdef>
|
|
</funcprototype>
|
|
</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>Deletes a file</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>unlink</function></funcdef>
|
|
<paramdef>string <parameter>filename</parameter></paramdef>
|
|
</funcprototype>
|
|
</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:
|
|
-->
|