diff --git a/reference/filesystem/functions/chgrp.xml b/reference/filesystem/functions/chgrp.xml index b6d714cf6a..9a346ecec9 100644 --- a/reference/filesystem/functions/chgrp.xml +++ b/reference/filesystem/functions/chgrp.xml @@ -1,13 +1,13 @@ - - + chgrp Changes file group - - Description + + + &reftitle.description; boolchgrp stringfilename @@ -15,20 +15,61 @@ Attempts to change the group of the file filename - to group (specified by name or number). 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. + 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. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + group + + + A group name or number. + + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.notes; ¬e.no-remote; ¬e.sm.uidcheck; + + + + &reftitle.seealso; - See also chown and - chmod. + + chown + chmod + + - + chown Changes file owner - - Description + + + &reftitle.description; boolchown stringfilename @@ -15,18 +15,57 @@ Attempts to change the owner of the file filename - to user user (specified by name or number). Only - the superuser may change the owner of a file. + to user user. Only the superuser may change the + owner of a file. + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + user + + + A user name or number. + + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.notes; ¬e.no-remote; ¬e.sm.uidcheck; + + + + &reftitle.seealso; - See also chmod. + + chmod + + - + copy Copies file - - Description + + + &reftitle.description; boolcopy stringsource @@ -15,7 +15,80 @@ Makes a copy of the file source to - dest. &return.success; + dest. + + + If you wish to move a file, use the rename function. + + + + + &reftitle.parameters; + + + + source + + + Path to the source file. + + + + + dest + + + The destination path. If dest is a URL, the + copy operation may fail if the wrapper does not support overwriting of + existing files. + + + + If the destination file already exists, it will be overwritten. + + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.0 + + Both source and dest + may now be URLs if the "fopen wrappers" have been enabled. + See fopen for more details. + + + + + + + + + + &reftitle.examples; + <function>copy</function> example @@ -32,37 +105,31 @@ if (!copy($file, $newfile)) { - - If you wish to move a file, use the rename function. - - - - As of PHP 4.3.0, both source and - dest may be URLs if the "fopen wrappers" - have been enabled. See fopen for more details. - If dest is a URL, the copy operation may - fail if the wrapper does not support overwriting of existing files. - - - - - If the destination file already exists, it will be overwritten. - - + + + + &reftitle.notes; Windows compatibility: If you copy a file with no size, - copy will return &false;, but the file will be correctly - copied. + copy will return &false;, but the file will be + correctly copied. + + + + &reftitle.seealso; - See also move_uploaded_file, - rename, and the section of the manual - about handling file - uploads. + + move_uploaded_file + rename + The section of the manual about handling file uploads + + - + delete See unlink or unset - - Description + + + &reftitle.description; voiddelete - stringfile + - This is a dummy manual entry to satisfy those people who are - looking for unlink or - unset in the wrong place. - - - See also unlink to delete files, - unset to delete variables. + This is a dummy manual entry to satisfy those people who are looking for + unlink or unset in the wrong + place. + + + &reftitle.returnvalues; + + &return.void; + + + + + &reftitle.seealso; + + + unlink to delete files + unset to delete variables + + + + - + disk_free_space Returns available space in directory - - Description + + + &reftitle.description; floatdisk_free_space stringdirectory - Given a string containing a directory, this function will return - the number of bytes available on the corresponding filesystem or - disk partition. + Given a string containing a directory, this function will return the + number of bytes available on the corresponding filesystem or disk + partition. + + + + &reftitle.parameters; + + + + directory + + + A directory of the filesystem or disk partition. + + + + + + + + + &reftitle.returnvalues; + + Returns the number of available bytes as a float. + + + + + &reftitle.examples; <function>disk_free_space</function> example @@ -34,13 +61,22 @@ disk_free_space("D:"); - - ¬e.no-remote; - - - See also disk_total_space - + + + &reftitle.notes; + ¬e.no-remote; + + + + &reftitle.seealso; + + + disk_total_space + + + + - + disk_total_space Returns the total size of a directory - - Description + + + &reftitle.description; floatdisk_total_space stringdirectory - Given a string containing a directory, this function will return - the total number of bytes on the corresponding filesystem or disk - partition. + Given a string containing a directory, this function will return the total + number of bytes on the corresponding filesystem or disk partition. + + + + &reftitle.parameters; + + + + directory + + + A directory of the filesystem or disk partition. + + + + + + + + + &reftitle.returnvalues; + + Returns the total number of bytes as a float. + + + + + &reftitle.examples; <function>disk_total_space</function> example @@ -34,13 +60,22 @@ disk_total_space("D:"); - - ¬e.no-remote; - - - See also disk_free_space - + + + &reftitle.notes; + ¬e.no-remote; + + + + &reftitle.seealso; + + + disk_free_space + + + + - + diskfreespace @@ -14,6 +13,7 @@ disk_free_space. + - + fclose Closes an open file pointer - - Description + + + &reftitle.description; boolfclose resourcehandle @@ -15,14 +15,34 @@ The file pointed to by handle is closed. + + + + &reftitle.parameters; + + + + handle + + + The file pointer must be valid, and must point to a file successfully + opened by fopen or fsockopen. + + + + + + + + + &reftitle.returnvalues; &return.success; - - The file pointer must be valid, and must point to a file - successfully opened by fopen or - fsockopen. - + + + + &reftitle.examples; A simple <function>fclose</function> example @@ -30,9 +50,9 @@ ]]> @@ -40,6 +60,17 @@ + + + &reftitle.seealso; + + + fopen + fsockopen + + + + - + feof Tests for end-of-file on a file pointer - - Description + + + &reftitle.description; boolfeof resourcehandle + + Tests for end-of-file on a file pointer. + + + + + &reftitle.parameters; + + + + handle + + &fs.validfp.all; + + + + + + + + &reftitle.returnvalues; Returns &true; if the file pointer is at EOF or an error occurs (including socket timeout); otherwise returns &false;. + + + + &reftitle.notes; If a connection opened by fsockopen wasn't closed @@ -25,7 +50,6 @@ value. - &fs.validfp.all; If passed file pointer is not valid you may get an infinite loop, because @@ -50,6 +74,7 @@ fclose($file); + - + fflush Flushes the output to a file - - Description + + + &reftitle.description; boolfflush resourcehandle - This function forces a write of all buffered output to the - resource pointed to by the file handle handle. + This function forces a write of all buffered output to the resource + pointed to by the file handle. + + + + + &reftitle.parameters; + + + + handle + + &fs.validfp.all; + + + + + + + + &reftitle.returnvalues; + &return.success; - &fs.validfp.all; + - + fgetcsv Gets line from file pointer and parse for CSV fields - - Description + + + &reftitle.description; arrayfgetcsv resourcehandle @@ -15,65 +15,112 @@ stringdelimiter stringenclosure + + Similar to fgets except that + fgetcsv parses the line it reads for fields in + CSV format and returns an array containing the fields + read. + + + + &reftitle.parameters; handle - - A valid file pointer to a file successfully opened by fopen, - popen, or fsockopen. - + + A valid file pointer to a file successfully opened by + fopen, popen, or + fsockopen. + - length (Optional) + length - - Must be greater than the longest line (in characters) to be found in the CSV file - (allowing for trailing line-end characters). It became optional in PHP 5. Omitting - this parameter (or setting it to 0 in PHP 5.0.4 and later) the maximum line length - is not limited, which is slightly slower. - + + Must be greater than the longest line (in characters) to be found in + the CSV file (allowing for trailing line-end characters). It became + optional in PHP 5. Omitting this parameter (or setting it to 0 in PHP + 5.0.4 and later) the maximum line length is not limited, which is + slightly slower. + - delimiter (Optional) + delimiter - + Set the field delimiter (one character only). Defaults as a comma. - + - enclosure (Optional) + enclosure - - Set the field enclosure character (one character only). Defaults as a double quotation mark. Added in PHP 4.3.0. - + + Set the field enclosure character (one character only). Defaults as a + double quotation mark. + + - - Similar to fgets except that - fgetcsv parses the line it reads for fields - in CSV format and returns an array containing - the fields read. - - - fgetcsv returns &false; on error, including - end of file. - + + &reftitle.returnvalues; + + Returns an indexed array containing the fields read. + - + A blank line in a CSV file will be returned as an array comprising a single null field, and will not be treated as an error. - + + ¬e.line-endings; + + fgetcsv returns &false; on error, including end of + file. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 4.3.5 + + fgetcsv is now binary safe + + + + 4.3.0 + + The enclosure parameter was added + + + + + + + + + + &reftitle.examples; Read and print the entire contents of a CSV file @@ -96,22 +143,31 @@ fclose($handle); - - fgetcsv has been binary safe since PHP 4.3.5 - + + + + &reftitle.notes; - + Locale setting is taken into account by this function. If LANG is e.g. en_US.UTF-8, files in one-byte encoding are read wrong by this function. - + - ¬e.line-endings; + + + + &reftitle.seealso; - See also explode, file, - pack and fputcsv. + + explode + file + pack + fputcsv + + - + fgets Gets line from file pointer - - Description + + + &reftitle.description; stringfgets resourcehandle intlength + + Gets a line from file pointer. + + + + + &reftitle.parameters; + + + + handle + + &fs.validfp.all; + + + + length + + + 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). If no length is specified, it will keep + reading from the stream until it reaches the end of the line. + + + + Until PHP 4.3.0, omitting it would assume 1024 as the line length. + If the majority of the lines in the file are all larger than 8KB, + it is more resource efficient for your script to specify the maximum + line length. + + + + + + + + + + &reftitle.returnvalues; Returns a string of up to length - 1 bytes read from - the file pointed to by handle. 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). If no length - is specified, it will keep reading from the stream until it reaches - the end of the line. + the file pointed to by handle. If an error occurs, returns &false;. + + + + &reftitle.changelog; - Common Pitfalls: + + + + + &Version; + &Description; + + + + + 4.3.0 + + fgets is now binary safe + + + + 4.2.0 + + The length parameter became optional + + + + + - - People used to the 'C' semantics of fgets - should note the difference in how EOF is returned. - - - &fs.validfp.all; + + + &reftitle.examples; - A simple example follows: Reading a file line by line @@ -54,33 +113,35 @@ if ($handle) { - - - The length parameter became optional in PHP - 4.2.0. Until PHP 4.3.0, omitting it would assume 1024 as the line length. - If the majority of the lines in the file are all larger than 8KB, - it is more resource efficient for your script to specify the maximum - line length. - - - - - This function is binary safe as of PHP 4.3. Earlier versions - were not binary safe. - - + + + + &reftitle.notes; ¬e.line-endings; + + + People used to the 'C' semantics of fgets + should note the difference in how EOF is returned. + + + + + + &reftitle.seealso; - See also fgetss - fread, - fgetc, - stream_get_line, - fopen, - popen, - fsockopen, and - stream_set_timeout. + + fgetss + fread + fgetc + stream_get_line + fopen + popen + fsockopen + stream_set_timeout + + - + file_exists Checks whether a file or directory exists - - Description + + + &reftitle.description; boolfile_exists stringfilename - + + Checks whether a file or directory exists. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file or directory. + + + On windows, use //computername/share/filename or + \\computername\share\filename to check files on + network shares. + + + + + + + + + &reftitle.returnvalues; + Returns &true; if the file or directory specified by filename exists; &false; otherwise. - - - On windows, use //computername/share/filename or - \\computername\share\filename to check files on - network shares. + + + This function returns &false; for files inaccessible due to safe mode restrictions. However these + files still can be included if + they are located in safe_mode_include_dir. + + + + + The check is done using the real UID/GID instead of the effective one. + + + + + + &reftitle.examples; Testing whether a file exists @@ -39,32 +80,26 @@ if (file_exists($filename)) { + + + &reftitle.notes; ¬e.clearstatcache; - &tip.fopen-wrapper.stat; + - - - This function returns &false; for files inaccessible due to safe mode restrictions. However these - files still can be included if - they are located in safe_mode_include_dir. - - - - - - The check is done using the real UID/GID instead of the effective one. - - - + + &reftitle.seealso; - See also is_readable, is_writable, - is_file and file. + + is_readable + is_writable + is_file + file + + + file_put_contents @@ -15,21 +15,15 @@ intflags resourcecontext - + Identical to calling fopen, fwrite, and fclose successively. - + You can also specify the data parameter as an array (not multi-dimension arrays). This is equivalent to file_put_contents($filename, implode('', $array)). - - As of PHP 5.1.0, you may also pass a stream resource to the - data parameter. In result, the remaining buffer of - that stream will be copied to the specified file. This is similar with - using stream_copy_to_stream. - @@ -51,6 +45,11 @@ The data to write. Can be either a string, an array or a stream resource (explained above). + + If data is a stream resource, the + remaining buffer of that stream will be copied to the specified file. + This is similar with using stream_copy_to_stream. + diff --git a/reference/filesystem/functions/file.xml b/reference/filesystem/functions/file.xml index 7887c233d4..4d415626df 100644 --- a/reference/filesystem/functions/file.xml +++ b/reference/filesystem/functions/file.xml @@ -1,13 +1,13 @@ - - + file Reads entire file into an array - - Description + + + &reftitle.description; arrayfile stringfilename @@ -15,57 +15,144 @@ resourcecontext - Similiar to file_get_contents, 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. Upon failure, file - returns &false;. + Reads an entire file into an array. + + + You can use file_get_contents to return the contents + of a file as a string. + + + + + + &reftitle.parameters; - The optional parameter flags can be one, or more, of - the following constants: - - FILE_USE_INCLUDE_PATH - + filename - - Search for the file in the include_path. - + + Path to the file. + + &tip.fopen-wrapper; - - FILE_IGNORE_NEW_LINES - + flags - - Do not add newline at the end of each array element - + + The optional parameter flags can be one, or + more, of the following constants: + + + + FILE_USE_INCLUDE_PATH + + + + Search for the file in the include_path. + + + + + + FILE_IGNORE_NEW_LINES + + + + Do not add newline at the end of each array element + + + + + + FILE_SKIP_EMPTY_LINES + + + + Skip empty lines + + + + + - - FILE_SKIP_EMPTY_LINES - + context - - Skip empty lines - + + ¬e.context-support; + + + + + &reftitle.returnvalues; + + Returns the file in an array. Each element of the array corresponds to a + line in the file, with the newline still attached. Upon failure, + file returns &false;. + - Prior to PHP 5.0.0 the flags parameter only - covered include_path and was - enabled with 1. + Each line in the resulting array will include the line ending, unless + FILE_IGNORE_NEW_LINES is used, so you still need to + use rtrim if you do not want the line ending + present. + ¬e.line-endings; + + + + &reftitle.changelog; - + + + + + &Version; + &Description; + + + + + 5.0.0 + + The context parameter was added + + + + 5.0.0 + + Prior to PHP 5.0.0 the flags parameter only + covered include_path and was + enabled with 1 + + + + 4.3.0 + + file became binary safe + + + + + + + + + + &reftitle.examples; + + + <function>file</function> example ]]> - - - &tip.fopen-wrapper; - - - Each line in the resulting array will include the line ending, unless FILE_IGNORE_NEW_LINES is used, so you - still need to use rtrim if you do not want the line - ending present. - - - ¬e.line-endings; - - - As of PHP 4.3.0 you can use file_get_contents to - return the contents of a file as a string. - - - In PHP 4.3.0 file became binary safe. - - - ¬e.context-support; - &warn.ssl-non-standard; - - See also readfile, - fopen, fsockopen, - popen, file_get_contents, - include, and - stream_context_create + + + + &reftitle.notes; + &warn.ssl-non-standard; + + + + &reftitle.seealso; + + + readfile + fopen + fsockopen + popen + file_get_contents + include + stream_context_create + + + + - + filectime Gets inode change time of file - - Description + + + &reftitle.description; intfilectime stringfilename + + Gets the inode change time of a file. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; Returns the time the file was last changed, or &false; in case of an error. The time is returned as a Unix timestamp. - - 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 - filemtime (which is what you want to use - when you want to create "Last Modified" footers on web pages) and - fileatime. - - - 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. - - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; + + + &reftitle.examples; A <function>filectime</function> example @@ -54,10 +62,40 @@ if (file_exists($filename)) { - - See also filemtime - + + + &reftitle.notes; + + + 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 + filemtime (which is what you want to use when you + want to create "Last Modified" footers on web pages) and + fileatime. + + + + + 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. + + + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + filemtime + + + + - + filegroup Gets file group - - Description + + + &reftitle.description; intfilegroup stringfilename + + Gets the file group. The group ID is returned in numerical format, use + posix_getgrgid to resolve it to a group name. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; Returns the group ID of the file, or &false; in case of an error. The group ID is returned in numerical format, use posix_getgrgid to resolve it to a group name. - Upon failure, &false; is returned along with an error of level - E_WARNING. + Upon failure, &false; is returned. - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - - - See also fileowner, and - safe_mode_gid. - + + + &reftitle.errors; + + Upon failure, an E_WARNING is emitted. + + + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + fileowner + safe_mode_gid + + + + - + fileinode Gets file inode - - Description + + + &reftitle.description; intfileinode stringfilename - Returns the inode number of the file, or &false; in case of an - error. + Gets the file inode. - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - - - See also stat - + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; + + Returns the inode number of the file, or &false; in case of an error. + + + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + stat + + + + - + filemtime Gets file modification time - - Description + + + &reftitle.description; intfilemtime stringfilename + + 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. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; Returns the time the file was last modified, or &false; in case of an error. The time is returned as a Unix timestamp, which is suitable for the date function. + - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - - - 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. - + + &reftitle.examples; <function>filemtime</function> example @@ -44,11 +62,26 @@ if (file_exists($filename)) { + + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; - See also filectime, stat, - touch, and getlastmod. + + filectime + stat + touch + getlastmod + + - + fileowner Gets file owner - - Description + + + &reftitle.description; intfileowner stringfilename + + Gets the file owner. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; 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 posix_getpwuid to resolve it to a username. - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - - - See also stat - - + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + stat + + + + - + fileperms Gets file permissions - - Description + + + &reftitle.description; intfileperms stringfilename + + Gets permissions for the given file. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; Returns the permissions on the file, or &false; in case of an error. - ¬e.clearstatcache; - &tip.fopen-wrapper.stat; - - Display permissions as an octal value - + + + + &reftitle.examples; + + + Display permissions as an octal value + ]]> - - - This would produce the output: - - + + &example.outputs; + - - - - Display full permissions - + + + + Display full permissions + ]]> - - - This would produce the output: - - + + &example.outputs; + - - - - See also is_readable, - and stat - + + + + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + is_readable + stat + + + + - + filesize Gets file size - - Description + + + &reftitle.description; intfilesize stringfilename + + Gets the size for the given file. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; Returns the size of the file in bytes, or &false; (and generates an error of level E_WARNING) in case of an error. @@ -24,11 +47,10 @@ be overcome by using sprintf("%u", filesize($file)). + - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - + + &reftitle.examples; <function>filesize</function> example @@ -46,10 +68,23 @@ echo $filename . ': ' . filesize($filename) . ' bytes'; - - See also file_exists - + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + file_exists + + + + - + fopen Opens file or URL - - Description + + + &reftitle.description; resourcefopen stringfilename @@ -15,209 +15,291 @@ booluse_include_path resourcecontext - - fopen binds a named resource, specified - by filename, to a stream. If - filename is of the form "scheme://...", - it is assumed to be a URL and PHP will search for a protocol - handler (also known as a wrapper) for that scheme. If no - wrappers for that protocol are registered, PHP will emit - a notice to help you track potential problems in your script - and then continue as though filename - specifies a regular file. - - - If PHP has decided that filename specifies - a local file, then it will try to open a stream on that file. - The file must be accessible to PHP, so you need to ensure that - the file access permissions allow this access. - If you have enabled &safemode;, - or open_basedir further - restrictions may apply. - - - If PHP has decided that filename specifies - a registered protocol, and that protocol is registered as a - network URL, PHP will check to make sure that - allow_url_fopen is - enabled. If it is switched off, PHP will emit a warning and - the fopen call will fail. - - - - The list of supported protocols can be found in . - Some protocols (also referred to as wrappers) support - context and/or &php.ini; options. - Refer to the specific page for the protocol in use for a list of options - which can be set. (e.g. &php.ini; value - user_agent used by the http wrapper). - - - ¬e.context-support; - - - As of PHP 4.3.2, the default mode is set to binary for all - platforms that distinguish between binary and text mode. If you are - having problems with your scripts after upgrading, try using the - 't' flag as a workaround until you have made your - script more portable as mentioned below. - - - The mode parameter specifies the type of access - you require to the stream. It may be any of the following: - - - A list of possible modes for <function>fopen</function> - using <parameter>mode</parameter> - + fopen binds a named resource, specified by + filename, to a stream. + + + + + &reftitle.parameters; + + + + filename + + + If filename is of the form "scheme://...", it + is assumed to be a URL and PHP will search for a protocol handler + (also known as a wrapper) for that scheme. If no wrappers for that + protocol are registered, PHP will emit a notice to help you track + potential problems in your script and then continue as though + filename specifies a regular file. + + + If PHP has decided that filename specifies + a local file, then it will try to open a stream on that file. + The file must be accessible to PHP, so you need to ensure that + the file access permissions allow this access. + If you have enabled &safemode;, + or open_basedir further + restrictions may apply. + + + If PHP has decided that filename specifies + a registered protocol, and that protocol is registered as a + network URL, PHP will check to make sure that + allow_url_fopen is + enabled. If it is switched off, PHP will emit a warning and + the fopen call will fail. + + + + The list of supported protocols can be found in . Some protocols (also referred to as + wrappers) support context + and/or &php.ini; options. Refer to the specific page for the + protocol in use for a list of options which can be set. (e.g. + &php.ini; value user_agent used by the + http wrapper). + + + + On the Windows platform, be careful to escape any backslashes + used in the path to the file, or use forward slashes. + + + +]]> + + + + + + + mode + + + The mode parameter specifies the type of access + you require to the stream. It may be any of the following: +
+ + A list of possible modes for <function>fopen</function> + using <parameter>mode</parameter> + + + + + mode + Description + + + + + '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. + + + + 'x' + + Create and open for writing only; place the file pointer at the + beginning of the file. If the file already exists, the + fopen call will fail by returning &false; and + generating an error of level E_WARNING. If + the file does not exist, attempt to create it. This is equivalent + to specifying O_EXCL|O_CREAT flags for the + underlying open(2) system call. + + + + 'x+' + + Create and open for reading and writing; place the file pointer at + the beginning of the file. If the file already exists, the + fopen call will fail by returning &false; and + generating an error of level E_WARNING. If + the file does not exist, attempt to create it. This is equivalent + to specifying O_EXCL|O_CREAT flags for the + underlying open(2) system call. + + + + +
+ + + + Different operating system families have different line-ending + conventions. When you write a text file and want to insert a line + break, you need to use the correct line-ending character(s) for your + operating system. Unix based systems use \n as the + line ending character, Windows based systems use \r\n + as the line ending characters and Macintosh based systems use + \r as the line ending character. + + + If you use the wrong line ending characters when writing your files, you + might find that other applications that open those files will "look + funny". + + + Windows offers a text-mode translation flag ('t') + which will transparently translate \n to + \r\n when working with the file. In contrast, you + can also use 'b' to force binary mode, which will not + translate your data. To use these flags, specify either + 'b' or 't' as the last character + of the mode parameter. + + + The default translation mode depends on the SAPI and version of PHP that + you are using, so you are encouraged to always specify the appropriate + flag for portability reasons. You should use the 't' + mode if you are working with plain-text files and you use + \n to delimit your line endings in your script, but + expect your files to be readable with applications such as notepad. You + should use the 'b' in all other cases. + + + If you do not specify the 'b' flag when working with binary files, you + may experience strange problems with your data, including broken image + files and strange problems with \r\n characters. + + + + + For portability, it is strongly recommended that you always + use the 'b' flag when opening files with fopen. + + + + + Again, for portability, it is also strongly recommended that + you re-write code that uses or relies upon the 't' + mode so that it uses the correct line endings and + 'b' mode instead. + + + + + + use_include_path + + + The optional third use_include_path parameter + can be set to '1' or &true; if you want to search for the file in the + include_path, too. + + + + + context + + ¬e.context-support; + + + + + + + + &reftitle.returnvalues; + + Returns a file pointer resource on success, or &false; on error. + + + + + &reftitle.errors; + + If the open fails, the function an error of level + E_WARNING is generated. You may use @ to suppress this + warning. + + + + + &reftitle.changelog; + + - mode - Description + &Version; + &Description; - 'r' + 4.3.2 - Open for reading only; place the file pointer at the - beginning of the file. + As of PHP 4.3.2, the default mode is set to binary for all platforms + that distinguish between binary and text mode. If you are having + problems with your scripts after upgrading, try using the + 't' flag as a workaround until you have made your + script more portable as mentioned below - 'r+' + 4.3.2 - 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. - - - - 'x' - - Create and open for writing only; place the file pointer at the - beginning of the file. If the file already exists, the - fopen call will fail by returning &false; and - generating an error of level E_WARNING. If - the file does not exist, attempt to create it. This is equivalent - to specifying O_EXCL|O_CREAT flags for the - underlying open(2) system call. This option is - supported in PHP 4.3.2 and later, and only works for local files. - - - - 'x+' - - Create and open for reading and writing; place the file pointer at - the beginning of the file. If the file already exists, the - fopen call will fail by returning &false; and - generating an error of level E_WARNING. If - the file does not exist, attempt to create it. This is equivalent - to specifying O_EXCL|O_CREAT flags for the - underlying open(2) system call. This option is - supported in PHP 4.3.2 and later, and only works for local files. + The 'x' and 'x+' option was + added - + - - - Different operating system families have different line-ending - conventions. When you write a text file and want to insert a line - break, you need to use the correct line-ending character(s) for your - operating system. Unix based systems use \n as the - line ending character, Windows based systems use \r\n - as the line ending characters and Macintosh based systems use - \r as the line ending character. - - - If you use the wrong line ending characters when writing your files, you - might find that other applications that open those files will "look - funny". - - - Windows offers a text-mode translation flag ('t') - which will transparently translate \n to - \r\n when working with the file. In contrast, you - can also use 'b' to force binary mode, which will not - translate your data. To use these flags, specify either - 'b' or 't' as the last character - of the mode parameter. - - - The default translation mode depends on the SAPI and version of PHP that - you are using, so you are encouraged to always specify the appropriate - flag for portability reasons. You should use the 't' - mode if you are working with plain-text files and you use - \n to delimit your line endings in your script, but - expect your files to be readable with applications such as notepad. You - should use the 'b' in all other cases. - - - If you do not specify the 'b' flag when working with binary files, you - may experience strange problems with your data, including broken image - files and strange problems with \r\n characters. - - - - - For portability, it is strongly recommended that you always - use the 'b' flag when opening files with fopen. - - - - - Again, for portability, it is also strongly recommended that - you re-write code that uses or relies upon the 't' - mode so that it uses the correct line endings and - 'b' mode instead. - - - - The optional third use_include_path parameter - can be set to '1' or &true; if you want to search for the file in - the include_path, too. - - - If the open fails, the function returns &false; and an error of - level E_WARNING is generated. You may use - @ to - suppress this warning. - + + + + &reftitle.examples; <function>fopen</function> examples @@ -233,42 +315,40 @@ $handle = fopen("ftp://user:password@example.com/somefile.txt", "w"); - - 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. - - - On the Windows platform, be careful to escape any backslashes - used in the path to the file, or use forward slashes. - - - -]]> - - - + + + + &reftitle.notes; &warn.ssl-non-standard; ¬e.sm.uidcheck.dir; - - See also , - fclose, - fgets, - fread, - fwrite, - fsockopen, - file, - file_exists, - is_readable, - stream_set_timeout, - popen, and - stream_context_create. - + + 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. + + + + &reftitle.seealso; + + + + fclose + fgets + fread + fwrite + fsockopen + file + file_exists + is_readable + stream_set_timeout + popen + stream_context_create + + + + - + fputs @@ -14,6 +13,7 @@ fwrite. + - + ftell Tells file pointer read/write position - - Description + + + &reftitle.description; intftell resourcehandle + + Tells the file pointer read/write position. + + + + + &reftitle.parameters; + + + + handle + + + The file pointer must be valid, and must point to a file successfully + opened by fopen or popen. + ftell gives undefined results for append-only streams + (opened with "a" flag). + + + + + + + + + &reftitle.returnvalues; Returns the position of the file pointer referenced by - handle; i.e., its offset into the - file stream. + handle; i.e., its offset into the file stream. If an error occurs, returns &false;. - - The file pointer must be valid, and must point to a file - successfully opened by fopen or - popen. - ftell gives undefined results for append-only streams - (opened with "a" flag). - + + + + &reftitle.examples; <function>ftell</function> example @@ -48,11 +70,20 @@ fclose($fp); + + + + &reftitle.seealso; - See also fopen, popen, - fseek, and rewind. + + fopen + popen + fseek + rewind + + + glob Find pathnames matching a pattern - - Description + + + &reftitle.description; arrayglob stringpattern @@ -16,71 +17,118 @@ The glob function searches for all the pathnames matching pattern according to the rules used by the libc glob() function, which is similar to the rules used by common - shells. No tilde expansion or parameter substitution is done. + shells. + + + + &reftitle.parameters; + + + + pattern + + + The pattern. No tilde expansion or parameter substitution is done. + + + + + flags + + + Valid flags: + + + + GLOB_MARK - Adds a slash to each item returned + + + + + GLOB_NOSORT - Return files as they appear in the + directory (no sorting) + + + + + GLOB_NOCHECK - Return the search pattern if no + files matching it were found + + + + + GLOB_NOESCAPE - Backslashes do not quote + metacharacters + + + + + GLOB_BRACE - Expands {a,b,c} to match 'a', 'b', + or 'c' + + + + + GLOB_ONLYDIR - Return only directory entries + which match the pattern + + + + + GLOB_ERR - Stop on read errors (like unreadable + directories), by default errors are ignored. + + + + + + + + + + + + &reftitle.returnvalues; Returns an array containing the matched files/directories, an empty array if no file matched or &false; on error. + + + + &reftitle.changelog; - Valid flags: - - - - GLOB_MARK - Adds a slash to each item returned - - - - - GLOB_NOSORT - Return files as they appear in the - directory (no sorting) - - - - - GLOB_NOCHECK - Return the search pattern if no - files matching it were found - - - - - GLOB_NOESCAPE - Backslashes do not quote - metacharacters - - - - - GLOB_BRACE - Expands {a,b,c} to match 'a', 'b', - or 'c' - - - - This flag is not available on some non GNU systems, like Solaris. - - - - - - GLOB_ONLYDIR - Return only directory entries - which match the pattern - - - - Before PHP 4.3.3 GLOB_ONLYDIR was - not - available on Windows and other systems not using the GNU - C library. - - - - - - GLOB_ERR - Stop on read errors (like unreadable - directories), by default errors are ignored. Added in PHP 5.1.0. - - - + + + + + &Version; + &Description; + + + + + 5.1.0 + + GLOB_ERR was added + + + + 4.3.3 + + GLOB_ONLYDIR bacame available on Windows and + other systems not using the GNU C library + + + + + + + + + &reftitle.examples; @@ -106,20 +154,36 @@ quickref.txt size 137820 </screen> </example> </para> + </refsect1> + <refsect1 role="notes"> + &reftitle.notes; ¬e.no-remote; <note> <simpara> This function isn't available on some systems (e.g. old Sun OS). </simpara> </note> + <note> + <simpara> + The <constant>GLOB_BRACE</constant> flag is not available on some non GNU + systems, like Solaris. + </simpara> + </note> + </refsect1> + <refsect1 role="seealso"> + &reftitle.seealso; <para> - See also <function>opendir</function>, - <function>readdir</function>, - <function>closedir</function>, and <function>fnmatch</function>. + <simplelist> + <member><function>opendir</function></member> + <member><function>readdir</function></member> + <member><function>closedir</function></member> + <member><function>fnmatch</function></member> + </simplelist> </para> </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/reference/filesystem/functions/is-dir.xml b/reference/filesystem/functions/is-dir.xml index 4de0657237..9951dfd1fb 100644 --- a/reference/filesystem/functions/is-dir.xml +++ b/reference/filesystem/functions/is-dir.xml @@ -1,23 +1,50 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.12 $ --> -<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 --> +<!-- $Revision: 1.13 $ --> <refentry id="function.is-dir"> <refnamediv> <refname>is_dir</refname> <refpurpose>Tells whether the filename is a directory</refpurpose> </refnamediv> - <refsect1> - <title>Description + + + &reftitle.description; boolis_dir stringfilename - Returns &true; if the filename exists and is a directory. If - filename is a relative filename, it will be - checked relative to the current working directory. + Tells whether the given filename is a directory. - ¬e.clearstatcache; + + + + &reftitle.parameters; + + + + filename + + + Path to the file. If filename is a relative + filename, it will be checked relative to the current working + directory. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the filename exists and is a directory, &false; + otherwise. + + + + + &reftitle.examples; <function>is_dir</function> example @@ -41,14 +68,27 @@ bool(true) - &tip.fopen-wrapper.stat; + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; - See also chdir, dir, - opendir, is_file and - is_link. + + chdir + dir + opendir + is_file + is_link + + - + is_executable Tells whether the filename is executable - - Description + + + &reftitle.description; boolis_executable stringfilename - Returns &true; if the filename exists and is executable. + Tells whether the filename is executable. + + + + &reftitle.parameters; - is_executable became available with - Windows in PHP version 5.0.0. + + + filename + + + Path to the file. + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the filename exists and is executable, or &false; on + error. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + is_executable became available with + Windows + + + + + + + + + + &reftitle.examples; <function>is_executable</function> example @@ -39,16 +88,24 @@ if (is_executable($file)) { + + + &reftitle.notes; ¬e.clearstatcache; - &tip.fopen-wrapper.stat; + + + &reftitle.seealso; - See also is_file and - is_link. + + is_file + is_link + + - + is_file Tells whether the filename is a regular file - - Description + + + &reftitle.description; boolis_file stringfilename - Returns &true; if the filename exists and is a regular file. + Tells whether the given file is a regular file. + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the filename exists and is a regular file, &false; + otherwise. + + + + + &reftitle.examples; <function>is_file</function> example @@ -35,16 +63,24 @@ bool(false) + + + &reftitle.notes; ¬e.clearstatcache; - &tip.fopen-wrapper.stat; + + + &reftitle.seealso; - See also is_dir and - is_link. + + is_dir + is_link + + - + is_link Tells whether the filename is a symbolic link - - Description + + + &reftitle.description; boolis_link stringfilename - Returns &true; if the filename exists and is a symbolic link. - - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - - - See also is_dir, - is_file, and readlink. + Tells whether the given file is a symbolic link. + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the filename exists and is a symbolic link, &false; + otherwise. + + + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + is_dir + is_file + readlink + + + + - + is_readable Tells whether the filename is readable - - Description + + + &reftitle.description; boolis_readable stringfilename - Returns &true; if the file or directory specified by - filename exists and is readable. + Tells whether the filename is readable. + + + + &reftitle.parameters; - 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. + + + filename + + + Path to the file. + + + + + + + + &reftitle.returnvalues; + + Returns &true; if the file or directory specified by + filename exists and is readable, &false; otherwise. + + + + + &reftitle.examples; <function>is_readable</function> example @@ -38,23 +60,35 @@ if (is_readable($filename)) { + + + &reftitle.notes; + + 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. + ¬e.clearstatcache; - &tip.fopen-wrapper.stat; - The check is done using the real UID/GID instead of the effective one. + + + &reftitle.seealso; - See also is_writable, - file_exists, and - fgets. + + is_writable + file_exists + fgets + + - + is_writeable @@ -14,6 +13,7 @@ is_writable. + + lchgrp Changes group ownership of symlink - - Description + + + &reftitle.description; boollchgrp stringfilename @@ -14,22 +15,64 @@ Attempts to change the group of the symlink filename - to group (specified by name or number). Only the - superuser may change the group of a symlink arbitrarily; other users may - change the group of a symlink to any group of which that user is a member. + to group. + + Only the superuser may change the group of a symlink arbitrarily; other + users may change the group of a symlink to any group of which that user is + a member. + + + + + &reftitle.parameters; + + + + filename + + + Path to the symlink. + + + + + group + + + The group specified by name or number. + + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.notes; ¬e.no-remote; ¬e.sm.uidcheck; + + + + &reftitle.seealso; - See also chgrp, - lchown - chown&listendand; - chmod. + + chgrp + lchown + chown + chmod + + + lchown Changes user ownership of symlink - - Description + + + &reftitle.description; boollchown stringfilename @@ -14,21 +15,62 @@ Attempts to change the owner of the symlink filename - to user user (specified by name or number). Only - the superuser may change the owner of a symlink. + to user user. + + Only the superuser may change the owner of a symlink. + + + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + user + + + User name or number. + + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.notes; ¬e.no-remote; ¬e.sm.uidcheck; + + + + &reftitle.seealso; - See also chown, - lchgrp, - chgrp&listendand; - chmod. + + chgrp + lchgrp + chgrp + chmod + + - + link Create a hard link - - Description + + + &reftitle.description; boollink stringtarget stringlink - link creates a hard link. &return.success; - - - ¬e.no-remote; - ¬e.no-windows; - - - See also the symlink to create soft links, - and readlink along with - linkinfo. + link creates a hard link. + + + &reftitle.parameters; + + + + target + + + Target of the link. + + + + + link + + + The link name. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.notes; + ¬e.no-remote; + ¬e.no-windows; + + + + &reftitle.seealso; + + + symlink + readlink + linkinfo + + + + - + linkinfo Gets information about a link - - Description + + + &reftitle.description; intlinkinfo stringpath - linkinfo 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 - path) really exists (using the same method - as the S_ISLNK macro defined in stat.h). - Returns 0 or &false; in - case of error. + Gets information about a link. + + This function is used to verify if a link (pointed to by + path) really exists (using the same method as the + S_ISLNK macro defined in stat.h). + + + + + &reftitle.parameters; + + + + path + + + Path to the link. + + + + + + + + + &reftitle.returnvalues; + + linkinfo returns the st_dev field + of the Unix C stat structure returned by the lstat + system call. Returns 0 or &false; in case of error. + + + + + &reftitle.examples; <function>linkinfo</function> example @@ -35,12 +63,24 @@ echo linkinfo('/vmlinuz'); // 835 + + + + &reftitle.notes; ¬e.no-windows; + + + + &reftitle.seealso; - See also symlink, link, - and readlink. + + symlink + link + readlink + + - + lstat Gives information about a file or symbolic link - - Description + + + &reftitle.description; arraylstat stringfilename Gathers the statistics of the file or symbolic link named by - filename. This function is identical to the - stat function except that if the - filename 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. + filename. + + + + &reftitle.parameters; + + + + filename + + + Path to a file or a symbolic link. + + + + + + + + + &reftitle.returnvalues; See the manual page for stat for information on the structure of the array that lstat returns. + This function is identical to the stat function + except that if the filename 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. - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - - - See also stat. - + + + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + + + + &reftitle.seealso; + + + stat + + + + - + mkdir Makes directory - - Description + + + &reftitle.description; boolmkdir stringpathname @@ -18,25 +18,109 @@ Attempts to create the directory specified by pathname. + + + + &reftitle.parameters; - 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 umask. + + + pathname + + + The directory path. + + + + + mode + + + The mode is 0777 by default, which means the widest possible + access. For more information on modes, read the details + on the chmod page. + + + + mode is ignored on Windows. + + + + 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 + umask. + + + + + recursive + + + + + + + context + + ¬e.context-support; + + + + + + + &reftitle.returnvalues; - - - Mode is ignored on Windows, and became optional in PHP 4.2.0. - - + &return.success; + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + The recursive parameter was added + + + + 5.0.0 + + As of PHP 5.0.0 mkdir can also be used with + some URL wrappers. Refer to for a listing of which wrappers support + mkdir + + + + 4.2.0 + + The mode parameter became optional. + + + + + + + + + + &reftitle.examples; - The mode is 0777 by default, which means the widest possible - access. For more information on modes, read the details - on the chmod page. - <function>mkdir</function> example + <function>mkdir</function> example - - &return.success; - - - - As of PHP 5.0.0 mkdir can also be - used with some URL wrappers. Refer to - for a listing of which wrappers support mkdir. - - - ¬e.context-support; - - - The recursive parameter was added as of PHP 5.0.0. - - + + + + &reftitle.notes; ¬e.sm.uidcheck.dir; + + + + &reftitle.seealso; - See also rmdir. + + rmdir + + - + pclose Closes process file pointer - - Description + + + &reftitle.description; intpclose resourcehandle - Closes a file pointer to a pipe opened by - popen. - - - The file pointer must be valid, and must have been returned by a - successful call to popen. - - - Returns the termination status of the process that was - run. - - - See also popen. + Closes a file pointer to a pipe opened by popen. + + + &reftitle.parameters; + + + + handle + + + The file pointer must be valid, and must have been returned by a + successful call to popen. + + + + + + + + + &reftitle.returnvalues; + + Returns the termination status of the process that was run. + + + + + &reftitle.seealso; + + + popen + + + + - + readlink Returns the target of a symbolic link - - Description + + + &reftitle.description; stringreadlink stringpath - readlink does the same as the readlink C - function and returns the contents of the symbolic link path or &false; - in case of error. + readlink does the same as the readlink C function. + + + + &reftitle.parameters; + + + + path + + + The symbolic link path. + + + + + + + + + &reftitle.returnvalues; + + Returns the contents of the symbolic link path or &false; on error. + + + + + &reftitle.examples; <function>readlink</function> example @@ -32,13 +57,24 @@ echo readlink('/vmlinuz'); + + + + &reftitle.notes; ¬e.no-windows; + + + + &reftitle.seealso; - See also is_link, - symlink, and - linkinfo. + + is_link + symlink + linkinfo + + - + rename Renames a file or directory - - Description + + + &reftitle.description; boolrename stringoldname @@ -18,9 +18,87 @@ Attempts to rename oldname to newname. + + + + &reftitle.parameters; + + + + oldname + + + + + + The old name. The wrapper used in oldname + must match the wrapper used in + newname. + + + + + + newname + + + The new name. + + + + + context + + ¬e.context-support; + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + rename can now also be used with + some URL wrappers. Refer to for a listing of which wrappers + support rename. + + + + 4.3.3 + + rename is now able to rename files across + partitions on *nix based systems. + + + + + + + + + + &reftitle.examples; Example with <function>rename</function> @@ -33,32 +111,19 @@ rename("/tmp/tmp_file.txt", "/home/user/login/docs/my_file.txt"); - - - Prior to PHP 4.3.3, rename could not rename files - across partitions on *nix based systems. - - - - - As of PHP 5.0.0 rename can also be - used with some URL wrappers. Refer to - for a listing of which wrappers support rename. - - - - - The wrapper used in oldname MUST - match the wrapper used in newname. - - - ¬e.context-support; + + + + &reftitle.seealso; - See also copy, - unlink, and - move_uploaded_file. + + copy + unlink + move_uploaded_file + + - + rewind Rewind the position of a file pointer - - Description + + + &reftitle.description; boolrewind resourcehandle @@ -16,24 +16,49 @@ Sets the file position indicator for handle to the beginning of the file stream. + + + If you have opened the file in append ("a" or "a+") mode, any data you + write to the file will always be appended, regardless of the file + position. + + + + + + &reftitle.parameters; + + + + handle + + + The file pointer must be valid, and must point to a file + successfully opened by fopen. + + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.seealso; - The file pointer must be valid, and must point to a file - successfully opened by fopen. - - - - If you have opened the file in append ("a" or "a+") mode, any data you write - to the file will always be appended, regardless of the file position. - - - - See also fseek and - ftell. + + fseek + ftell + + - + rmdir Removes directory - - Description + + + &reftitle.description; boolrmdir stringdirname @@ -16,21 +16,80 @@ Attempts to remove the directory named by dirname. The directory must be empty, and the relevant permissions must permit this. - &return.success; - - - - As of PHP 5.0.0 rmdir can also be - used with some URL wrappers. Refer to - for a listing of which wrappers support rmdir. - - - ¬e.context-support; - ¬e.sm.uidcheck.dir; - - See also mkdir and unlink. + + + &reftitle.parameters; + + + + dirname + + + Path to the directory. + + + + + context + + ¬e.context-support; + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + As of PHP 5.0.0 rmdir can also be used with + some URL wrappers. Refer to for a listing of which wrappers support + rmdir. + + + + + + + + + + &reftitle.notes; + ¬e.sm.uidcheck.dir; + + + + &reftitle.seealso; + + + mkdir + unlink + + + + - + set_file_buffer @@ -14,6 +13,7 @@ stream_set_write_buffer. + - + stat Gives information about a file - - Description + + + &reftitle.description; arraystat stringfilename Gathers the statistics of the file named by - filename. If filename - is a symbolic link, statistics are from the file itself, not the - symlink. lstat is identical to - stat except it would instead be based off the symlinks - status. + filename. If filename is a + symbolic link, statistics are from the file itself, not the symlink. - In case of error, stat returns &false;. It also - will throw a warning. + lstat is identical to stat + except it would instead be based off the symlinks status. + + + + &reftitle.parameters; - Returns an array with the statistics of the file with the - following elements. This array is zero-based. In addition to - returning these attributes in a numeric array, they can be accessed - with associative indices, as noted next to each parameter; this is - available since PHP 4.0.6: + + + filename + + + Path to the file. + + + + + + + + &reftitle.returnvalues; <function>stat</function> and <function>fstat</function> result @@ -109,26 +119,68 @@ <entry>blocks</entry> <entry>number of blocks allocated</entry> </row> - </tbody> </tgroup> </table> - * Only valid on systems supporting the st_blksize type - other systems (e.g. Windows) return -1. </para> - - ¬e.clearstatcache; - - &tip.fopen-wrapper.stat; - <para> - See also <function>lstat</function>, - <function>fstat</function>, - <function>filemtime</function>, and - <function>filegroup</function>. + In case of error, <function>stat</function> returns &false;. </para> </refsect1> + + <refsect1 role="errors"> + &reftitle.errors; + <para> + Upon failure, an <constant>E_WARNING</constant> is emitted. + </para> + </refsect1> + + <refsect1 role="changelog"> + &reftitle.changelog; + <para> + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>&Version;</entry> + <entry>&Description;</entry> + </row> + </thead> + <tbody> + <row> + <entry>4.0.6</entry> + <entry> + In addition to returning these attributes in a numeric array, they + can be accessed with associative indices, as noted next to each + parameter + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </refsect1> + + <refsect1 role="notes"> + &reftitle.notes; + ¬e.clearstatcache; + &tip.fopen-wrapper.stat; + </refsect1> + + <refsect1 role="seealso"> + &reftitle.seealso; + <para> + <simplelist> + <member><function>lstat</function></member> + <member><function>fstat</function></member> + <member><function>filemtime</function></member> + <member><function>filegroup</function></member> + </simplelist> + </para> + </refsect1> + </refentry> <!-- Keep this comment at the end of the file diff --git a/reference/filesystem/functions/symlink.xml b/reference/filesystem/functions/symlink.xml index 79552c293d..a7ec0425ac 100644 --- a/reference/filesystem/functions/symlink.xml +++ b/reference/filesystem/functions/symlink.xml @@ -1,33 +1,72 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.7 $ --> -<!-- splitted from ./en/functions/filesystem.xml, last change in rev 1.2 --> +<!-- $Revision: 1.8 $ --> <refentry id="function.symlink"> <refnamediv> <refname>symlink</refname> <refpurpose>Creates a symbolic link</refpurpose> </refnamediv> - <refsect1> - <title>Description + + + &reftitle.description; boolsymlink stringtarget stringlink - symlink creates a symbolic link - to the existing target with - the specified name link. + symlink creates a symbolic link to the existing + target with the specified name + link. + + + + &reftitle.parameters; + + + + target + + + Target of the link. + + + + + link + + + The link name. + + + + + + + + + &reftitle.returnvalues; &return.success; + + + + &reftitle.notes; ¬e.no-windows; + + + + &reftitle.seealso; - See also link to create hard links, - and readlink along with - linkinfo. + + link to create hard links + readlink along with + linkinfo + + - + tmpfile Creates a temporary file - - Description + + + &reftitle.description; resourcetmpfile - Creates a temporary file with a unique name in read-write (w+) mode, - returning a file handle similar to the one returned by - fopen. + Creates a temporary file with a unique name in read-write (w+) mode and + returns a file handle . + + The file is automatically removed when closed (using fclose), or when the script ends. @@ -24,6 +25,18 @@ tmpfile(3) function, as well as the stdio.h header file. + + + + &reftitle.returnvalues; + + Returns a file handle, similar to the one returned by + fopen, for the new file, or &false; on failure. + + + + + &reftitle.examples; <function>tmpfile</function> example @@ -46,10 +59,18 @@ writing to tempfile + + + + &reftitle.seealso; - See also tempnam, sys_get_temp_dir. + + tempnam + sys_get_temp_dir + + - + unlink Deletes a file - - Description + + + &reftitle.description; boolunlink stringfilename resourcecontext - Deletes filename. Similar to the Unix C - unlink() function. &return.success; - - - - As of PHP 5.0.0 unlink can also be - used with some URL wrappers. Refer to - for a listing of which wrappers support unlink. - - - ¬e.context-support; - - See also rmdir for removing directories. + Deletes filename. Similar to the Unix C unlink() + function. + + + &reftitle.parameters; + + + + filename + + + Path to the file. + + + + + context + + ¬e.context-support; + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + As of PHP 5.0.0 unlink can also be used with + some URL wrappers. Refer to for a listing of which wrappers support + unlink. + + + + + + + + + + &reftitle.seealso; + + + rmdir for removing directories + + + +