diff options
Diffstat (limited to 'pear/docs/Archive_Tar.txt')
| -rw-r--r-- | pear/docs/Archive_Tar.txt | 424 |
1 files changed, 0 insertions, 424 deletions
diff --git a/pear/docs/Archive_Tar.txt b/pear/docs/Archive_Tar.txt deleted file mode 100644 index 73bee0d786..0000000000 --- a/pear/docs/Archive_Tar.txt +++ /dev/null @@ -1,424 +0,0 @@ -Documentation for class Archive_Tar -=================================== -Last update : 2001-08-15 - - - -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. - - -Sample : --------- - - // ----- Creating the object (uncompressed archive) - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); - - // ----- Creating the archive - $v_list[0]="file.txt"; - $v_list[1]="data/"; - $v_list[2]="file.log"; - $tar_object->create($v_list); - - // ----- Adding files - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; - $v_list[2]="log/file.log"; - $tar_object->add($v_list); - - // ----- Adding more files - $tar_object->add("release/newfile.log release/readme.txt"); - - // ----- Listing the content - if (($v_list = $tar_object->listContent()) != 0) - for ($i=0; $i<sizeof($v_list); $i++) - { - 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 " .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>"; - } - - // ----- Extracting the archive in directory "install" - $tar_object->extract("install"); - - -Public arguments : ------------------- - -None - - -Public Methods : ----------------- - -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. -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. -Return value : - The Archive_Tar object. -Sample : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object_compressed = new Archive_Tar("tarname.tgz", true); -How it works : - Initialize the object. - -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. - 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. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $v_list[0]="file.txt"; - $v_list[1]="data/"; (Optional '/' at the end) - $v_list[2]="file.log"; - $tar_object->create($v_list); -Sample 2 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $tar_object->create("file.txt data/ file.log"); -How it works : - Just calling the createModify() method with the right parameters. - -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. - 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. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $v_list[0]="file.txt"; - $v_list[1]="data/"; (Optional '/' at the end) - $v_list[2]="file.log"; - $tar_object->createModify($v_list, "install"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/file.log -Sample 2 : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->setErrorHandling(PEAR_ERROR_PRINT); // Optional error handling - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->createModify($v_list, "install", "dev"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/log/file.log -How it works : - Open the file in write mode (erasing the existing one if one), - call the _addList() method for adding the files in an empty archive, - add the tar footer (512 bytes block), close the tar file. - - -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. -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. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->addModify($v_list, "install"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // install/file.log -Sample 2 : - $tar_object = new Archive_Tar("tarname.tar"); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->addModify($v_list, "install", "dev"); - // files are stored in the archive as : - // install/file.txt - // install/data - // install/data/file1.txt - // install/data/... all the files and sub-dirs of data/ - // 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. - -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. - 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. -Return value : - true on success, false on error. -Sample 1 : - $tar_object = new Archive_Tar("tarname.tar"); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->add($v_list); -Sample 2 : - $tar_object = new Archive_Tar("tarname.tgz", true); - [...] - $v_list[0]="dev/file.txt"; - $v_list[1]="dev/data/"; (Optional '/' at the end) - $v_list[2]="log/file.log"; - $tar_object->add($v_list); -How it works : - Simply call the addModify() method with the right parameters. - -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. - See extractModify() for details and limitations. -Arguments : - $p_path : Optional path where the files/dir need to by extracted. -Return value : - true on success, false on error. -Sample : - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extract(); -How it works : - Simply call the extractModify() method with appropriate parameters. - -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. -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. -Return value : - true on success, false on error. -Sample : - // Imagine tarname.tar with files : - // dev/data/file.txt - // dev/data/log.txt - // readme.txt - $tar_object = new Archive_Tar("tarname.tar"); - $tar_object->extractModify("install", "dev"); - // Files will be extracted there : - // install/data/file.txt - // 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. - 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. - The file informations are : - $file[filename] : Name and path of the file/dir. - $file[mode] : File permissions (result of fileperms()) - $file[uid] : user id - $file[gid] : group id - $file[size] : filesize - $file[mtime] : Last modification time (result of filemtime()) - $file[typeflag] : "" for file, "5" for directory -Arguments : -Return value : - An array of arrays or 0 on error. -Sample : - $tar_object = new Archive_Tar("tarname.tar"); - if (($v_list = $tar_object->listContent()) != 0) - for ($i=0; $i<sizeof($v_list); $i++) - { - 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 " .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. - -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. -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. -Return value : - true on success, false on error. -Sample : - // Imagine tarname.tar with files : - // dev/data/file.txt - // dev/data/log.txt - // readme.txt - $tar_object = new Archive_Tar("tarname.tar"); - $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. - |