PhpConcept

Developers Tools

  • Increase font size
  • Default font size
  • Decrease font size
Home PclTar User Guide

PclTar User Guide

Print PDF

 

Table of content

Functions description

The library is made of one file : pcltar.lib.php3 and two secondary libraries, the first one for trace management (pcltrace.lib.php3) and the other one for error management (pclerror.lib.php3).

The library define public functions available for the user, and internal functions which are called by the first ones. Only the public functions are described in this manual.

Please note that effort for compatibility will only be done on public functions while releasing new version. Modifications will be indicated in release notes. Internal function must not be used directly and may change without any notice.

Functions are also detailed in their header in the PHP file, here is only an other description:

 

PclTarCreate($p_tarname, $p_list, $p_mode, $p_add_dir, $p_remove_dir) :

Create a new archive with name $p_tarname. If files or folders are listed in $p_list, they will be added.
If the archive extension ($p_tarname) is '.tar', then the archive will not be compressed (standard GNU TAR), if it is '.tar.gz' or '.tgz', the archive will be compressed with gzip functions. If you want to use an other extension, the archive format must be indicated in $p_mode ('tar' ou 'tgz').

The $p_list, $p_add_dir and $p_remove_dir parameters and the adding methodology are fully described in PclTarAddList().

 

PclTarAddList($p_tarname, $p_list, $p_add_dir, $p_remove_dir, $p_mode) :

Add to an already existing archive a list of files or folders which names are in $p_list.
Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

The $p_list parameter may be :

  • An array of strings, each one representing the name of a file or a folder,
  • A string with the name of a file or a folder to archive,
  • A string which contains a list of file or folder names, separated by a space character.

PclTarAddList() automatically recognize if the given name is a file or a folder and if it is readable or not. If it is a folder, all the files and sub-folders are added in the archive (kind of recursive function).
Note that since version 1.2 if a folder is empty, a directory entry is created for this folder without files inside.

The relative path of the file is stored in the archive, however it is reduced as far as possible :

  • data/../include/file.txt will give include/file.txt
  • ./include/file.txt will give include/file.txt
  • ../../include/file.txt will give include/file.txt
  • etc ...

$p_add_dir and $p_remove_dir gives the ability to store with the file / directory a path which is not the real path of the original file / directory :

When using PclTarAddList("archive.tgz", "dev/include/conf.txt", "release", "dev"), the archive will contain a file with path "release/include/conf.txt".

While adding a large number of files the maximum script execution time may be reached. Be carefull also with folder when their contents are unknown.

 

PclTarAdd($p_tarname, $p_list) :

This function must not be used anymore. Please prefer PclTarAddList().

 

PclTarList($p_tarname, $p_mode) :

Give the list of files included int he archive $p_tarname.
The return value of the function is an array which contains an array of files properties on success, 0 on error.
Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

The files properties are :

  • list[0][filename] : filename of file 0,
  • list[0][mode] : Access mode of file 0 (see chmod()),
  • list[0][size] : Size of file 0,
  • list[0][uid] : Owner of file 0,
  • list[0][gid] : Group of file 0,
  • list[0][mtime] : Last modification date of file 0,
  • list[0][typeflag] : File type 0 (0 for "file", 1 for "link", 5 for "directory"),
  • list[0][status] : Status of the action on the file (ok, added, updated, not_updated, already_a_directory, write_protected, newer_exist, path_creation_fail, write_error).

 

PclTarExtract($p_tarname, $p_path, $p_remove_path, $p_mode) :

Extract all the files of the archive in the directory $p_path. The relative path of each file is maintained relative to $p_path. However, by using $p_remove_path the first part of the archived file path can be removed.

If a file is stored as "dev/include/conf.txt" in the archive and extracted by PclTarExtract("archive.tgz", "data", "dev"), the file will be written in "data/include/conf.txt".

If a file with the same name exists it will be replaced only if the archived file is newer. If older, the file is not extracted and the "status" field in the file descriptor is set with value "newer_exist".
While extracting a file if a directory exists with the same name, the file is not extracted. The "status" field in the file descriptor is set with value "already_a_directory".

While extracting a file if a file exists with the same name and is write protected, the file is not extracted. The "status" field in the file descriptor is set with value "write_protected".
The same behavior is implemented for directory extracting.

The function returns the extracted list of files in the same format as PclTarList().

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

 

PclTarExtractList($p_tarname, $p_list, $p_path, $p_remove_path, $p_mode) :

This function is the same as PcltarExtract(), but only the files or folders indicated in $p_list are extracted.

 

PclTarExtractIndex($p_tarname, $p_index, $p_path, $p_remove_path, $p_mode) :

This function is the same as PcltarExtract(), but only the files or folders which indexes in the archive are secified in the $p_index parameter are extracted.

The $p_index parameter is a single string with the index of the file or folder to extract, or several ranges of indexes of files/folders to extract. In this case th $p_index format is : '2,5-10,11,14,19-33', a list of values separated by a comma ','. Each value is an index or a range of indexes. The range is composed by two values (star and end included) separated by a '-'.
Please note that the $p_index format does not support any other characters than the numbers, ',' and '-'. (Spaces and ';' are not supported).

Moreover, if the index identify a folder in the archive, only the folder is created (extracted) but not the sub-directories and nor the files of this folder.

 

PclTarDelete($p_tarname, $p_filelist, $p_mode) :

Delete the files indicated in list $p_filelist from the archive $p_tarname.

The $p_filelist can be an array of filenames or directories, or a single string containing a list of filenames or directories separated by a single space.

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

When a folder is specified to be removed, all the sub-directories and files which are archived under this folder are also removed (new as of release 1.3).

 

PclTarUpdate($p_tarname, $p_filelist, $p_mode, $p_add_dir, $p_remove_dir) :

The files indicated in $p_filelist are updated in the archive $p_tarname if their last modification date is better than the one already stored. If the file does not exist in the archive, it is added at the end (same behavior as PclTarAddList()).

The $p_filelist can be an array of filenames or directories, or a single string containing a list of filenames or directories separated by a single space.

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode if the archive is compressed ('tgz') or not ('tar').

PclTarMerge($p_tarname, $p_tarname_add, $p_mode, $p_mode_add) :

The content of archive $p_tarname_add is added at the end of archive $p_tarname. $p_tarname_add is not modified. The type of archives (compressed or not) can be mixed. Each archive will keep its origin mode.

Depending on the archive extension (.tar, .tar.gz ou .tgz) the function will determine the archive type and do the actions in accordance. If the archive has an other extension, you must specify in $p_mode and $p_mode_add if the archive is compressed ('tgz') or not ('tar').

 

 

Archive structure

Only POSIX header are supported.

The official stricture of GNU TAR archive, with all the values of file properties can be found on the GNU web site : GNU TAR Standard Format.

Supported PHP language

PclTar was developped with PHP 3.0.17.


Last Updated on Wednesday, 23 December 2009 19:43