From 6946eeb075d0bb31d7e682254865598ca0b5c478 Mon Sep 17 00:00:00 2001 From: Egon Schmid Date: Mon, 20 Dec 1999 22:26:22 +0000 Subject: [PATCH] Minor cosmetic correction and left some more work. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@17646 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/filesystem.xml | 748 ++++++++++++++++++++++----------------- 1 file changed, 414 insertions(+), 334 deletions(-) diff --git a/functions/filesystem.xml b/functions/filesystem.xml index db6e280f6b..cd53decab9 100644 --- a/functions/filesystem.xml +++ b/functions/filesystem.xml @@ -15,27 +15,29 @@ Given a string containing a path to a file, this function will - return the base name of the file. + return the base name of the file. + On Windows, both slash (/) and backslash (\) are used as path separator character. In other environments, it is the forward slash - (/). + (/). + - <function>basename</function> example - + + <function>basename</function> example + $path = "/home/httpd/html/index.php3"; $file = basename($path); // $file is set to "index.php3" - - - + + + - See also: - dirname + See also: dirname + - chgrp @@ -52,17 +54,21 @@ $file = basename($path); // $file is set to "index.php3" Attempts to change the group of the file filename to group. Only the superuser may change the group of a file arbitrarily; other users may change the group of a file to any group of which that - user is a member. + user is a member. + - Returns true on success; otherwise returns false. + Returns true on success; otherwise returns false. + - On Windows, does nothing and returns true. + On Windows, does nothing and returns true. + - See also chown and chmod. + See also chown and + chmod. + - chmod @@ -78,29 +84,29 @@ $file = basename($path); // $file is set to "index.php3" Attempts to change the mode of the file specified by filename to that given in - mode. - + mode. + Note that mode is not automatically assumed to be an octal value. To ensure the expected operation, you need to prefix mode with a zero (0): - - + chmod( "/somedir/somefile", 755 ); // decimal; probably incorrect chmod( "/somedir/somefile", 0755 ); // octal; correct value of mode - - + + - Returns true on success and false otherwise. - + Returns true on success and false otherwise. + - See also chown and chgrp. + See also chown and + chgrp. + - chown @@ -115,22 +121,22 @@ chmod( "/somedir/somefile", 0755 ); // octal; correct value of mode Attempts to change the owner of the file filename to user - user. Only the superuser may change the owner of a file. - + user. Only the superuser may change the owner of a file. + Returns true on success; otherwise returns false. - - On Windows, does nothing and returns true. - - + On Windows, does nothing and returns true. + + + - See also chown and chmod. - + See also chown and + chmod. + - clearstatcache @@ -144,16 +150,17 @@ chmod( "/somedir/somefile", 0755 ); // octal; correct value of mode Invoking the stat or - lstat system call on most systems is quite - expensive. Therefore, the result of the last call to any of the - status functions (listed below) is stored for use on the next + lstat system call on most systems is + quite expensive. Therefore, the result of the last call to any of + the status functions (listed below) is stored for use on the next such call using the same filename. If you wish to force a new status check, for instance if the file is being checked many times and may change or disappear, use this function to clear the - results of the last call from memory. - - This value is only cached for the lifetime of a single request. - + results of the last call from memory. + + + This value is only cached for the lifetime of a single request. + Affected functions include stat, lstat, @@ -172,12 +179,11 @@ chmod( "/somedir/somefile", 0755 ); // octal; correct value of mode fileowner, filesize, filetype, and - fileperms. - + fileperms. + - copy @@ -193,17 +199,18 @@ chmod( "/somedir/somefile", 0755 ); // octal; correct value of mode Makes a copy of a file. Returns true if the copy succeeded, false otherwise. - <function>copy</function> example - + + <function>copy</function> example + if (!copy($file, $file.'.bak')) { print("failed to copy $file...<br>\n"); } - - - + + + - See also: - rename + See also: rename. + @@ -223,9 +230,9 @@ if (!copy($file, $file.'.bak')) { looking for unlink or unset in the wrong place. - See also: - unlink to delete files, unset - to delete variables. + See also: unlink to delete files, + unset to delete variables. + @@ -249,16 +256,17 @@ if (!copy($file, $file.'.bak')) { other environments, it is the forward slash (/). - <function>dirname</function> example - + + <function>dirname</function> example + $path = "/etc/passwd"; $file = dirname($path); // $file is set to "/etc" - - - + + + - See also: - basename + See also: basename + @@ -274,19 +282,21 @@ $file = dirname($path); // $file is set to "/etc" string directory - Given a string containing a directory, this function will - return the number of bytes available on the corresponding - disk. + Given a string containing a directory, this function will return + the number of bytes available on the corresponding disk. + - <function>diskfreespace</function> example - -$df = diskfreespace("/"); // $df contains the number of bytes available on "/" - - + + <function>diskfreespace</function> example + +$df = diskfreespace("/"); // $df contains the number of bytes + // available on "/" + + + - fclose @@ -299,20 +309,19 @@ $df = diskfreespace("/"); // $df contains the number of bytes available on "/" int fp - The file pointed to by fp is closed. - + The file pointed to by fp is closed. + - Returns true on success and false on failure. - + Returns true on success and false on failure. + The file pointer must be valid, and must point to a file successfully opened by fopen or - fsockopen. - + fsockopen. + - feof @@ -326,21 +335,20 @@ $df = diskfreespace("/"); // $df contains the number of bytes available on "/" Returns true if the file pointer is at EOF or an error occurs; - otherwise returns false. - + otherwise returns false. + The file pointer must be valid, and must point to a file successfully opened by fopen, - popen, or fsockopen. - + popen, or fsockopen. + - fgetc - get character from file pointer + Get character from file pointer Description @@ -355,19 +363,22 @@ $df = diskfreespace("/"); // $df contains the number of bytes available on "/" The file pointer must be valid, and must point to a file successfully opened by fopen, - popen, or fsockopen. - - See also fread, fopen, - popen, fsockopen, and - fgets. - + popen, or fsockopen. + + + See also fread, fopen, + popen, fsockopen, and + fgets. + fgetcsv - get line from file pointer and parse for CSV fields + + Get line from file pointer and parse for CSV fields + Description @@ -375,43 +386,57 @@ $df = diskfreespace("/"); // $df contains the number of bytes available on "/" array fgetcsv int fp int length - string delimiter + string + + delimiter + + - Similar to fgets() except that fgetcsv() parses the line it reads for - fields in CSV format and returns an array containing the fields read. - The field delimiter is a comma, unless you specifiy another - delimiter with the optional third parameter. + Similar to fgets() except that fgetcsv() parses the line it reads + for fields in CSV format and returns an array containing the + fields read. The field delimiter is a comma, unless you specifiy + another delimiter with the optional third parameter. + - fp must be a valid file pointer to a file successfully opened by - fopen, popen, or fsockopen - - length must be greater than the longest line to be found in the CSV - file (allowing for trailing line-end characters). - - fgetcsv() returns false on error, including end of file. - - NB A blank line in a CSV file will be returned as an array comprising - just one single null field, and will not be treated as an error. - - - fgetcsv() example - Read and print entire contents of a CSV file - -$row=1; -$fp = fopen("test.csv","r"); -while ($data = fgetcsv($fp,1000, ",")) { - $num = count($data); - print "<p> $num fields in line $row: <br>"; - $row++; - for ( $c=0; $c<$num; $c++ ) print $data[$c] . "<br>"; + fp must be a valid file pointer to a file successfully opened by + fopen, popen, or + fsockopen + + + length must be greater than the longest line to be found in the + CSV file (allowing for trailing line-end characters). + + + fgetcsv() returns false on error, including end of file. + + + NB A blank line in a CSV file will be returned as an array + comprising just one single null field, and will not be treated as + an error. + + + + <function>Fgetcsv</function> example - Read and print entire + contents of a CSV file + + +$row = 1; +$fp = fopen ("test.csv","r"); +while ($data = fgetcsv ($fp, 1000, ",")) { + $num = count ($data); + print "<p> $num fields in line $row: <br>"; + $row++; + for ($c=0; $c<$num; $c++) { + print $data[$c] . "<br>"; + } } -fclose($fp); - - +fclose ($fp); + + - fgets @@ -424,46 +449,50 @@ fclose($fp); int fp int length - Returns a string of up to length - 1 bytes read from the file pointed to by fp. Reading ends when length - 1 bytes have been - read, on a newline (which is included in the return value), or - on EOF (whichever comes first). - + read, on a newline (which is included in the return value), or on + EOF (whichever comes first). + - If an error occurs, returns false. + If an error occurs, returns false. + - Common Pitfalls: + Common Pitfalls: + - People used to the 'C' semantics of fgets should note the difference - in how EOF is returned. + People used to the 'C' semantics of fgets should note the + difference in how EOF is returned. + - The file pointer must be valid, and must point to a file + The file pointer must be valid, and must point to a file successfully opened by fopen, - popen, or fsockopen. - + popen, or + fsockopen. + - A simple example follows: - + A simple example follows: + Reading a file line by line -$fd = fopen("/tmp/inputfile.txt", "r"); +$fd = fopen ("/tmp/inputfile.txt", "r"); while (!feof($fd)) { - $buffer = fgets($fd, 4096); - echo $buffer; + $buffer = fgets($fd, 4096); + echo $buffer; } -fclose($fd); - - - See also fread, - fopen, popen, - fgetc, and fsockopen. - +fclose ($fd); + + + + + See also fread, fopen, + popen, fgetc, and + fsockopen. + - fgetss @@ -475,30 +504,36 @@ fclose($fd); string fgetss int fp int length - string allowable_tags + string + + allowable_tags + + - Identical to fgets, - except that fgetss attempts to strip any HTML and PHP tags from - the text it reads. + Identical to fgets, except that fgetss + attempts to strip any HTML and PHP tags from the text it + reads. + You can use the optional third parameter to specify tags which should not be stripped. - - - allowable_tags was added in PHP 3.0.13, PHP4B3. - - + + + allowable_tags was added in PHP 3.0.13, + PHP4B3. + + + See also fgets, fopen, - fsockopen, popen, - and strip_tags. - + fsockopen, popen, and + strip_tags. + - file @@ -509,26 +544,28 @@ fclose($fd); array file string filename - int use_include_path + int + use_include_path + - - Identical to readfile, except that file - returns the file in an array. Each element of the array corresponds - to a line in the file, with the newline still attached. - + Identical to readfile, except that + file returns the file in an array. Each + element of the array corresponds to a line in the file, with the + newline still attached. + You can use the optional second parameter and set it to "1", if - you want to search for the file in the include_path, too. - + you want to search for the file in the include_path, too. + See also readfile, - fopen, and popen. - + fopen, and popen. + - file_exists @@ -540,23 +577,21 @@ fclose($fd); int file_exists string filename - Returns true if the file specified by - filename exists; false otherwise. - + filename exists; false otherwise. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + - fileatime - get last access time of file + Get last access time of file Description @@ -564,19 +599,21 @@ fclose($fd); int fileatime string filename - Returns the time the file was last accessed, or false in case - of an error. + + Returns the time the file was last accessed, or false in case of + an error. + The results of this function are cached. See - clearstatcache for more details. + clearstatcache for more details. + - filectime - get inode change time of file + Get inode change time of file Description @@ -586,15 +623,15 @@ fclose($fd); Returns the time the file was last changed, or false in case of - an error. + an error. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + - filegroup @@ -606,20 +643,21 @@ fclose($fd); int filegroup string filename - Returns the group ID of the owner of the file, or false in case of an - error. + + Returns the group ID of the owner of the file, or false in case + of an error. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + - fileinode - get file inode + Get file inode Description @@ -632,16 +670,16 @@ fclose($fd); error. The results of this function are cached. See - clearstatcache for more details. + clearstatcache for more details. + - filemtime - get file modification time + Get file modification time Description @@ -651,19 +689,19 @@ fclose($fd); Returns the time the file was last modified, or false in case of - an error. + an error. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + - fileowner - get file owner + Get file owner Description @@ -671,16 +709,18 @@ fclose($fd); int fileowner string filename - Returns the user ID of the owner of the file, or false in case of an + + Returns the user ID of the owner of the file, or false in case of + an. + The results of this function are cached. See clearstatcache for more details. - error. - + error. + - fileperms @@ -693,15 +733,15 @@ fclose($fd); string filename - Returns the permissions on the file, or false in case of an error. + Returns the permissions on the file, or false in case of an error. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + - filesize @@ -713,15 +753,16 @@ fclose($fd); int filesize string filename - Returns the size of the file, or false in case of an error. + + Returns the size of the file, or false in case of an error. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + - filetype @@ -733,15 +774,15 @@ fclose($fd); string filetype string filename - Returns the type of the file. Possible values are - fifo, char, dir, - block, link, file, and - unknown. - Returns false if an error occurs. + + Returns the type of the file. Possible values are fifo, char, + dir, block, link, file, and unknown. Returns false + if an error occurs. + The results of this function are cached. See - clearstatcache for more details. - + clearstatcache for more details. + @@ -758,45 +799,52 @@ fclose($fd); int operation - 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). - + 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). + flock operates on fp which must be an open file pointer. operation is one of - the following values: - + the following values: + - - To acquire a shared lock (reader), set operation - to 1. - - - To acquire an exclusive lock (writer), set - operation to 2. - - - To release a lock (shared or exclusive), set - operation to 3. - - - If you don't want flock to block while locking, - add 4 to operation. - + + + To acquire a shared lock (reader), set + operation to 1. + + + + + To acquire an exclusive lock (writer), set + operation to 2. + + + + + To release a lock (shared or exclusive), set + operation to 3. + + + + + If you don't want flock to block while + locking, add 4 to operation. + + - - flock allows you to perform a simple reader/writer - model which can be used on virtually every platform (including most - Unices and even Windows). - + flock allows you to perform a simple + reader/writer model which can be used on virtually every platform + (including most Unices and even Windows). + - flock returns true on success and false on error - (e.g. when a lock could not be acquired). - + flock returns true on success and false on + error (e.g. when a lock could not be acquired). + @@ -811,100 +859,130 @@ fclose($fd); int fopen string filename string mode - int use_include_path + int + + use_include_path + + - If filename begins with "http://" (not case sensitive), an HTTP - 1.0 connection is opened to the specified server and a file - pointer is returned to the beginning of the text of the response. - + If filename begins with "http://" (not + case sensitive), an HTTP 1.0 connection is opened to the + specified server and a file pointer is returned to the beginning + of the text of the response. + Does not handle HTTP redirects, so you must include trailing - slashes on directories. - + slashes on directories. + - If filename begins with "ftp://" (not case sensitive), an ftp - connection to the specified server is opened and a pointer to the - requested file is returned. If the server does not support - passive mode ftp, this will fail. You can open files for either - reading and writing via ftp (but not both simultaneously). - + If filename begins with "ftp://" (not case + sensitive), an ftp connection to the specified server is opened + and a pointer to the requested file is returned. If the server + does not support passive mode ftp, this will fail. You can open + files for either reading and writing via ftp (but not both + simultaneously). + If filename begins with anything else, the file will be opened from the filesystem, and a file pointer to - the file opened is returned. - + the file opened is returned. + - If the open fails, the function returns false. - + If the open fails, the function returns false. + mode may be any of the following: - 'r' - Open for reading only; place the file - pointer at the beginning of the file. - - 'r+' - Open for reading and writing; place the file pointer at - the beginning of the file. - - '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. - - '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. - - '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. - - '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. + + + 'r' - Open for reading only; place the file pointer at the + beginning of the file. + + + + + 'r+' - Open for reading and writing; place the file pointer at + the beginning of the file. + + + + + '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. + + + + + '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. + + + + + '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. + + + + + '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. + + - As well, mode may contain the letter 'b'. This is useful only on systems which differentiate between binary and text files (i.e., it's useless on Unix). If not - needed, this will be ignored. - + needed, this will be ignored. + You can use the optional third parameter and set it to "1", if - you want to search for the file in the include_path, too. - + you want to search for the file in the include_path, too. + fopen() example - + $fp = fopen("/home/rasmus/file.txt", "r"); $fp = fopen("http://www.php.net/", "r"); $fp = fopen("ftp://user:password@example.com/", "w"); - - + + + If you are experiencing problems with reading and writing to - files and you're using the server module version of PHP, remember + 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. - - - On the Windows platform, be careful to escape any backslashes - used in the path to the file, or use forward slashes. - + accessible to the server process. + + + On the Windows platform, be careful to escape any backslashes + used in the path to the file, or use forward slashes. + + $fp = fopen("c:\\data\\info.txt", "r"); - - + + + See also fclose, - fsockopen, and popen. - + fsockopen, and popen. + - - fpassthru - output all remaining data on a file pointer + fpassthru + + Output all remaining data on a file pointer + Description @@ -914,31 +992,32 @@ $fp = fopen("c:\\data\\info.txt", "r"); Reads to EOF on the given file pointer and writes the results to - standard output. - + standard output. + - If an error occurs, fpassthru returns false. - + If an error occurs, fpassthru returns + false. + - The file pointer must be valid, and must point to a file successfully - opened by fopen, popen, or - fsockopen. The file is closed when - fpassthru is done reading it (leaving - fp useless). - + The file pointer must be valid, and must point to a file + successfully opened by fopen, + popen, or fsockopen. + The file is closed when fpassthru is done + reading it (leaving fp useless). + - If you just want to dump the contents of a file to stdout - you may want to use the readfile, which - saves you the fopen call. - + If you just want to dump the contents of a file to stdout you may + want to use the readfile, which saves you + the fopen call. + - See also readfile, fopen, - popen, and fsockopen - + See also readfile, + fopen, popen, and + fsockopen + - fputs @@ -1016,20 +1095,21 @@ fclose( $fd ); Sets the file position indicator for the file referenced by fp to offset bytes into the file stream. Equivalent to calling (in C) - fseek( fp, offset, SEEK_SET ). - + fseek(fp, offset, SEEK_SET). + Upon success, returns 0; otherwise, returns -1. Note that seeking - past EOF is not considered an error. - + past EOF is not considered an error. + - May not be used on file pointers returned by fopen - if they use the "http://" or "ftp://" formats. - + May not be used on file pointers returned by + fopen if they use the "http://" or "ftp://" + formats. + See also ftell and - rewind. - + rewind. + @@ -1759,7 +1839,7 @@ sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t sgml-parent-document:nil -sgml-default-dtd-file:"../manual.ced" +sgml-default-dtd-file:"../../manual.ced" sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil