cvs: phpdoc /pt_BR/functions filesystem.xml

jpm Thu Nov 15 09:59:55 2001 EDT Modified files: /phpdoc/pt_BR/functions filesystem.xml Log: More fixes on entities as examplified by derick

Index: phpdoc/pt_BR/functions/filesystem.xml diff -u phpdoc/pt_BR/functions/filesystem.xml:1.4 phpdoc/pt_BR/functions/filesystem.xml:1.5 --- phpdoc/pt_BR/functions/filesystem.xml:1.4 Thu Nov 15 05:35:35 2001 +++ phpdoc/pt_BR/functions/filesystem.xml Thu Nov 15 09:59:55 2001 @@ -1,2959 +1,2959 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> - <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 &true; se obtiver sucesso; caso contrário retorna - &false;. - </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...&lt;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 "&lt;p&gt; $num campos na linha $row: &lt;br&gt;"; - $row++; - for ($c=0; $c&lt;$num; $c++) { - print $data[$c] . "&lt;br&gt;"; - } -} -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"> -&lt;?php -// get a web page into an array and print it out -$fcontents = file ('http://www.php.net'); -while (list ($line_num, $line) = each ($fcontents)) { - echo "&lt;b&gt;Line $line_num:&lt;/b&gt; " . htmlspecialchars ($line) . "&lt;br&gt;\n"; -} - -// get a web page into a string -$fcontents = join ('', file ('http://www.php.net')); -?&gt; - </programlisting> - </informalexample> - </para> - <para> - See also <function>readfile</function>, - <function>fopen</function>, <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:password@example.com/", "w"); - </programlisting> - </example> - </para> - <simpara> - If you are experiencing problems with reading and writing to - files and you're using the server module version of PHP, remember - to make sure that the files and directories you're using are - accessible to the server process. - </simpara> - <para> - On the Windows platform, be careful to escape any backslashes - used in the path to the file, or use forward slashes. - <informalexample> - <programlisting role="php"> -$fp = fopen ("c:\\data\\info.txt", "r"); - </programlisting> - </informalexample> - </para> - <simpara> - See also <function>fclose</function>, - <function>fsockopen</function>, - <function>socket_set_timeout</function>, and - <function>popen</function>. - </simpara> - </refsect1> - </refentry> - - <refentry id="function.fpassthru"> - <refnamediv> - <refname>fpassthru</refname> - <refpurpose> - Output all remaining data on a file pointer - </refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>fpassthru</function></funcdef> - <paramdef>int <parameter>fp</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - Reads to EOF on the given file pointer and writes the results to - standard output. - </simpara> - <simpara> - If an error occurs, <function>fpassthru</function> returns - &false;. - </simpara> - <simpara> - The file pointer must be valid, and must point to a file - successfully opened by <function>fopen</function>, - <function>popen</function>, or <function>fsockopen</function>. - The file is closed when <function>fpassthru</function> is done - reading it (leaving <parameter>fp</parameter> useless). - </simpara> - <simpara> - If you just want to dump the contents of a file to stdout you may - want to use the <function>readfile</function>, which saves you - the <function>fopen</function> call. - </simpara> - <simpara> - See also <function>readfile</function>, - <function>fopen</function>, <function>popen</function>, and - <function>fsockopen</function> - </simpara> - </refsect1> - </refentry> - - <refentry id="function.fputs"> - <refnamediv> - <refname>fputs</refname> - <refpurpose>Writes to a file pointer</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>int <function>fputs</function></funcdef> - <paramdef>int <parameter>fp</parameter></paramdef> - <paramdef>string <parameter>str</parameter></paramdef> - <paramdef>int - <parameter> - <optional>length</optional> - </parameter> - </paramdef> - </funcprototype> - </funcsynopsis> - <para> - <function>fputs</function> is an alias to - <function>fwrite</function>, and is identical in every way. Note - that the <parameter>length</parameter> parameter is optional and - if not specified the entire string will be written. - </para> - </refsect1> - </refentry> - - <refentry id="function.fread"> - <refnamediv> - <refname>fread</refname> - <refpurpose>Binary-safe file read</refpurpose> - </refnamediv> - <refsect1> - <title>Description</title> - <funcsynopsis> - <funcprototype> - <funcdef>string <function>fread</function></funcdef> - <paramdef>int <parameter>fp</parameter></paramdef> - <paramdef>int <parameter>length</parameter></paramdef> - </funcprototype> - </funcsynopsis> - <simpara> - <function>fread</function> reads up to - <parameter>length</parameter> bytes from the file pointer - referenced by <parameter>fp</parameter>. Reading stops when - <parameter>length</parameter> bytes have been read or EOF is - reached, whichever comes first. - </simpara> - <para> - <informalexample> - <programlisting role="php"> -// get contents of a file into a string -$filename = "/usr/local/something.txt"; -$fd = fopen ($filename, "r"); -$contents = fread ($fd, filesize ($filename)); -fclose ($fd); - </programlisting> - </informalexample> - </para> - <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> - - &note.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"> -&lt;?php - -$path_parts = pathinfo("/www/htdocs/index.html"); - -echo $path_parts["dirname"] . "\n"; -echo $path_parts["basename"] . "\n"; -echo $path_parts["extension"] . "\n"; - -?&gt; - </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 &amp; 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 ---> +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- $Revision: 1.5 $ --> + <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 &true; se obtiver sucesso; caso contrário retorna + &false;. + </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 &true; se obtiver sucesso e caso contrário &false;. + </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 &true; se obtiver sucesso e caso contrário &false;. + </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 &true; se a copia é + obtida com sucesso, caso contrário &false;. + <example> + <title>exemplo do <function>copy</function></title> + <programlisting role="php"> +if (!copy($arquivo, $arquivo.'.bak')) { + print ("erro ao copiar $arquivo...&lt;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 &true; se obtiver sucesso e caso contrário + &false;. + </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 &true; se obtiver o ponteiro estiver no fim do arquivo + (eof) ou um erro ocorrer, caso contrário retorna &false;. + </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 &true; se obtiver sucesso e caso contrário + &false;. + </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 &false; 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 &false; 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 "&lt;p&gt; $num campos na linha $row: &lt;br&gt;"; + $row++; + for ($c=0; $c&lt;$num; $c++) { + print $data[$c] . "&lt;br&gt;"; + } +} +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 &false;. + </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"> +&lt;?php +// get a web page into an array and print it out +$fcontents = file ('http://www.php.net'); +while (list ($line_num, $line) = each ($fcontents)) { + echo "&lt;b&gt;Line $line_num:&lt;/b&gt; " . htmlspecialchars ($line) . "&lt;br&gt;\n"; +} + +// get a web page into a string +$fcontents = join ('', file ('http://www.php.net')); +?&gt; + </programlisting> + </informalexample> + </para> + <para> + See also <function>readfile</function>, + <function>fopen</function>, <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:password@example.com/", "w"); + </programlisting> + </example> + </para> + <simpara> + If you are experiencing problems with reading and writing to + files and you're using the server module version of PHP, remember + to make sure that the files and directories you're using are + accessible to the server process. + </simpara> + <para> + On the Windows platform, be careful to escape any backslashes + used in the path to the file, or use forward slashes. + <informalexample> + <programlisting role="php"> +$fp = fopen ("c:\\data\\info.txt", "r"); + </programlisting> + </informalexample> + </para> + <simpara> + See also <function>fclose</function>, + <function>fsockopen</function>, + <function>socket_set_timeout</function>, and + <function>popen</function>. + </simpara> + </refsect1> + </refentry> + + <refentry id="function.fpassthru"> + <refnamediv> + <refname>fpassthru</refname> + <refpurpose> + Output all remaining data on a file pointer + </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>fpassthru</function></funcdef> + <paramdef>int <parameter>fp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + Reads to EOF on the given file pointer and writes the results to + standard output. + </simpara> + <simpara> + If an error occurs, <function>fpassthru</function> returns + &false;. + </simpara> + <simpara> + The file pointer must be valid, and must point to a file + successfully opened by <function>fopen</function>, + <function>popen</function>, or <function>fsockopen</function>. + The file is closed when <function>fpassthru</function> is done + reading it (leaving <parameter>fp</parameter> useless). + </simpara> + <simpara> + If you just want to dump the contents of a file to stdout you may + want to use the <function>readfile</function>, which saves you + the <function>fopen</function> call. + </simpara> + <simpara> + See also <function>readfile</function>, + <function>fopen</function>, <function>popen</function>, and + <function>fsockopen</function> + </simpara> + </refsect1> + </refentry> + + <refentry id="function.fputs"> + <refnamediv> + <refname>fputs</refname> + <refpurpose>Writes to a file pointer</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>fputs</function></funcdef> + <paramdef>int <parameter>fp</parameter></paramdef> + <paramdef>string <parameter>str</parameter></paramdef> + <paramdef>int + <parameter> + <optional>length</optional> + </parameter> + </paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>fputs</function> is an alias to + <function>fwrite</function>, and is identical in every way. Note + that the <parameter>length</parameter> parameter is optional and + if not specified the entire string will be written. + </para> + </refsect1> + </refentry> + + <refentry id="function.fread"> + <refnamediv> + <refname>fread</refname> + <refpurpose>Binary-safe file read</refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>string <function>fread</function></funcdef> + <paramdef>int <parameter>fp</parameter></paramdef> + <paramdef>int <parameter>length</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <simpara> + <function>fread</function> reads up to + <parameter>length</parameter> bytes from the file pointer + referenced by <parameter>fp</parameter>. Reading stops when + <parameter>length</parameter> bytes have been read or EOF is + reached, whichever comes first. + </simpara> + <para> + <informalexample> + <programlisting role="php"> +// get contents of a file into a string +$filename = "/usr/local/something.txt"; +$fd = fopen ($filename, "r"); +$contents = fread ($fd, filesize ($filename)); +fclose ($fd); + </programlisting> + </informalexample> + </para> + <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> + + &note.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"> +&lt;?php + +$path_parts = pathinfo("/www/htdocs/index.html"); + +echo $path_parts["dirname"] . "\n"; +echo $path_parts["basename"] . "\n"; +echo $path_parts["extension"] . "\n"; + +?&gt; + </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 &amp; 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 +-->