cvs: php4 /pear/Experimental/Archive/docs Tar.txt
| From: | Stig Bakken | Date: | Sat, 18 Aug 2001 19:08:55 +0000 |
| Subject: | cvs: php4 /pear/Experimental/Archive/docs Tar.txt | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-570@lists.php.net to get a copy of this message | ||
ssb Sat Aug 18 15:08:55 2001 EDT
Modified files:
/php4/pear/Experimental/Archive/docs Tar.txt
Log:
* wrapped to 80 columns
Index: php4/pear/Experimental/Archive/docs/Tar.txt diff -u php4/pear/Experimental/Archive/docs/Tar.txt:1.1 php4/pear/Experimental/Archive/docs/Tar.txt:1.2 --- php4/pear/Experimental/Archive/docs/Tar.txt:1.1 Thu Aug 16 03:25:56 2001 +++ php4/pear/Experimental/Archive/docs/Tar.txt Sat Aug 18 15:08:55 2001 @@ -7,9 +7,13 @@ Overview : ---------- - The Archive_Tar class helps in creating and managing GNU TAR format files compressed by GNU ZIP or not. - The class offers basic functions like creating an archive, adding files in the archive, extracting files from the archive and listing the archive content. - It also provide advanced functions that allow the adding and extraction of files with path manipulation. + The Archive_Tar class helps in creating and managing GNU TAR format + files compressed by GNU ZIP or not. + The class offers basic functions like creating an archive, adding + files in the archive, extracting files from the archive and listing + the archive content. + It also provide advanced functions that allow the adding and + extraction of files with path manipulation. Sample : @@ -62,11 +66,15 @@ Method : Archive_Tar($p_tarname, $compress = false) Description : - Archive_Tar Class constructor. This flavour of the constructor only declare a new Archive_Tar object, identifying it by the name of the tar file. - If the compress argument is set the tar will be read or created as a gzip compressed TAR file. + Archive_Tar Class constructor. This flavour of the constructor only + declare a new Archive_Tar object, identifying it by the name of the + tar file. + If the compress argument is set the tar will be read or created as a + gzip compressed TAR file. Arguments : $p_tarname : A valid filename for the tar archive file. - $p_compress : true/false. Indicate if the archive need to be compressed or not. + $p_compress : true/false. Indicate if the archive need to be + compressed or not. Return value : The Archive_Tar object. Sample : @@ -77,13 +85,23 @@ Method : Archive_Tar($p_tarname, $p_filelist, $p_compress = false) Description : - Archive_Tar Class constructor. This flavour of the constructor creates a Tar archive containing the files/directory indicated in $p_filelist. The archive can be compressed by gzip by using the $p_compress option. - If the file already exists and is writable, it is replaced by the new tar. It is a create and not an add. If the file exists and is read-only or is a directory it is not replaced. The method does not return error code (constructor) a PEAR error text is set (but no use ...). - For better error handling it is recommended to create the object, initialise PEAR error handling and call the create() method. + Archive_Tar Class constructor. This flavour of the constructor + creates a Tar archive containing the files/directory indicated in + $p_filelist. The archive can be compressed by gzip by using the + $p_compress option. + If the file already exists and is writable, it is replaced by the + new tar. It is a create and not an add. If the file exists and is + read-only or is a directory it is not replaced. The method does not + return error code (constructor) a PEAR error text is set (but no use + ...). + For better error handling it is recommended to create the object, + initialise PEAR error handling and call the create() method. Arguments : $p_tarname : A valid filename for the tar archive file. - $p_filelist : A list of files and/or directories. (see discussion in add() method about the list structure). - $p_compress : true/false. Indicate if the archive need to be compressed or not. + $p_filelist : A list of files and/or directories. (see discussion in + add() method about the list structure). + $p_compress : true/false. Indicate if the archive need to be + compressed or not. Return value : The Archive_Tar object. Sample 1 : @@ -98,12 +116,20 @@ Method : create($p_filelist) Description : - This method creates the archive file and add the files / directories that are listed in $p_filelist. - If the file already exists and is writable, it is replaced by the new tar. It is a create and not an add. If the file exists and is read-only or is a directory it is not replaced. The method return false and a PEAR error text. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. + This method creates the archive file and add the files / directories + that are listed in $p_filelist. + If the file already exists and is writable, it is replaced by the + new tar. It is a create and not an add. If the file exists and is + read-only or is a directory it is not replaced. The method return + false and a PEAR error text. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. See also createModify() method for more details. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. Return value : true on success, false on error. Sample 1 : @@ -122,17 +148,34 @@ Method : createModify($p_filelist, $p_add_dir, $p_remove_dir = "") Description : - This method creates the archive file and add the files / directories that are listed in $p_filelist. - If the file already exists and is writable, it is replaced by the new tar. It is a create and not an add. If the file exists and is read-only or is a directory it is not replaced. The method return false and a PEAR error text. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. - The path indicated in $p_remove_dir will be removed from the memorized path of each file / directory listed when this path exists. By default nothing is removed (empty path "") - The path indicated in $p_add_dir will be added at the beginning of the memorized path of each file / directory listed. However it can be set to empty "". The adding of a path is done after the removing of path. - The path add/remove ability enables the user to prepare an archive for extraction in a different path than the origin files are. + This method creates the archive file and add the files / directories + that are listed in $p_filelist. + If the file already exists and is writable, it is replaced by the + new tar. It is a create and not an add. If the file exists and is + read-only or is a directory it is not replaced. The method return + false and a PEAR error text. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. + The path indicated in $p_remove_dir will be removed from the + memorized path of each file / directory listed when this path + exists. By default nothing is removed (empty path "") + The path indicated in $p_add_dir will be added at the beginning of + the memorized path of each file / directory listed. However it can + be set to empty "". The adding of a path is done after the removing + of path. + The path add/remove ability enables the user to prepare an archive + for extraction in a different path than the origin files are. See also addModify() method for file adding properties. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. - $p_add_dir : A string which contains a path to be added to the memorized path of each element in the list. - $p_remove_dir : A string which contains a path to be removed from the memorized path of each element in the list, when relevant. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. + $p_add_dir : A string which contains a path to be added to the + memorized path of each element in the list. + $p_remove_dir : A string which contains a path to be removed from + the memorized path of each element in the list, when + relevant. Return value : true on success, false on error. Sample 1 : @@ -169,19 +212,42 @@ Method : addModify($p_filelist, $p_add_dir, $p_remove_dir="") Description : - This method add the files / directories listed in $p_filelist at the end of the existing archive. If the archive does not yet exists it is created. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. - The path indicated in $p_remove_dir will be removed from the memorized path of each file / directory listed when this path exists. By default nothing is removed (empty path "") - The path indicated in $p_add_dir will be added at the beginning of the memorized path of each file / directory listed. However it can be set to empty "". The adding of a path is done after the removing of path. - The path add/remove ability enables the user to prepare an archive for extraction in a different path than the origin files are. - If a file/dir is already in the archive it will only be added at the end of the archive. There is no update of the existing archived file/dir. However while extracting the archive, the last file will replace the first one. This results in a none optimization of the archive size. - If a file/dir does not exist the file/dir is ignored. However an error text is send to PEAR error. - If a file/dir is not readable the file/dir is ignored. However an error text is send to PEAR error. - If the resulting filename/dirname (after the add/remove option or not) string is greater than 99 char, the file/dir is ignored. However an error text is send to PEAR error. + This method add the files / directories listed in $p_filelist at the + end of the existing archive. If the archive does not yet exists it + is created. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. + The path indicated in $p_remove_dir will be removed from the + memorized path of each file / directory listed when this path + exists. By default nothing is removed (empty path "") + The path indicated in $p_add_dir will be added at the beginning of + the memorized path of each file / directory listed. However it can + be set to empty "". The adding of a path is done after the removing + of path. + The path add/remove ability enables the user to prepare an archive + for extraction in a different path than the origin files are. + If a file/dir is already in the archive it will only be added at the + end of the archive. There is no update of the existing archived + file/dir. However while extracting the archive, the last file will + replace the first one. This results in a none optimization of the + archive size. + If a file/dir does not exist the file/dir is ignored. However an + error text is send to PEAR error. + If a file/dir is not readable the file/dir is ignored. However an + error text is send to PEAR error. + If the resulting filename/dirname (after the add/remove option or + not) string is greater than 99 char, the file/dir is + ignored. However an error text is send to PEAR error. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. - $p_add_dir : A string which contains a path to be added to the memorized path of each element in the list. - $p_remove_dir : A string which contains a path to be removed from the memorized path of each element in the list, when relevant. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. + $p_add_dir : A string which contains a path to be added to the + memorized path of each element in the list. + $p_remove_dir : A string which contains a path to be removed from + the memorized path of each element in the list, when + relevant. Return value : true on success, false on error. Sample 1 : @@ -212,17 +278,31 @@ // install/log/file.log How it works : If the archive does not exists it create it and add the files. - If the archive does exists and is not compressed, it open it, jump before the last empty 512 bytes block (tar footer) and add the files at this point. - If the archive does exists and is compressed, a temporary copy file is created. This temporary file is then 'gzip' read block by block until the last empty block. The new files are then added in the compressed file. - The adding of files is done by going through the file/dir list, adding files per files, in a recursive way through the directory. Each time a path need to be added/removed it is done before writing the file header in the archive. + If the archive does exists and is not compressed, it open it, jump + before the last empty 512 bytes block (tar footer) and add the files + at this point. + If the archive does exists and is compressed, a temporary copy file + is created. This temporary file is then 'gzip' read block by block + until the last empty block. The new files are then added in the + compressed file. + The adding of files is done by going through the file/dir list, + adding files per files, in a recursive way through the + directory. Each time a path need to be added/removed it is done + before writing the file header in the archive. Method : add($p_filelist) Description : - This method add the files / directories listed in $p_filelist at the end of the existing archive. If the archive does not yet exists it is created. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. + This method add the files / directories listed in $p_filelist at the + end of the existing archive. If the archive does not yet exists it + is created. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. See addModify() method for details and limitations. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. Return value : true on success, false on error. Sample 1 : @@ -244,8 +324,11 @@ Method : extract($p_path = "") Description : - This method extract all the content of the archive in the directory indicated by $p_path.If $p_path is optional, if not set the archive is extracted in the current directory. - While extracting a file, if the directory path does not exists it is created. + This method extract all the content of the archive in the directory + indicated by $p_path.If $p_path is optional, if not set the archive + is extracted in the current directory. + While extracting a file, if the directory path does not exists it is + created. See extractModify() for details and limitations. Arguments : $p_path : Optional path where the files/dir need to by extracted. @@ -259,18 +342,33 @@ Method : extractModify($p_path, $p_remove_path) Description : - This method extract all the content of the archive in the directory indicated by $p_path. When relevant the memorized path of the files/dir can be modified by removing the $p_remove_path path at the beginning of the file/dir path. - While extracting a file, if the directory path does not exists it is created. - While extracting a file, if the file already exists it is replaced without looking for last modification date. - While extracting a file, if the file already exists and is write protected, the extraction is aborted. - While extracting a file, if a directory with the same name already exists, the extraction is aborted. - While extracting a directory, if a file with the same name already exists, the extraction is aborted. - While extracting a file/directory if the destination directory exist and is write protected, or does not exist but can not be created, the extraction is aborted. - If after extraction an extracted file does not show the correct stored file size, the extraction is aborted. - When the extraction is aborted, a PEAR error text is set and false is returned. However the result can be a partial extraction that may need to be manually cleaned. + This method extract all the content of the archive in the directory + indicated by $p_path. When relevant the memorized path of the + files/dir can be modified by removing the $p_remove_path path at the + beginning of the file/dir path. + While extracting a file, if the directory path does not exists it is + created. + While extracting a file, if the file already exists it is replaced + without looking for last modification date. + While extracting a file, if the file already exists and is write + protected, the extraction is aborted. + While extracting a file, if a directory with the same name already + exists, the extraction is aborted. + While extracting a directory, if a file with the same name already + exists, the extraction is aborted. + While extracting a file/directory if the destination directory exist + and is write protected, or does not exist but can not be created, + the extraction is aborted. + If after extraction an extracted file does not show the correct + stored file size, the extraction is aborted. + When the extraction is aborted, a PEAR error text is set and false + is returned. However the result can be a partial extraction that may + need to be manually cleaned. Arguments : - $p_path : The path of the directory where the files/dir need to by extracted. - $p_remove_path : Part of the memorized path that can be removed if present at the beginning of the file/dir path. + $p_path : The path of the directory where the files/dir need to by + extracted. + $p_remove_path : Part of the memorized path that can be removed if + present at the beginning of the file/dir path. Return value : true on success, false on error. Sample : @@ -285,13 +383,16 @@ // install/data/log.txt // install/readme.txt How it works : - Open the archive and call a more generic function that can extract only a part of the archive or all the archive. + Open the archive and call a more generic function that can extract + only a part of the archive or all the archive. See extractList() method for more details. Method : listContent() Description : - This method returns an array of arrays that describe each file/directory present in the archive. - The array is not sorted, so it show the position of the file in the archive. + This method returns an array of arrays that describe each + file/directory present in the archive. + The array is not sorted, so it show the position of the file in the + archive. The file informations are : $file[filename] : Name and path of the file/dir. $file[mode] : File permissions (result of fileperms()) @@ -310,23 +411,31 @@ { echo "Filename :'".$v_list[$i][filename]."'<br>"; echo " .size :'".$v_list[$i][size]."'<br>"; - echo " .mtime :'".$v_list[$i][mtime]."' (".date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>"; + echo " .mtime :'".$v_list[$i][mtime]."' (". + date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>"; echo " .mode :'".$v_list[$i][mode]."'<br>"; echo " .uid :'".$v_list[$i][uid]."'<br>"; echo " .gid :'".$v_list[$i][gid]."'<br>"; echo " .typeflag :'".$v_list[$i][typeflag]."'<br>"; } How it works : - Call the same function as an extract however with a flag to only go through the archive without extracting the files. + Call the same function as an extract however with a flag to only go + through the archive without extracting the files. Method : extractList($p_filelist, $p_path = "", $p_remove_path = "") Description : - This method extract from the archive only the files indicated in the $p_filelist. These files are extracted in the current directory or in the directory indicated by the optional $p_path parameter. - If indicated the $p_remove_path can be used in the same way as it is used in extractModify() method. + This method extract from the archive only the files indicated in the + $p_filelist. These files are extracted in the current directory or + in the directory indicated by the optional $p_path parameter. + If indicated the $p_remove_path can be used in the same way as it is + used in extractModify() method. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. - $p_path : The path of the directory where the files/dir need to by extracted. - $p_remove_path : Part of the memorized path that can be removed if present at the beginning of the file/dir path. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. + $p_path : The path of the directory where the files/dir need to by + extracted. + $p_remove_path : Part of the memorized path that can be removed if + present at the beginning of the file/dir path. Return value : true on success, false on error. Sample : @@ -335,10 +444,12 @@ // dev/data/log.txt // readme.txt $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extractList("dev/data/file.txt readme.txt", "install", "dev"); + $tar_object->extractList("dev/data/file.txt readme.txt", "install", + "dev"); // Files will be extracted there : // install/data/file.txt // install/readme.txt How it works : - Go through the archive and extract only the files present in the list. + Go through the archive and extract only the files present in the + list.
Index: php4/pear/Experimental/Archive/docs/Tar.txt diff -u php4/pear/Experimental/Archive/docs/Tar.txt:1.1 php4/pear/Experimental/Archive/docs/Tar.txt:1.2 --- php4/pear/Experimental/Archive/docs/Tar.txt:1.1 Thu Aug 16 03:25:56 2001 +++ php4/pear/Experimental/Archive/docs/Tar.txt Sat Aug 18 15:08:55 2001 @@ -7,9 +7,13 @@ Overview : ---------- - The Archive_Tar class helps in creating and managing GNU TAR format files compressed by GNU ZIP or not. - The class offers basic functions like creating an archive, adding files in the archive, extracting files from the archive and listing the archive content. - It also provide advanced functions that allow the adding and extraction of files with path manipulation. + The Archive_Tar class helps in creating and managing GNU TAR format + files compressed by GNU ZIP or not. + The class offers basic functions like creating an archive, adding + files in the archive, extracting files from the archive and listing + the archive content. + It also provide advanced functions that allow the adding and + extraction of files with path manipulation. Sample : @@ -62,11 +66,15 @@ Method : Archive_Tar($p_tarname, $compress = false) Description : - Archive_Tar Class constructor. This flavour of the constructor only declare a new Archive_Tar object, identifying it by the name of the tar file. - If the compress argument is set the tar will be read or created as a gzip compressed TAR file. + Archive_Tar Class constructor. This flavour of the constructor only + declare a new Archive_Tar object, identifying it by the name of the + tar file. + If the compress argument is set the tar will be read or created as a + gzip compressed TAR file. Arguments : $p_tarname : A valid filename for the tar archive file. - $p_compress : true/false. Indicate if the archive need to be compressed or not. + $p_compress : true/false. Indicate if the archive need to be + compressed or not. Return value : The Archive_Tar object. Sample : @@ -77,13 +85,23 @@ Method : Archive_Tar($p_tarname, $p_filelist, $p_compress = false) Description : - Archive_Tar Class constructor. This flavour of the constructor creates a Tar archive containing the files/directory indicated in $p_filelist. The archive can be compressed by gzip by using the $p_compress option. - If the file already exists and is writable, it is replaced by the new tar. It is a create and not an add. If the file exists and is read-only or is a directory it is not replaced. The method does not return error code (constructor) a PEAR error text is set (but no use ...). - For better error handling it is recommended to create the object, initialise PEAR error handling and call the create() method. + Archive_Tar Class constructor. This flavour of the constructor + creates a Tar archive containing the files/directory indicated in + $p_filelist. The archive can be compressed by gzip by using the + $p_compress option. + If the file already exists and is writable, it is replaced by the + new tar. It is a create and not an add. If the file exists and is + read-only or is a directory it is not replaced. The method does not + return error code (constructor) a PEAR error text is set (but no use + ...). + For better error handling it is recommended to create the object, + initialise PEAR error handling and call the create() method. Arguments : $p_tarname : A valid filename for the tar archive file. - $p_filelist : A list of files and/or directories. (see discussion in add() method about the list structure). - $p_compress : true/false. Indicate if the archive need to be compressed or not. + $p_filelist : A list of files and/or directories. (see discussion in + add() method about the list structure). + $p_compress : true/false. Indicate if the archive need to be + compressed or not. Return value : The Archive_Tar object. Sample 1 : @@ -98,12 +116,20 @@ Method : create($p_filelist) Description : - This method creates the archive file and add the files / directories that are listed in $p_filelist. - If the file already exists and is writable, it is replaced by the new tar. It is a create and not an add. If the file exists and is read-only or is a directory it is not replaced. The method return false and a PEAR error text. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. + This method creates the archive file and add the files / directories + that are listed in $p_filelist. + If the file already exists and is writable, it is replaced by the + new tar. It is a create and not an add. If the file exists and is + read-only or is a directory it is not replaced. The method return + false and a PEAR error text. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. See also createModify() method for more details. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. Return value : true on success, false on error. Sample 1 : @@ -122,17 +148,34 @@ Method : createModify($p_filelist, $p_add_dir, $p_remove_dir = "") Description : - This method creates the archive file and add the files / directories that are listed in $p_filelist. - If the file already exists and is writable, it is replaced by the new tar. It is a create and not an add. If the file exists and is read-only or is a directory it is not replaced. The method return false and a PEAR error text. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. - The path indicated in $p_remove_dir will be removed from the memorized path of each file / directory listed when this path exists. By default nothing is removed (empty path "") - The path indicated in $p_add_dir will be added at the beginning of the memorized path of each file / directory listed. However it can be set to empty "". The adding of a path is done after the removing of path. - The path add/remove ability enables the user to prepare an archive for extraction in a different path than the origin files are. + This method creates the archive file and add the files / directories + that are listed in $p_filelist. + If the file already exists and is writable, it is replaced by the + new tar. It is a create and not an add. If the file exists and is + read-only or is a directory it is not replaced. The method return + false and a PEAR error text. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. + The path indicated in $p_remove_dir will be removed from the + memorized path of each file / directory listed when this path + exists. By default nothing is removed (empty path "") + The path indicated in $p_add_dir will be added at the beginning of + the memorized path of each file / directory listed. However it can + be set to empty "". The adding of a path is done after the removing + of path. + The path add/remove ability enables the user to prepare an archive + for extraction in a different path than the origin files are. See also addModify() method for file adding properties. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. - $p_add_dir : A string which contains a path to be added to the memorized path of each element in the list. - $p_remove_dir : A string which contains a path to be removed from the memorized path of each element in the list, when relevant. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. + $p_add_dir : A string which contains a path to be added to the + memorized path of each element in the list. + $p_remove_dir : A string which contains a path to be removed from + the memorized path of each element in the list, when + relevant. Return value : true on success, false on error. Sample 1 : @@ -169,19 +212,42 @@ Method : addModify($p_filelist, $p_add_dir, $p_remove_dir="") Description : - This method add the files / directories listed in $p_filelist at the end of the existing archive. If the archive does not yet exists it is created. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. - The path indicated in $p_remove_dir will be removed from the memorized path of each file / directory listed when this path exists. By default nothing is removed (empty path "") - The path indicated in $p_add_dir will be added at the beginning of the memorized path of each file / directory listed. However it can be set to empty "". The adding of a path is done after the removing of path. - The path add/remove ability enables the user to prepare an archive for extraction in a different path than the origin files are. - If a file/dir is already in the archive it will only be added at the end of the archive. There is no update of the existing archived file/dir. However while extracting the archive, the last file will replace the first one. This results in a none optimization of the archive size. - If a file/dir does not exist the file/dir is ignored. However an error text is send to PEAR error. - If a file/dir is not readable the file/dir is ignored. However an error text is send to PEAR error. - If the resulting filename/dirname (after the add/remove option or not) string is greater than 99 char, the file/dir is ignored. However an error text is send to PEAR error. + This method add the files / directories listed in $p_filelist at the + end of the existing archive. If the archive does not yet exists it + is created. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. + The path indicated in $p_remove_dir will be removed from the + memorized path of each file / directory listed when this path + exists. By default nothing is removed (empty path "") + The path indicated in $p_add_dir will be added at the beginning of + the memorized path of each file / directory listed. However it can + be set to empty "". The adding of a path is done after the removing + of path. + The path add/remove ability enables the user to prepare an archive + for extraction in a different path than the origin files are. + If a file/dir is already in the archive it will only be added at the + end of the archive. There is no update of the existing archived + file/dir. However while extracting the archive, the last file will + replace the first one. This results in a none optimization of the + archive size. + If a file/dir does not exist the file/dir is ignored. However an + error text is send to PEAR error. + If a file/dir is not readable the file/dir is ignored. However an + error text is send to PEAR error. + If the resulting filename/dirname (after the add/remove option or + not) string is greater than 99 char, the file/dir is + ignored. However an error text is send to PEAR error. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. - $p_add_dir : A string which contains a path to be added to the memorized path of each element in the list. - $p_remove_dir : A string which contains a path to be removed from the memorized path of each element in the list, when relevant. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. + $p_add_dir : A string which contains a path to be added to the + memorized path of each element in the list. + $p_remove_dir : A string which contains a path to be removed from + the memorized path of each element in the list, when + relevant. Return value : true on success, false on error. Sample 1 : @@ -212,17 +278,31 @@ // install/log/file.log How it works : If the archive does not exists it create it and add the files. - If the archive does exists and is not compressed, it open it, jump before the last empty 512 bytes block (tar footer) and add the files at this point. - If the archive does exists and is compressed, a temporary copy file is created. This temporary file is then 'gzip' read block by block until the last empty block. The new files are then added in the compressed file. - The adding of files is done by going through the file/dir list, adding files per files, in a recursive way through the directory. Each time a path need to be added/removed it is done before writing the file header in the archive. + If the archive does exists and is not compressed, it open it, jump + before the last empty 512 bytes block (tar footer) and add the files + at this point. + If the archive does exists and is compressed, a temporary copy file + is created. This temporary file is then 'gzip' read block by block + until the last empty block. The new files are then added in the + compressed file. + The adding of files is done by going through the file/dir list, + adding files per files, in a recursive way through the + directory. Each time a path need to be added/removed it is done + before writing the file header in the archive. Method : add($p_filelist) Description : - This method add the files / directories listed in $p_filelist at the end of the existing archive. If the archive does not yet exists it is created. - The $p_filelist parameter can be an array of string, each string representing a filename or a directory name with their path if needed. It can also be a single string with names separated by a single blank. + This method add the files / directories listed in $p_filelist at the + end of the existing archive. If the archive does not yet exists it + is created. + The $p_filelist parameter can be an array of string, each string + representing a filename or a directory name with their path if + needed. It can also be a single string with names separated by a + single blank. See addModify() method for details and limitations. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. Return value : true on success, false on error. Sample 1 : @@ -244,8 +324,11 @@ Method : extract($p_path = "") Description : - This method extract all the content of the archive in the directory indicated by $p_path.If $p_path is optional, if not set the archive is extracted in the current directory. - While extracting a file, if the directory path does not exists it is created. + This method extract all the content of the archive in the directory + indicated by $p_path.If $p_path is optional, if not set the archive + is extracted in the current directory. + While extracting a file, if the directory path does not exists it is + created. See extractModify() for details and limitations. Arguments : $p_path : Optional path where the files/dir need to by extracted. @@ -259,18 +342,33 @@ Method : extractModify($p_path, $p_remove_path) Description : - This method extract all the content of the archive in the directory indicated by $p_path. When relevant the memorized path of the files/dir can be modified by removing the $p_remove_path path at the beginning of the file/dir path. - While extracting a file, if the directory path does not exists it is created. - While extracting a file, if the file already exists it is replaced without looking for last modification date. - While extracting a file, if the file already exists and is write protected, the extraction is aborted. - While extracting a file, if a directory with the same name already exists, the extraction is aborted. - While extracting a directory, if a file with the same name already exists, the extraction is aborted. - While extracting a file/directory if the destination directory exist and is write protected, or does not exist but can not be created, the extraction is aborted. - If after extraction an extracted file does not show the correct stored file size, the extraction is aborted. - When the extraction is aborted, a PEAR error text is set and false is returned. However the result can be a partial extraction that may need to be manually cleaned. + This method extract all the content of the archive in the directory + indicated by $p_path. When relevant the memorized path of the + files/dir can be modified by removing the $p_remove_path path at the + beginning of the file/dir path. + While extracting a file, if the directory path does not exists it is + created. + While extracting a file, if the file already exists it is replaced + without looking for last modification date. + While extracting a file, if the file already exists and is write + protected, the extraction is aborted. + While extracting a file, if a directory with the same name already + exists, the extraction is aborted. + While extracting a directory, if a file with the same name already + exists, the extraction is aborted. + While extracting a file/directory if the destination directory exist + and is write protected, or does not exist but can not be created, + the extraction is aborted. + If after extraction an extracted file does not show the correct + stored file size, the extraction is aborted. + When the extraction is aborted, a PEAR error text is set and false + is returned. However the result can be a partial extraction that may + need to be manually cleaned. Arguments : - $p_path : The path of the directory where the files/dir need to by extracted. - $p_remove_path : Part of the memorized path that can be removed if present at the beginning of the file/dir path. + $p_path : The path of the directory where the files/dir need to by + extracted. + $p_remove_path : Part of the memorized path that can be removed if + present at the beginning of the file/dir path. Return value : true on success, false on error. Sample : @@ -285,13 +383,16 @@ // install/data/log.txt // install/readme.txt How it works : - Open the archive and call a more generic function that can extract only a part of the archive or all the archive. + Open the archive and call a more generic function that can extract + only a part of the archive or all the archive. See extractList() method for more details. Method : listContent() Description : - This method returns an array of arrays that describe each file/directory present in the archive. - The array is not sorted, so it show the position of the file in the archive. + This method returns an array of arrays that describe each + file/directory present in the archive. + The array is not sorted, so it show the position of the file in the + archive. The file informations are : $file[filename] : Name and path of the file/dir. $file[mode] : File permissions (result of fileperms()) @@ -310,23 +411,31 @@ { echo "Filename :'".$v_list[$i][filename]."'<br>"; echo " .size :'".$v_list[$i][size]."'<br>"; - echo " .mtime :'".$v_list[$i][mtime]."' (".date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>"; + echo " .mtime :'".$v_list[$i][mtime]."' (". + date("l dS of F Y h:i:s A", $v_list[$i][mtime]).")<br>"; echo " .mode :'".$v_list[$i][mode]."'<br>"; echo " .uid :'".$v_list[$i][uid]."'<br>"; echo " .gid :'".$v_list[$i][gid]."'<br>"; echo " .typeflag :'".$v_list[$i][typeflag]."'<br>"; } How it works : - Call the same function as an extract however with a flag to only go through the archive without extracting the files. + Call the same function as an extract however with a flag to only go + through the archive without extracting the files. Method : extractList($p_filelist, $p_path = "", $p_remove_path = "") Description : - This method extract from the archive only the files indicated in the $p_filelist. These files are extracted in the current directory or in the directory indicated by the optional $p_path parameter. - If indicated the $p_remove_path can be used in the same way as it is used in extractModify() method. + This method extract from the archive only the files indicated in the + $p_filelist. These files are extracted in the current directory or + in the directory indicated by the optional $p_path parameter. + If indicated the $p_remove_path can be used in the same way as it is + used in extractModify() method. Arguments : - $p_filelist : An array of filenames and directory names, or a single string with names separated by a single blank space. - $p_path : The path of the directory where the files/dir need to by extracted. - $p_remove_path : Part of the memorized path that can be removed if present at the beginning of the file/dir path. + $p_filelist : An array of filenames and directory names, or a single + string with names separated by a single blank space. + $p_path : The path of the directory where the files/dir need to by + extracted. + $p_remove_path : Part of the memorized path that can be removed if + present at the beginning of the file/dir path. Return value : true on success, false on error. Sample : @@ -335,10 +444,12 @@ // dev/data/log.txt // readme.txt $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extractList("dev/data/file.txt readme.txt", "install", "dev"); + $tar_object->extractList("dev/data/file.txt readme.txt", "install", + "dev"); // Files will be extracted there : // install/data/file.txt // install/readme.txt How it works : - Go through the archive and extract only the files present in the list. + Go through the archive and extract only the files present in the + list.