 |
 |
 |
 |
|
|
Date: 08/31/00
- Next message: Luca Perugini: "[PHP-DOC] cvs: phpdoc /it/functions ftp.xml"
- Previous message: Luca Perugini: "[PHP-DOC] cvs: phpdoc /it/functions filepro.xml"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
perugini Thu Aug 31 09:34:44 2000 EDT
Modified files:
/phpdoc/it/functions filesystem.xml
Log:
Sync with en tree.
Index: phpdoc/it/functions/filesystem.xml
diff -u phpdoc/it/functions/filesystem.xml:1.5 phpdoc/it/functions/filesystem.xml:1.6
--- phpdoc/it/functions/filesystem.xml:1.5 Sat Jun 24 00:38:44 2000
+++ phpdoc/it/functions/filesystem.xml Thu Aug 31 09:34:44 2000
@@ -6,7 +6,7 @@
<refnamediv>
<refname>basename</refname>
<refpurpose>
- Return filename component of path
+ Returns filename component of path
</refpurpose>
</refnamediv>
<refsect1>
@@ -32,7 +32,7 @@
<title><function>basename</function> example</title>
<programlisting role="php">
$path = "/home/httpd/html/index.php3";
-$file = basename($path); // $file is set to "index.php3"
+$file = basename ($path); // $file is set to "index.php3"
</programlisting>
</example>
</para>
@@ -45,7 +45,7 @@
<refentry id="function.chgrp">
<refnamediv>
<refname>chgrp</refname>
- <refpurpose>Change file group</refpurpose>
+ <refpurpose>Changes file group</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -57,10 +57,11 @@
</funcprototype>
</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.
+ 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.
@@ -71,7 +72,7 @@
</para>
<note>
<simpara>
- This function does not work on Windows systems
+ This function does not work on Windows systems
</simpara>
</note>
</refsect1>
@@ -80,7 +81,7 @@
<refentry id="function.chmod">
<refnamediv>
<refname>chmod</refname>
- <refpurpose>Change file mode</refpurpose>
+ <refpurpose>Changes file mode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -98,12 +99,14 @@
</para>
<para>
Note that <parameter>mode</parameter> is not automatically
- assumed to be an octal value. To ensure the expected operation,
+ 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", 0755 ); // octal; correct value of mode
+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>
@@ -116,7 +119,7 @@
</para>
<note>
<simpara>
- This function does not work on Windows systems
+ This function does not work on Windows systems
</simpara>
</note>
</refsect1>
@@ -125,7 +128,7 @@
<refentry id="function.chown">
<refnamediv>
<refname>chown</refname>
- <refpurpose>change file owner</refpurpose>
+ <refpurpose>Changes file owner</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -142,10 +145,6 @@
</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
@@ -162,7 +161,7 @@
<refentry id="function.clearstatcache">
<refnamediv>
<refname>clearstatcache</refname>
- <refpurpose>Clear file stat cache</refpurpose>
+ <refpurpose>Clears file stat cache</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -211,7 +210,7 @@
<refentry id="function.copy">
<refnamediv>
<refname>copy</refname>
- <refpurpose>Copy file</refpurpose>
+ <refpurpose>Copies file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -226,10 +225,10 @@
Makes a copy of a file. Returns true if the copy succeeded,
false otherwise.
<example>
- <title><function>copy</function> example</title>
+ <title><function>Copy</function> example</title>
<programlisting role="php">
-if ( !copy($file, $file.'.bak') ) {
- print("failed to copy $file...<br>\n");
+if (!copy($file, $file.'.bak')) {
+ print ("failed to copy $file...<br>\n");
}
</programlisting>
</example>
@@ -253,21 +252,22 @@
<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>
+ 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>
+ <refpurpose>Returns directory name component of path</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -287,10 +287,10 @@
(<literal>/</literal>).</para>
<para>
<example>
- <title><function>dirname</function> example</title>
+ <title><function>Dirname</function> example</title>
<programlisting role="php">
$path = "/etc/passwd";
-$file = dirname($path); // $file is set to "/etc"
+$file = dirname ($path); // $file is set to "/etc"
</programlisting>
</example>
</para>
@@ -303,7 +303,7 @@
<refentry id="function.diskfreespace">
<refnamediv>
<refname>diskfreespace</refname>
- <refpurpose>Return available space in directory</refpurpose>
+ <refpurpose>Returns available space in directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -315,7 +315,8 @@
</funcsynopsis>
<para>
Given a string containing a directory, this function will return
- the number of bytes available on the corresponding disk.
+ the number of bytes available on the corresponding filesystem or
+ disk partition.
</para>
<para>
<example>
@@ -332,7 +333,7 @@
<refentry id="function.fclose">
<refnamediv>
<refname>fclose</refname>
- <refpurpose>Close an open file pointer</refpurpose>
+ <refpurpose>Closes an open file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -359,7 +360,7 @@
<refentry id="function.feof">
<refnamediv>
<refname>feof</refname>
- <refpurpose>Test for end-of-file on a file pointer</refpurpose>
+ <refpurpose>Tests for end-of-file on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -384,7 +385,7 @@
<refentry id="function.fgetc">
<refnamediv>
<refname>fgetc</refname>
- <refpurpose>Get character from file pointer</refpurpose>
+ <refpurpose>Gets character from file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -396,8 +397,8 @@
</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>
+ 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>,
@@ -415,7 +416,7 @@
<refnamediv>
<refname>fgetcsv</refname>
<refpurpose>
- Get line from file pointer and parse for CSV fields
+ Gets line from file pointer and parse for CSV fields
</refpurpose>
</refnamediv>
<refsect1>
@@ -433,22 +434,24 @@
</funcprototype>
</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.
+ 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
+ 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>
+ <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
+ 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.
+ <function>Fgetcsv</function> returns false on error, including
+ end of file.
</simpara>
<simpara>
NB A blank line in a CSV file will be returned as an array
@@ -465,10 +468,10 @@
$fp = fopen ("test.csv","r");
while ($data = fgetcsv ($fp, 1000, ",")) {
$num = count ($data);
- print "<p> $num fields in line $row: <br>";
+ print "<p> $num fields in line $row: <br>";
$row++;
- for ($c=0; $c<$num; $c++) {
- print $data[$c] . "<br>";
+ for ($c=0; $c<$num; $c++) {
+ print $data[$c] . "<br>";
}
}
fclose ($fp);
@@ -480,7 +483,7 @@
<refentry id="function.fgets">
<refnamediv>
<refname>fgets</refname>
- <refpurpose>Get line from file pointer</refpurpose>
+ <refpurpose>Gets line from file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -519,7 +522,7 @@
<title>Reading a file line by line</title>
<programlisting role="php">
$fd = fopen ("/tmp/inputfile.txt", "r");
-while (!feof($fd)) {
+while (!feof ($fd)) {
$buffer = fgets($fd, 4096);
echo $buffer;
}
@@ -529,8 +532,9 @@
</para>
<para>
See also <function>fread</function>, <function>fopen</function>,
- <function>popen</function>, <function>fgetc</function>, and
- <function>fsockopen</function>.
+ <function>popen</function>, <function>fgetc</function>,
+ <function>fsockopen</function>, and
+ <function>socket_set_timeout</function>.
</para>
</refsect1>
</refentry>
@@ -539,7 +543,7 @@
<refnamediv>
<refname>fgetss</refname>
<refpurpose>
- Get line from file pointer and strip HTML tags
+ Gets line from file pointer and strip HTML tags
</refpurpose>
</refnamediv>
<refsect1>
@@ -579,11 +583,10 @@
</refsect1>
</refentry>
-
<refentry id="function.file">
<refnamediv>
<refname>file</refname>
- <refpurpose>read entire file into an array</refpurpose>
+ <refpurpose>Reads entire file into an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -596,40 +599,37 @@
</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>
+ <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";
+$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' ) );
+$fcontents = join ('', file ('http://www.php.net'));
?>
</programlisting>
</informalexample>
</para>
-
<para>
See also <function>readfile</function>,
- <function>fopen</function>, and <function>popen</function>.
+ <function>fopen</function>, <function>fsockopen</function>, and
+ <function>popen</function>.
</para>
</refsect1>
</refentry>
@@ -638,33 +638,29 @@
<refentry id="function.file-exists">
<refnamediv>
<refname>file_exists</refname>
- <refpurpose>Check whether a file exists</refpurpose>
+ <refpurpose>Checks whether a file exists</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>int <function>file_exists</function></funcdef>
+ <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>
@@ -672,7 +668,7 @@
<refentry id="function.fileatime">
<refnamediv>
<refname>fileatime</refname>
- <refpurpose>Get last access time of file</refpurpose>
+ <refpurpose>Gets last access time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -682,25 +678,31 @@
<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>Get inode change time of file</refpurpose>
+ <refpurpose>Gets inode change time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -718,13 +720,26 @@
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>Get file group</refpurpose>
+ <refpurpose>Gets file group</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -754,7 +769,7 @@
<refentry id="function.fileinode">
<refnamediv>
<refname>fileinode</refname>
- <refpurpose>Get file inode</refpurpose>
+ <refpurpose>Gets file inode</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -782,7 +797,7 @@
<refentry id="function.filemtime">
<refnamediv>
<refname>filemtime</refname>
- <refpurpose>Get file modification time</refpurpose>
+ <refpurpose>Gets file modification time</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -800,13 +815,19 @@
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>Get file owner</refpurpose>
+ <refpurpose>Gets file owner</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -836,7 +857,7 @@
<refentry id="function.fileperms">
<refnamediv>
<refname>fileperms</refname>
- <refpurpose>Get file permissions</refpurpose>
+ <refpurpose>Gets file permissions</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -859,7 +880,7 @@
<refentry id="function.filesize">
<refnamediv>
<refname>filesize</refname>
- <refpurpose>Get file size</refpurpose>
+ <refpurpose>Gets file size</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -882,7 +903,7 @@
<refentry id="function.filetype">
<refnamediv>
<refname>filetype</refname>
- <refpurpose>Get file type</refpurpose>
+ <refpurpose>Gets file type</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -916,6 +937,11 @@
<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>
@@ -934,36 +960,42 @@
<listitem>
<simpara>
To acquire a shared lock (reader), set
- <parameter>operation</parameter> to 1.
+ <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 2.
+ <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 3.
+ <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 4 to <parameter>operation</parameter>.
+ 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
+ <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).
+ (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
+ <function>Flock</function> returns true on success and false on
error (e.g. when a lock could not be acquired).
</simpara>
</refsect1>
@@ -972,7 +1004,7 @@
<refentry id="function.fopen">
<refnamediv>
<refname>fopen</refname>
- <refpurpose>Open file or URL</refpurpose>
+ <refpurpose>Opens file or URL</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -992,7 +1024,8 @@
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.
+ 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
@@ -1065,7 +1098,7 @@
</simpara>
</listitem>
</itemizedlist>
- As well, <parameter>mode</parameter> may contain the letter
+ 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.
@@ -1077,11 +1110,12 @@
</para>
<para>
<example>
- <title>fopen() example</title>
+ <title><function>Fopen</function> example</title>
<programlisting role="php">
-$fp = fopen("/home/rasmus/file.txt", "r");
-$fp = fopen("http://www.php.net/", "r");
-$fp = fopen("email protected>?subject=Re:%20[PHP-DOC]%20cvs:%20phpdoc%20/it/functions%20filesystem.xml&replyto=cvsperugini967739684 <email protected>">password <email protected>/">ftp://user:password <email protected>/", "w");
+$fp = fopen ("/home/rasmus/file.txt", "r");
+$fp = fopen ("/home/rasmus/file.gif", "wb");
+$fp = fopen ("http://www.php.net/", "r");
+$fp = fopen ("email protected>?subject=Re:%20[PHP-DOC]%20cvs:%20phpdoc%20/it/functions%20filesystem.xml&replyto=cvsperugini967739684 <email protected>">password <email protected>/">ftp://user:password <email protected>/", "w");
</programlisting>
</example>
</para>
@@ -1096,13 +1130,15 @@
used in the path to the file, or use forward slashes.
<informalexample>
<programlisting role="php">
-$fp = fopen("c:\\data\\info.txt", "r");
+$fp = fopen ("c:\\data\\info.txt", "r");
</programlisting>
</informalexample>
</para>
<simpara>
See also <function>fclose</function>,
- <function>fsockopen</function>, and <function>popen</function>.
+ <function>fsockopen</function>,
+ <function>socket_set_timeout</function>, and
+ <function>popen</function>.
</simpara>
</refsect1>
</refentry>
@@ -1153,7 +1189,7 @@
<refentry id="function.fputs">
<refnamediv>
<refname>fputs</refname>
- <refpurpose>Write to a file pointer</refpurpose>
+ <refpurpose>Writes to a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1170,7 +1206,7 @@
</funcprototype>
</funcsynopsis>
<para>
- <function>fputs</function> is an alias to
+ <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.
@@ -1193,7 +1229,7 @@
</funcprototype>
</funcsynopsis>
<simpara>
- <function>fread</function> reads up to
+ <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
@@ -1214,15 +1250,72 @@
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>.
+ <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>Seek on a file pointer</refpurpose>
+ <refpurpose>Seeks on a file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1231,12 +1324,29 @@
<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 fp to
- offset bytes into the file stream. Equivalent to calling (in C)
- <literal>fseek(fp, offset, SEEK_SET)</literal>.
+ 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
@@ -1247,6 +1357,11 @@
<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>.
@@ -1254,10 +1369,57 @@
</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>Tell file pointer read/write position</refpurpose>
+ <refpurpose>Tells file pointer read/write position</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1290,7 +1452,7 @@
<refnamediv>
<refname>ftruncate</refname>
<refpurpose>
- Truncate a file to a given length.
+ Truncates a file to a given length.
</refpurpose>
</refnamediv>
<refsect1>
@@ -1369,22 +1531,39 @@
</funcprototype>
</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.
+ 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>
- <simpara>
- Note that the default for any fopen with calling set_file_buffer
- is 8K.
</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>.
+ See also <function>fopen</function>, <function>fwrite</function>.
</simpara>
</refsect1>
</refentry>
@@ -1604,7 +1783,7 @@
<refentry id="function.linkinfo">
<refnamediv>
<refname>linkinfo</refname>
- <refpurpose>Get information about a link</refpurpose>
+ <refpurpose>Gets information about a link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1637,7 +1816,7 @@
<refentry id="function.mkdir">
<refnamediv>
<refname>mkdir</refname>
- <refpurpose>Make directory</refpurpose>
+ <refpurpose>Makes directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1672,7 +1851,7 @@
<refentry id="function.pclose">
<refnamediv>
<refname>pclose</refname>
- <refpurpose>Close process file pointer</refpurpose>
+ <refpurpose>Closes process file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1703,7 +1882,7 @@
<refentry id="function.popen">
<refnamediv>
<refname>popen</refname>
- <refpurpose>Open process file pointer</refpurpose>
+ <refpurpose>Opens process file pointer</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1745,7 +1924,7 @@
<refentry id="function.readfile">
<refnamediv>
<refname>readfile</refname>
- <refpurpose>Output a file</refpurpose>
+ <refpurpose>Outputs a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1806,7 +1985,7 @@
<refentry id="function.readlink">
<refnamediv>
<refname>readlink</refname>
- <refpurpose>Return the target of a symbolic link</refpurpose>
+ <refpurpose>Returns the target of a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1837,7 +2016,7 @@
<refentry id="function.rename">
<refnamediv>
<refname>rename</refname>
- <refpurpose>Rename a file</refpurpose>
+ <refpurpose>Renames a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1888,7 +2067,7 @@
<refentry id="function.rmdir">
<refnamediv>
<refname>rmdir</refname>
- <refpurpose>Remove directory</refpurpose>
+ <refpurpose>Removes directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1915,7 +2094,7 @@
<refentry id="function.stat">
<refnamediv>
<refname>stat</refname>
- <refpurpose>Give information about a file</refpurpose>
+ <refpurpose>Gives information about a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -1958,7 +2137,7 @@
<refnamediv>
<refname>lstat</refname>
<refpurpose>
- Give information about a file or symbolic link
+ Gives information about a file or symbolic link
</refpurpose>
</refnamediv>
<refsect1>
@@ -2003,10 +2182,41 @@
</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>Create a symbolic link</refpurpose>
+ <refpurpose>Creates a symbolic link</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2029,7 +2239,7 @@
</para>
<note>
<simpara>
- This function does not work on Windows systems
+ This function does not work on Windows systems.
</simpara>
</note>
</refsect1>
@@ -2038,7 +2248,7 @@
<refentry id="function.tempnam">
<refnamediv>
<refname>tempnam</refname>
- <refpurpose>create unique file name</refpurpose>
+ <refpurpose>Creates unique file name</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2073,13 +2283,48 @@
</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>Set modification time of file</refpurpose>
+ <refpurpose>Sets modification time of file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2087,7 +2332,11 @@
<funcprototype>
<funcdef>int <function>touch</function></funcdef>
<paramdef>string <parameter>filename</parameter></paramdef>
- <paramdef>int <parameter>time</parameter></paramdef>
+ <paramdef>int
+ <parameter>
+ <optional>time</optional>
+ </parameter>
+ </paramdef>
</funcprototype>
</funcsynopsis>
<para>
@@ -2101,12 +2350,13 @@
<para>
Returns true on success and false otherwise.
<example>
- <title><function>touch</function> example</title>
+ <title><function>Touch</function> example</title>
<programlisting role="php">
-if ( touch($FileName) ) {
- print "$FileName modification time has been changed to todays date and time";
+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";
+ print "Sorry Could Not change modification time of $FileName";
}
</programlisting>
</example>
@@ -2128,7 +2378,7 @@
</funcprototype>
</funcsynopsis>
<para>
- <function>Umask</function> sets PHP's umask to mask & 0777 and
+ <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>
@@ -2142,7 +2392,7 @@
<refentry id="function.unlink">
<refnamediv>
<refname>unlink</refname>
- <refpurpose>Delete a file</refpurpose>
+ <refpurpose>Deletes a file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
@@ -2164,7 +2414,7 @@
</para>
<note>
<simpara>
- This function may not work on Windows systems.
+ This function may not work on Windows systems.
</simpara>
</note>
</refsect1>
- Next message: Luca Perugini: "[PHP-DOC] cvs: phpdoc /it/functions ftp.xml"
- Previous message: Luca Perugini: "[PHP-DOC] cvs: phpdoc /it/functions filepro.xml"
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]