rarruda Tue Nov 13 22:07:44 2001 EDT
Modified files:
/phpdoc/pt_BR/functions filesystem.xml
Log:
Initial translation up to fgets function.
Index: phpdoc/pt_BR/functions/filesystem.xml
diff -u /dev/null phpdoc/pt_BR/functions/filesystem.xml:1.3
--- /dev/null Tue Nov 13 22:07:44 2001
+++ phpdoc/pt_BR/functions/filesystem.xml Tue Nov 13 22:07:43 2001
@@ -0,0 +1,2959 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.3 $ -->
+ <reference id="ref.filesystem">
+ <title>Fun��es do Filesystem</title>
+ <titleabbrev>Filesystem</titleabbrev>
+
+ <refentry id="function.basename">
+ <refnamediv>
+ <refname>basename</refname>
+ <refpurpose>
+ Retorna a parte do nome do arquivo do path
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>basename</function></funcdef>
+ <paramdef>string <parameter>path</parameter></paramdef>
+ <paramdef>string <parameter><optional>suffixo</optional></parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Dado uma string contendo um path para um arquivo, essa fun��o ir�
+ retornar o nome base do arquivo.
+ Se o nome do arquivo � terminado em um <parameter>suffixo</parameter>
+ este tambem ser� retirado.
+ </para>
+ <para>
+ No Windows, tanto a barra (<literal>/</literal>) quanto a
+ barrainvertida (<literal>\</literal>) s�o usadas como caracter de
+ separacao do path. Em outros ambientes, somente a barra
+ (<literal>/</literal>).
+ </para>
+ <para>
+ <example>
+ <title>exemplo do <function>basename</function></title>
+ <programlisting role="php">
+$path = "/home/httpd/html/index.php";
+$arquivo = basename ($path); // $arquivo conter� "index.php"
+$arquivo = basename ($path,".php"); // $arquivo conter� "index"
+ </programlisting>
+ </example>
+ </para>
+ <note>
+ <para>
+ O parametro <parameter>suffixo</parameter> foi adicionado no PHP 4.1.0.
+ </para>
+ </note>
+ <para>
+ Veja tamb�m: <function>dirname</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.chgrp">
+ <refnamediv>
+ <refname>chgrp</refname>
+ <refpurpose>Modifica o grupo do arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>chgrp</function></funcdef>
+ <paramdef>string <parameter>arquivo</parameter></paramdef>
+ <paramdef>mixed <parameter>grupo</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Tenta modificar o grupo do
+ <parameter>arquivo</parameter> para o
+ <parameter>grupo</parameter>. Somente o superusu�rio pode mudar
+ o grupo de um arquivo arbitr�rio; outros usu�rios podem somente
+ mudar o grupo de um arquivo para qual o usu�rio pertence.
+ </para>
+ <para>
+ Retorna &verdadeiro; se obtiver sucesso; caso contr�rio retorna
+ &falso;.
+ </para>
+ <para>
+ Veja tamb�m <function>chown</function> e
+ <function>chmod</function>.
+ </para>
+ <note>
+ <simpara>
+ Esta fun��o n�o funciona em sistemas Windows.
+ </simpara>
+ </note>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.chmod">
+ <refnamediv>
+ <refname>chmod</refname>
+ <refpurpose>Modifica as permiss�es do arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>chmod</function></funcdef>
+ <paramdef>string <parameter>arquivo</parameter></paramdef>
+ <paramdef>int <parameter>modo</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Tenta mudar as permiss�es do arquivo especificado por
+ <parameter>arquivo</parameter> para o dado em
+ <parameter>modo</parameter>.
+ </para>
+ <para>
+ Note que <parameter>mode</parameter> n�o � assumido ser um numero
+ octal, ent�o strings (como "g+w") n�o ir� funcionar. Para garantir
+ que a opera��o seja bem sucedide � necess�rio o prefixo zero (0)
+ em <parameter>mode</parameter>:
+ <informalexample>
+ <programlisting role="php">
+chmod ("/algumdir/algumarquivo", 755); // decimal; provavelmente incorreto
+chmod ("/algumdir/algumarquivo", "u+rwx,go+rx"); // string; incorreto
+chmod ("/algumdir/algumarquivo", 0755); // octal; correto valor da permiss�o
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ Retorna &verdadeiro; se obtiver sucesso e caso contr�rio &falso;.
+ </para>
+ <para>
+ Veja tamb�m <function>chown</function> e
+ <function>chgrp</function>.
+ </para>
+ <note>
+ <simpara>
+ Esta fun��o n�o funciona em sistemas Windows.
+ </simpara>
+ </note>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.chown">
+ <refnamediv>
+ <refname>chown</refname>
+ <refpurpose>Modifica o dono do arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>chown</function></funcdef>
+ <paramdef>string <parameter>arquivo</parameter></paramdef>
+ <paramdef>mixed <parameter>usu�rio</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Tenta modificar o dono do arquivo "arquivo" para o usu�rio
+ "usu�rio". Somente o superusu�rio pode modificar o dono de
+ um arquivo.
+ </para>
+ <para>
+ Retorna &verdadeiro; se obtiver sucesso e caso contr�rio &falso;.
+ </para>
+ <para>
+ Veja tamb�m <function>chown</function> e
+ <function>chmod</function>.
+ </para>
+ <note>
+ <simpara>
+ Esta fun��o n�o funciona em sistemas Windows.
+ </simpara>
+ </note>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.clearstatcache">
+ <refnamediv>
+ <refname>clearstatcache</refname>
+ <refpurpose>Limpa o cache do file stat</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>clearstatcache</function></funcdef>
+ <void/>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Invocando a fun��o do sistema (system call)
+ <systemitem>stat</systemitem> ou <systemitem>lstat</systemitem>
+ na maior parte do sistema � bem caro. Ent�o, o resultado da ultima
+ chamada para qualquer chamada para as fun��es de status (listadas
+ abaixo) � guardada para a ultiliza��o nas possiveis procimas
+ chamadas utilizando o mesmo nome de arquivo. Se voce deseja forcar
+ um check no status, por exemplo se o arquivo for checado muitas
+ vezes e pode mudar ou disaparecer, use esta fun��o para limpar os
+ resultados da ultima chamada da mem�ria.
+ </para>
+ <para>
+ Este valor somente reside no cache pelo tempo de somente um pedido.
+ </para>
+ <para>
+ As fun��es afetadas s�o <function>stat</function>,
+ <function>lstat</function>,
+ <function>file_exists</function>,
+ <function>is_writable</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>, e
+ <function>fileperms</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.copy">
+ <refnamediv>
+ <refname>copy</refname>
+ <refpurpose>Copia arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>copy</function></funcdef>
+ <paramdef>string <parameter>origem</parameter></paramdef>
+ <paramdef>string <parameter>destino</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Faz uma c�pia de um arquivo. Retorna &verdadeiro; se a copia �
+ obtida com sucesso, caso contr�rio &falso;.
+ <example>
+ <title>exemplo do <function>copy</function></title>
+ <programlisting role="php">
+if (!copy($arquivo, $arquivo.'.bak')) {
+ print ("erro ao copiar $arquivo...<br>\n");
+}
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Veja tamb�m: <function>rename</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.delete">
+ <refnamediv>
+ <refname>delete</refname>
+ <refpurpose>Uma se��o dipens�vel do manual</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>void <function>delete</function></funcdef>
+ <paramdef>string <parameter>file</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Esta � uma se��o dispens�vel do manual criada para satisfazer
+ as pessoas que est�o procurando por <function>unlink</function>
+ ou <function>unset</function> no lugar errado.
+ </para>
+ <para>
+ Veja tamb�m: <function>unlink</function> para deletar arquivos,
+ <function>unset</function> para apagar v�riaveis.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.dirname">
+ <refnamediv>
+ <refname>dirname</refname>
+ <refpurpose>Retorna o nome do diret�rio componente do path</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>dirname</function></funcdef>
+ <paramdef>string <parameter>path</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Dada uma string contendo um path para um arquivo, esta fun��o
+ ir� retornar o nome do diret�rio.
+ </para>
+ <para>
+ No Windows, tanto barra (<literal>/</literal>) quanto a
+ barrainvertida (<literal>\</literal>) s�o usadas como caracter
+ separador no path. Em outros ambientes � utilizado a barra
+ (<literal>/</literal>).</para>
+ <para>
+ <example>
+ <title>exemplo do <function>dirname</function></title>
+ <programlisting role="php">
+$path = "/etc/passwd";
+$file = dirname ($path); // $file is set to "/etc"
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Veja tamb�m: <function>basename</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.disk-free-space">
+ <refnamediv>
+ <refname>disk_free_space</refname>
+ <refpurpose>Retorna o espa�o disponivel no diret�rio.</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>disk_free_space</function></funcdef>
+ <paramdef>string <parameter>diret�rio</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Dado uma string contendo um diret�rio, esta fun��o retornar� o
+ numero de bytes dispon�veis no correspondente filesystem ou
+ parti��o de disco.
+ </para>
+ <para>
+ <example>
+ <title>exemplo de <function>disk_free_space</function></title>
+ <programlisting role="php">
+$df = disk_free_space("/"); // $df cont�m o n�mero de bytes.
+ // dispon�vel em "/"
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.diskfreespace">
+ <refnamediv>
+ <refname>diskfreespace</refname>
+ <refpurpose>Sin�nimo de <function>disk_free_space</function></refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>diskfreespace</function></funcdef>
+ <paramdef>string <parameter>diret�rio</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Este � um sin�nimo obsoleto para a fun��o
+ <function>disk_free_space</function>.
+ Ultilize aquela fun��o ao invez.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.disk-total-space">
+ <refnamediv>
+ <refname>disk_total_space</refname>
+ <refpurpose>Retorna o tamanho total do diret�rio</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>float <function>disk_total_space</function></funcdef>
+ <paramdef>string <parameter>diret�rio</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Dado uma string contendo um diret�rio, esta fun��o retornar� o
+ numero total de bytes correspondendo ao filesystem ou a parti��o
+ de disco.
+ </para>
+ <para>
+ <example>
+ <title><function>disk_total_space</function> example</title>
+ <programlisting role="php">
+$df = disk_total_space("/"); // $df cont�m o numero total de
+ // bytes dispon�veis em "/"
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.fclose">
+ <refnamediv>
+ <refname>fclose</refname>
+ <refpurpose>Fecha um ponteiro de arquivo aberto</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>fclose</function></funcdef>
+ <paramdef>int <parameter>fp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ O arquivo apontado por <parameter>fp</parameter> � fechado.
+ </para>
+ <para>
+ Retorna &verdadeiro; se obtiver sucesso e caso contr�rio
+ &falso;.
+ </para>
+ <para>
+ O ponteiro para o arquivo tem que ser v�lido e tem que
+ apontar para um arquivo aberto por <function>fopen</function>
+ ou <function>fsockopen</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.feof">
+ <refnamediv>
+ <refname>feof</refname>
+ <refpurpose> Testa por fim-de-arquivo (eof) em um ponteiro de arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>feof</function></funcdef>
+ <paramdef>int <parameter>fp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Retorna &verdadeiro; se obtiver o ponteiro estiver no fim do arquivo
+ (eof) ou um erro ocorrer, caso contr�rio retorna &falso;.
+ </para>
+ <para>
+ O ponteir para o arquivo tem que ser v�lido e tem que apontar para
+ um arquivo aberto com sucesso por <function>fopen</function>,
+ <function>popen</function>, ou <function>fsockopen</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.fflush">
+ <refnamediv>
+ <refname>fflush</refname>
+ <refpurpose>Forca a ida da saida para o arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>int <function>fflush</function></funcdef>
+ <paramdef>int <parameter>fp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Esta fun��o forca que toda a sa�da que est� no buffer
+ para qual o arquivo est� apontado pelo
+ <parameter>fp</parameter> seja escrita.
+ Retorna &verdadeiro; se obtiver sucesso e caso contr�rio
+ &falso;.
+ </para>
+ <para>
+ O ponteiro de arquivo tem que ser v�lido e apontar para
+ um arquivo que foi aberto com sucesso por
+ <function>fopen</function>, <function>popen</function>,
+ ou <function>fsockopen</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.fgetc">
+ <refnamediv>
+ <refname>fgetc</refname>
+ <refpurpose>L� caracter do ponteiro de arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>fgetc</function></funcdef>
+ <paramdef>int <parameter>fp</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Retorna uma string contendo somente um caracter lido do arquivo
+ apontado por fp. Retorna &falso; no fim do arquivo (eof).
+ </para>
+ <para>
+ O ponteiro de arquivo tem que ser v�lido e apontar para um
+ arquivo aberto com sucesso por <function>fopen</function>,
+ <function>popen</function>, ou <function>fsockopen</function>.
+ </para>
+ <para>
+ Veja tamb�m <function>fread</function>, <function>fopen</function>,
+ <function>popen</function>, <function>fsockopen</function>, e
+ <function>fgets</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.fgetcsv">
+ <refnamediv>
+ <refname>fgetcsv</refname>
+ <refpurpose>
+ Ler uma linha do ponteiro de arquivos e parse por campos CSV
+ </refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>fgetcsv</function></funcdef>
+ <paramdef>int <parameter>fp</parameter></paramdef>
+ <paramdef>int <parameter>comprimento</parameter></paramdef>
+ <paramdef>string
+ <parameter>
+ <optional>delimitador</optional>
+ </parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <simpara>
+ Similar � <function>fgets</function> exceto que
+ <function>fgetcsv</function> parses a linha que l� por campos
+ no formato <acronym>CSV</acronym> e retorna um vetor (array)
+ contendo os campos lidos. O delimitador dos campos � a virgula,
+ a menos que seja especificado com o terceiro parametro que �
+ opcional.
+ </simpara>
+ <simpara>
+ <parameter>Fp</parameter> tem que ser um ponteiro de arquivo
+ v�lido para um arquivo aberto com sucesso por
+ <function>fopen</function>, <function>popen</function>,
+ ou <function>fsockopen</function>
+ </simpara>
+ <simpara>
+ Comprimento tem que ser maior do que a maior linha a ser encontrada
+ no arquivo CSV (incluindo caracteres de termina��o de linha).
+ </simpara>
+ <simpara>
+ <function>fgetcsv</function> retorna &falso; ao encontrar um erro,
+ incluindo fim de arquivo (eof).
+ </simpara>
+ <simpara>
+ N.B. Uma linha em branco em um arquivo CSV ser� retornada como um
+ vetor contendo um �nico campo nulo (&null;), e n�o ser� tratado
+ como um erro.
+ </simpara>
+ <example>
+ <title>
+ exemplo de <function>fgetcsv</function> - Ler e imprimir os conte�dos
+ inteiros de um arquivo CSV.
+ </title>
+ <programlisting role="php">
+$row = 1;
+$fp = fopen ("test.csv","r");
+while ($data = fgetcsv ($fp, 1000, ",")) {
+ $num = count ($data);
+ print "<p> $num campos na linha $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>L� a linha de um ponteiro de arquivo</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Descri��o</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>string <function>fgets</function></funcdef>
+ <paramdef>int <parameter>fp</parameter></paramdef>
+ <paramdef>int <parameter>comprimento</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Retorna uma string com at� comprimento - 1 bytes lidos do arquivo
+ apontado por fp. A leitura acaba quando comprimento - 1 bytes
+ foram lidos, em uma nova linha (newline) (que � incluida no valor
+ retornado), ou em um fim de arquivo (eof) (o que acontecer
+ primeiro).
+ </para>
+ <para>
+ Se um erro ocorrer, retorna &falso;.
+ </para>
+ <para>
+ Equivocos comuns:
+ </para>
+ <simpara>
+ Pessoas acostumadas a semantica do fgets em 'C' devem notar a
+ diferenca em como o fim do arquivo (eof) � retornado.
+ </simpara>
+ <simpara>
+ O ponteiro para o arquivo deve ser v�lido e deve apontar para um
+ arquivo aberto com sucesso por <function>fopen</function>,
+ <function>popen</function>, ou
+ <function>fsockopen</function>.
+ </simpara>
+ <para>
+ Um simples exemplo segue:
+ <example>
+ <title>Lendo um arquivo linha a linha</title>
+ <programlisting role="php">
+$fd = fopen ("/tmp/arquivodeentrada.txt", "r");
+while (!feof ($fd)) {
+ $buffer = fgets($fd, 4096);
+ echo $buffer;
+}
+fclose ($fd);
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Veja tamb�m <function>fread</function>, <function>fopen</function>,
+ <function>popen</function>, <function>fgetc</function>,
+ <function>fsockopen</function>, e
+ <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>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; 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 application 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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </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 filesystems, a file is considered
+ changed when its inode data is changed; that is, when
+ the permissions, owner, group, or other metadata
+ from the inode is updated. See also
+ <function>filemtime</function> (which is what you want to use
+ when you want to create "Last Modified" footers on web pages) and
+ <function>fileatime</function>.
+ </para>
+ <para>Note also that in some Unix texts the ctime of a file is
+ referred to as being the creation time of the file. This is wrong.
+ There is no creation time for Unix files in most Unix filesystems.
+ </para>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ </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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ </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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ </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>
+ <warning>
+ <para>
+ On most operation systems <function>flock</function> is implemented
+ at the process level. When using a multithreaded server API like
+ ISAPI you cannot rely on <function>flock</function> to protect
+ files against other PHP scripts running in parallel threads of the
+ same server instance!
+ </para>
+ </warning>
+ </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, the page is requested using the HTTP GET
+ method, and a file pointer is returned to the beginning
+ of the body of the response. A 'Host:' header is sent with the
+ request in order to handle name-based virtual hosts.
+ </simpara>
+ <simpara>
+ Note that the file pointer allows you to retrieve only the
+ <emphasis>body</emphasis> of the response; you cannot
+ access the HTTP response header using this function.
+ </simpara>
+ <simpara>
+ Versions prior to PHP 4.0.5 do not handle HTTP redirects. Because
+ of this, directories must include trailing slashes.
+ </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 or 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>
+ </para>
+ <note>
+ <para>
+ The <parameter>mode</parameter> may contain the letter
+ 'b'. This is useful only on systems which differentiate between
+ binary and text files (i.e. Windows. It's useless on Unix).
+ If not needed, this will be ignored.
+ </para>
+ </note>
+ <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:[EMAIL PROTECTED]/";, "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>
+ <note>
+ <para>
+ On systems which differentiate between binary and text files
+ (i.e. Windows) the file must be opened with 'b' included in
+ <function>fopen</function> mode parameter.
+ </para>
+ </note>
+ <para>
+ <informalexample>
+ <programlisting role="php">
+$filename = "c:\\files\\somepic.gif";
+$fd = fopen ($filename, "rb");
+$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>
+ <note>
+ <para>
+ On systems which differentiate between binary and text files
+ (i.e. Windows) the file must be opened with 'b' included in
+ <function>fopen</function> mode parameter.
+ </para>
+ </note>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <para>
+ See also <function>is_writable</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.is-writable">
+ <refnamediv>
+ <refname>is_writable</refname>
+ <refpurpose>Tells whether the filename is writable</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>is_writable</function></funcdef>
+ <paramdef>string <parameter>filename</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ Returns &true; if the filename exists and is writable. 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>
+ <simpara>
+ This function will not work on <link
+ linkend="features.remote-files">remote files</link>; the file to
+ be examined must be accessible via the server's filesystem.
+ </simpara>
+ <para>
+ See also <function>is_readable</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.is-writeable">
+ <refnamediv>
+ <refname>is_writeable</refname>
+ <refpurpose>Tells whether the filename is writable</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>bool <function>is_writeable</function></funcdef>
+ <paramdef>string <parameter>filename</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ This is an alias for <function>is_writable</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.
+ The mode is also modified by the current umask, which you
+ can change using <function>umask</function>.
+ <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
+ &false;.
+ </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
+ &false;. 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>
+
+ ¬e.sm.uidcheck;
+
+ <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.parse-ini-file">
+ <refnamediv>
+ <refname>parse_ini_file</refname>
+ <refpurpose>Parse a configuration file</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>parse_ini_file</function></funcdef>
+ <paramdef>string <parameter>filename</parameter></paramdef>
+ <paramdef>bool
+ <parameter>
+ <optional>process_sections</optional>
+ </parameter>
+ </paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>parse_ini_file</function> loads in the
+ ini file specified in <parameter>filename</parameter>,
+ and returns the settings in it in an associative array.
+ By setting the last <parameter>process_sections</parameter>
+ parameter to &true;, you get a multidimensional array, with
+ the section names and settings included. The default
+ for <parameter>process_sections</parameter> is &false;
+ </para>
+ <note>
+ <para>
+ This function has nothing to do with the
+ <filename>php.ini</filename> file. It is already processed,
+ the time you run your script. This function can be used to
+ read in your own application's configuration files.
+ </para>
+ </note>
+ <para>
+ The structure of the ini file is similar to that of
+ the <filename>php.ini</filename>'s.
+ </para>
+ <para>
+ <example>
+ <title>Contents of sample.ini</title>
+ <programlisting>
+; This is a sample configuration file
+; Comments start with ';', as in php.ini
+
+[first_section]
+one = 1
+five = 5
+
+[second_section]
+path = /usr/local/bin
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title><function>parse_ini_file</function> example</title>
+ <programlisting>
+<![CDATA[
+<?php
+
+// Parse without sections
+$ini_array = parse_ini_file("sample.ini");
+print_r($ini_array);
+
+// Parse with sections
+$ini_array = parse_ini_file("sample.ini", TRUE);
+print_r($ini_array);
+
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Would produce:
+ <informalexample>
+ <programlisting>
+Array
+(
+ [one] => 1
+ [five] => 5
+ [path] => /usr/local/bin
+)
+Array
+(
+ [first_section] => Array
+ (
+ [one] => 1
+ [five] => 5
+ )
+
+ [second_section] => Array
+ (
+ [path] => /usr/local/bin
+ )
+
+)
+ </programlisting>
+ </informalexample>
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="function.pathinfo">
+ <refnamediv>
+ <refname>pathinfo</refname>
+ <refpurpose>Returns information about a file path</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <funcsynopsis>
+ <funcprototype>
+ <funcdef>array <function>pathinfo</function></funcdef>
+ <paramdef>string <parameter>path</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ <para>
+ <function>pathinfo</function> returns an associative array
+ containing information about <parameter>path</parameter>. The
+ following array elements are returned:
+ <parameter>dirname</parameter>, <parameter>basename</parameter>
+ and <parameter>extension</parameter>.
+ </para>
+ <para>
+ <example>
+ <title><function>pathinfo</function> Example</title>
+ <programlisting role="php">
+<?php
+
+$path_parts = pathinfo("/www/htdocs/index.html");
+
+echo $path_parts["dirname"] . "\n";
+echo $path_parts["basename"] . "\n";
+echo $path_parts["extension"] . "\n";
+
+?>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Would produce:
+ <informalexample>
+ <programlisting>
+/www/htdocs
+index.html
+html
+ </programlisting>
+ </informalexample>
+ </para>
+ <para>
+ See also <function>dirname</function>,
+ <function>basename</function>, <function>parse_url</function>
+ and <function>realpath</function>.
+ </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>
+ Versions prior to PHP 4.0.5 do not handle HTTP redirects. Because
+ of this, directories must include trailing slashes.
+ </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>
+ Returns &false; in case of error.
+ </para>
+ <para>
+ <function>stat</function> doesn't handle URL as does <function>fopen</function>.
+ </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>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.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>
+ Prior to PHP 4.0.6, the behaviour of the
+ <function>tempnam</function> function was 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>
+ <note>
+ <simpara>
+ This function's behavior changed in 4.0.3. The temporary file is also
+ created to avoid a race condition where the file might appear in the
+ filesystem between the time the string was generated and before the
+ the script gets around to creating the file.
+ </simpara>
+ </note>
+ <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>
+ <void/>
+ </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>
+ <note>
+ <simpara>
+ This function may not work on Windows systems.
+ </simpara>
+ </note>
+ </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:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
