mirror of
https://github.com/YunoHost-Apps/spip_ynh.git
synced 2024-09-03 20:25:59 +02:00
493 lines
19 KiB
Text
493 lines
19 KiB
Text
// --------------------------------------------------------------------------------
|
|
// PclTar 1.3.1 - readme.txt
|
|
// --------------------------------------------------------------------------------
|
|
// License GNU/GPL - Vincent Blavet - January 2003
|
|
// http://www.phpconcept.net
|
|
// --------------------------------------------------------------------------------
|
|
|
|
(Voir version Française à la fin)
|
|
|
|
0 - Sommaire
|
|
============
|
|
1 - Introduction
|
|
2 - Install
|
|
3 - What's new
|
|
4 - Using PclTar
|
|
5 - Manual
|
|
6 - Language
|
|
7 - Known bugs
|
|
8 - License
|
|
9 - Warning
|
|
10 - Author
|
|
|
|
1 - Introduction
|
|
================
|
|
|
|
PclTar is a library that allow you to create a GNU TAR archive,
|
|
to add files or directories, to extract all the archive or a part of it.
|
|
So far tests show that the files generated by PclTar are readable by
|
|
gzip tools and WinZip application.
|
|
|
|
PclTar is made of the following files, placed in the same 'lib' directory :
|
|
- pcltar.lib.php3
|
|
- pcltrace.lib.php3
|
|
- pclerror.lib.php3
|
|
|
|
Today the libraries PclTrace and PclError are mandatory to run PclTar.
|
|
|
|
The extension of the files can be modified to .php (or other) without any
|
|
internal modification.
|
|
|
|
The files can be put into any directory as far as the calling script/application
|
|
has a valid path to it (see section using PclTar).
|
|
|
|
|
|
2 - Install
|
|
===========
|
|
|
|
PclTar 1.3 is released in three format :
|
|
|
|
- Zip traditionnal format (pcltar-1-3.zip),
|
|
- Compressed GNU TAR format (pcltar-1-3.tgz),
|
|
- PhpZip auto-extract PhpZip (pcltar-1-3.piz).
|
|
|
|
The Zip and compressed GNU TAR file also include the auto-extract PhpZip file, which
|
|
might be usefull for a remote auto-install.
|
|
|
|
a. Zip archive
|
|
Unzip the Zip file in a folder.
|
|
The files are in the 'lib' directory, but may be moved in any other directory.
|
|
|
|
b. Compressed GNU TAR archive
|
|
Extract the Compressed GNU TAR file in a folder.
|
|
The files are in the 'lib' directory, but may be moved in any other directory.
|
|
|
|
c. Auto-extract PhpZip archive
|
|
Download *** IN BINARY MODE *** the auto-extract PhpZip archive on your web site
|
|
in the destination directory 'myfolder'.
|
|
Launch the extract by calling http://mydomain.com/myfolder/pcltar-1-3.piz.php3.
|
|
The files are automatically placed in the 'lib' directory of the 'myfolder'
|
|
directory.
|
|
|
|
3 - What's new
|
|
==============
|
|
|
|
In version 1.3.1 :
|
|
|
|
- Remove deprecated call to functions with references
|
|
|
|
In version 1.3 :
|
|
|
|
- Add the function PclTarExtractIndex()
|
|
- Correction of a bug with folders. When folder are archived, the size is sometime not
|
|
null. PclTar now force the size to be zero when the archived file is a folder. When
|
|
un-archiving the size is also forced to 0 when the item is a folder.
|
|
- Modify function PclTarDelete() : When you give the name of a directory to be deleted, the
|
|
directory entry and the files of the directory are deleted.
|
|
- Correct bug in the path add/remove options in functions. When a path is removed,
|
|
sometime the 'home' path was not.
|
|
- Correct a bug in directory extraction : The directory is created but the status in
|
|
the resulting file list is set to write_error.
|
|
- Correct a bug : missing update of file cache (clearstatcache())
|
|
|
|
In version 1.2 :
|
|
|
|
- Add a new function PclTarMerge(), which allow to merge two archives.
|
|
- Add the add_path/remove_path ability to the PclTarCreate() function
|
|
- The add list/dir function now support empty directory. Before version 1.2, directories
|
|
where not identified as separate entries, there where in the archive, only if there is at
|
|
least one file.
|
|
- Optimization of PclTarHandleAddList()
|
|
|
|
In version 1.1 :
|
|
|
|
- Adding check of header checksum while extracting a file from the archive,
|
|
- Enhancement in POSIX header creation. In the first version PclTar use a temporary
|
|
file for checksum calculation. It is now directly computed.
|
|
- Adding field "status" in file description, remove fields "link", "magic", "version",
|
|
"uname", "gname", "devmajor" and "devminor", because they do not carry interesting info.
|
|
- While extracting, a check is done if the file exists or not. If an error occurs in the
|
|
file extraction, the file is skipped, and the function tries to extract the next one.
|
|
In previous release, the extraction was stopped.
|
|
- While extracting a file, the mtime is now updated with the value stored in the archive.
|
|
Note that the mode (R/W) is not set today (default RW).
|
|
|
|
- New function PclTarDelete($tarname, $filelist), which deletes the files specified in
|
|
$filelist.
|
|
- New function PclTarUpdate(), which replace old files with new ones (depending of last
|
|
modification date). If the file does not exist, it is added at the end of the archive.
|
|
- Values for the file properties array :
|
|
filename (with path),
|
|
size,
|
|
mode (decimal value of the octal value),
|
|
uid,
|
|
gid,
|
|
mtime (last modification date like time() function result),
|
|
typeflag ("0" or "" = file, "5" = directory, "1" = link),
|
|
status (ok, added, updated, not_updated, already_a_directory,
|
|
write_protected, newer_exist, path_creation_fail, write_error)
|
|
- Add a "remove path" property in the extract functions. This allow to extract file
|
|
in an other directory than the expected directory.
|
|
- Add new function PclTarAddList()
|
|
- Add parameter $p_mode in PclTarList()
|
|
|
|
4 - Using PclTar
|
|
========================
|
|
|
|
In order to use PclTar 1.3, an application (or a script) must include
|
|
the PclTar file pcltar.lib.php3.
|
|
Because PclTar 1.3 include two other libraries (PclTrace and PclError), a
|
|
way to include these libraries must be done. Several solutions are available :
|
|
|
|
- Include each library in the application/script (in this order) :
|
|
<?
|
|
include ("my_lib_dir/pclerror.lib.php3");
|
|
include ("my_lib_dir/pcltrace.lib.php3");
|
|
include ("my_lib_dir/pcltar.lib.php3");
|
|
[...]
|
|
?>
|
|
|
|
- Give the library path knownledge to PclTar :
|
|
<?
|
|
$g_pcltar_lib_dir = "my_lib_dir";
|
|
include ("my_lib_dir/pcltar.lib.php3");
|
|
[...]
|
|
?>
|
|
|
|
- Modify the $g_pcltar_lib_dir value in pcltar.lib.php3
|
|
|
|
- Use the global include directory configured in php.ini, and modify the
|
|
$g_pcltar_lib_dir value in pcltar.lib.php3 and set it to ''
|
|
|
|
Note that PclTar file (pcltar.lib.php3) may be included several time without any
|
|
problem. However this is not recomended for performance reason.
|
|
|
|
After the include(s), the functions defined by PclTar can be directly used
|
|
(see manual section).
|
|
|
|
|
|
5 - Manual
|
|
==========
|
|
|
|
PclTar introduce functions to create, add, list, delete and extract files in a GNU
|
|
TAR archive. The GNU TAR archive can be compressed or not.
|
|
|
|
A more complete documentation of the PclTar function is available at
|
|
http://www.phpconcept.net
|
|
|
|
Each public function is documented in an appropriate header directly in the source
|
|
code.
|
|
|
|
|
|
|
|
6 - Langage
|
|
===========
|
|
|
|
PclTar was developped in PHP3 but is compatible with PHP4. The files
|
|
extension can be modified without any action needed inside the files.
|
|
|
|
PclTar code is fully documented (nearly step by step) in english.
|
|
|
|
|
|
7 - Known bugs
|
|
==============
|
|
|
|
Here is a list of known bugs in PclTar 1.0 (not exhaustive list) :
|
|
|
|
- Only GNU TAR archive with POSIX header are supported
|
|
- While extracting a file, the header checksum is not checked.
|
|
- While extracting a file, the last modified date is not checked with the one
|
|
of the file that will be replaced.
|
|
- While extracting a file, the file mode (access right by user, ...) is not
|
|
reproduced.
|
|
- While archiving a full directory, the directory it self is not archived.
|
|
- While extracting a directory name the directory is created only if there is
|
|
a file inside. Should be created even if no file is inside.
|
|
|
|
Known bugs will be updated in http://www.phpconcept.net
|
|
|
|
|
|
8 - License
|
|
===========
|
|
|
|
PclTar 1.3 Library is released under GNU/GPL license.
|
|
This library is free, so you can use it at no cost.
|
|
|
|
HOWEVER, if you release a script, an application, a library or any kind of
|
|
code including PclTar library (or a part of it), YOU MUST :
|
|
- Release your work under GNU/GPL license (free software),
|
|
- You must indicate in the documentation (or a readme file), that your work
|
|
include PclTar Library, and make a reference to the author and the web site
|
|
http://www.phpconcept.net
|
|
|
|
I will also appreciate that you send me a mail (vincent@blavet.net), just to
|
|
be aware that someone is using PclTar (but this is not mandatory ;-) ).
|
|
|
|
For more information : http://www.gnu.org
|
|
|
|
9 - Warning
|
|
=================
|
|
|
|
This library and the associated files are non commercial, non professional work.
|
|
It should not have unexpected results. However if any damage is caused by this software
|
|
the author can not be responsible.
|
|
The use of this software is at the risk of the user.
|
|
|
|
10 - Author
|
|
==========
|
|
|
|
This software was written by Vincent Blavet (vincent@blavet.net) on its leasure time.
|
|
|
|
|
|
|
|
********************************************************************************
|
|
* VERSION FRANCAISE *
|
|
********************************************************************************
|
|
|
|
|
|
0 - Sommaire
|
|
============
|
|
1 - Introduction
|
|
2 - Installation
|
|
3 - Nouveautés
|
|
4 - Démarrer avec PclTar
|
|
5 - Manuel
|
|
6 - Langage
|
|
7 - Problèmes connus
|
|
8 - License
|
|
9 - Avertissement
|
|
10 - Auteur
|
|
|
|
|
|
1 - Introduction
|
|
================
|
|
|
|
PclTar est une librairie qui vous permet de créer des archives au format GNU TAR ou GNU
|
|
TAR compressé, d'ajouter des fichiers ou des dossiers entiers et d'extraire le contenu
|
|
total ou partiel des archives.
|
|
A présent les tests ont montré que les archives créées par PclTar sont lisibles par les
|
|
outils tar et gzip, ainsi que l'application WinZip.
|
|
|
|
PclTar est constituée des fichiers suivants, ils sont placés dans le dossier 'lib' :
|
|
- pcltar.lib.php3
|
|
- pcltrace.lib.php3
|
|
- pclerror.lib.php3
|
|
|
|
Aujourd'hui les librairies PclTrace et PclError sont obligatoires pour faire fonctionner
|
|
PclTar.
|
|
|
|
Les extensions de fichiers (.php3) peuvent être modifiés (en .php par exemple) sans
|
|
nécessité d'intervenir à l'intérieur du fichier.
|
|
|
|
Les fichiers peuvent être placés dans n'importe quel dossier pour peu que l'application
|
|
ou le script appelant utilise un chemin d'appel valide.
|
|
|
|
|
|
2 - Installation
|
|
================
|
|
|
|
PclTar 1.3 est distribué sous trois formats :
|
|
|
|
- Format Zip traditionnel (pcltar-1-3.zip),
|
|
- Format GNU TAR compressé (pcltar-1-3.tgz),
|
|
- Format PhpZip auto-extract (pcltar-1-3.piz).
|
|
|
|
Les fichiers Zip and GNU TAR compressés contiennent aussi le format PhpZip
|
|
auto-extract.
|
|
|
|
a. Archive Zip
|
|
Décompressez l'archive Zip dans un dossier.
|
|
Les fichiers sont dans le dossier 'lib' et peuvent être déplacés ailleurs.
|
|
|
|
b. Archive GNU TAR compressée
|
|
Décompressez l'archive GNU TAR dans un dossier.
|
|
Les fichiers sont dans le dossier 'lib' et peuvent être déplacés ailleurs.
|
|
|
|
c. Auto-extract PhpZip archive
|
|
Téléchargez *** EN MODE BINAIRE *** l'archive PhpZip sur votre site Web dans
|
|
le dossier souhaité 'mondossier'.
|
|
Lancer l'extraction en appelant http://mondomaine.com/mondossier/pcltar-1-3.piz.php3
|
|
Les fichiers sont dans le dossier 'lib' du dossier 'mondossier'.
|
|
|
|
|
|
3 - Nouveautés
|
|
==============
|
|
|
|
En version 1.3.1 :
|
|
|
|
- Suppression des appels de fonctions par références
|
|
|
|
En version 1.3 :
|
|
|
|
- Ajout de la fonction PclTarExtractIndex()
|
|
- Correction d'un bug avec l'archivage des dossiers. Parfois la taille des
|
|
dossiers archivés était non nul ce qui entrainait une erreur lors de l'extraction.
|
|
PclTar force désormais la taille à zéro lorsqu'il s'agit d'un dossier. De même lors
|
|
de l'extraction il ignore la taille éventuellement incorrecte.
|
|
- Modification de la fonction PclTarDelete() : Lorsque l'on donne le nom d'un dossier
|
|
à supprimer, le dossier et les fichiers se trouvant dedans sont supprimés.
|
|
Avant la version 1.3 seulement l'entrée concernant le dossier était supprimée.
|
|
- Correction d'un bug dans les propriétés d'ajout/suppression de chemin. Lorsque l'on
|
|
indiquait un chemin à supprimer, cela se passait bien pour les fichiers et
|
|
sous-dossiers, mais le dossier en lui-même n'était pas ignoré.
|
|
- Correction d'un bug dans l'extraction d'un dossier : Le dossier est normalement créé,
|
|
mais le status de l'opération pour ce dossier était en 'write_erreor'.
|
|
- Correction d'un bug sur la validité des dates de dernière modification des
|
|
fichiers. Utilisation plus systèmatique de clearstatcache().
|
|
|
|
En version 1.2 :
|
|
|
|
- Ajout d'une nouvelle fonction PclTarMerge(), qui permet d'ajouter à une archive le
|
|
contenu d'une autre.
|
|
- Ajout des propriétés "ajout de path/suppression de path" pour la fonction PclTarCreate().
|
|
- Les archives générées par PclTar supportent maintenant les dossiers vide. Avant la
|
|
version 1.2, un dossier n'était ajouté que lorsqu'il y avait au moins un fichier dedans.
|
|
- Optimisation du code de PclTarHandleAddList()
|
|
|
|
En version 1.1 :
|
|
|
|
- Ajout de la vérification du checksum lors de l'extraction d'un fichier.
|
|
- Amélioration de la création des entêtes POSIX. En version 1.0 PclTar utilisait un fichier
|
|
temporaire pour calculer le checksum. Ce n'est plus le cas à partir de la version 1.2.
|
|
- Ajout d'un champ "status" dans le tableau de description des propriétés d'un fichier.
|
|
Les champs "link", "magic", "version", "uname", "gname", "devmajor" and "devminor" sont
|
|
eux supprimés car ils ne contiennent aucune information interessante.
|
|
- Lors de l'extraction une vérification est faite pour savoir si le fichier existe déjà ou non.
|
|
Si une erreur arrive lors de l'extraction le fichier est sauté et la fonction cherche à
|
|
extraire le fichier suivant. Dans la version précédente l'extraction était arrêtée.
|
|
- Lors de l'extraction d'un fichier la date de dernière modification est mise à jour avec
|
|
celle mémorisée dans l'archive.
|
|
Notez que ce n'est pas le cas pour le mode (R/W) qui reste celui par défaut.
|
|
- Nouvelle fonction PclTarDelete($tarname, $filelist), qui supprime de l'archive les fichiers
|
|
spécifiés dans $filelist.
|
|
- Nouvelle fonction PclTarUpdate(), qui remplace les anciens fichiers par les nouveaux
|
|
(en fonction de la date de dernière modification). Si le fichier n'existe pas il est
|
|
ajouté en fin d'archive.
|
|
- Le tableau contenant les propriétés d'un fichier a les champs suivants :
|
|
filename (with path),
|
|
size,
|
|
mode (decimal value of the octal value),
|
|
uid,
|
|
gid,
|
|
mtime (last modification date like time() function result),
|
|
typeflag ("0" or "" = file, "5" = directory, "1" = link),
|
|
status (ok, added, updated, not_updated, already_a_directory,
|
|
write_protected, newer_exist, path_creation_fail, write_error)
|
|
- Ajout d'une propriété "chemin à retirer" dans les fonctions d'extraction. Cela permet
|
|
d'extraire un fichier ou un dossier dans un dossier différent de celui qui a été mémorizé.
|
|
- Ajout de la focntion PclTarAddList()
|
|
- Ajout du parametre $p_mode dans PclTarList()
|
|
|
|
3 - Démarrer avec PclTar
|
|
========================
|
|
|
|
Pour utiliser PclTar, une application ou un script doivent inclure le fichier
|
|
pcltar.lib.php3.
|
|
PclTar utilisant deux librairies annexes (PclTrace et PclError), une configuration
|
|
est nécessaire pour que PclTar retrouve le chemin d'inclusion des deux librairies.
|
|
Plusieurs solutions, au choix, sont possibles :
|
|
|
|
- Inclure chaque librarie dans l'application/script :
|
|
<?
|
|
include ("my_lib_dir/pclerror.lib.php3");
|
|
include ("my_lib_dir/pcltrace.lib.php3");
|
|
include ("my_lib_dir/pcltar.lib.php3");
|
|
[...]
|
|
?>
|
|
|
|
- Donner à PclTar la connaissance du chemin d'inclusion :
|
|
<?
|
|
$g_pcltar_lib_dir = "my_lib_dir";
|
|
include ("my_lib_dir/pcltar.lib.php3");
|
|
[...]
|
|
?>
|
|
|
|
- Modifier la variable $g_pcltar_lib_dir dans pcltar.lib.php3
|
|
|
|
- Utiliser le chemin d'include par défaut (configuré dans php.ini), sans oublier de
|
|
modifier la variable $g_pcltar_lib_dir pour la mettre à ''.
|
|
|
|
Il est à noter que le fichier pcltar.lib.php3 peut être inclu plusieurs fois sans
|
|
impact autre qu'une légère perte de performance.
|
|
|
|
|
|
4 - Manuel
|
|
==========
|
|
|
|
PclTar définit des fonctions pour créer, ajouter, lister, détruire et extraire des
|
|
fichiers depuis une archive GNU TAR. Cette archive peut être compressée ou non.
|
|
|
|
Une description plus complète de PclTar est disponible sur
|
|
http://www.phpconcept.net
|
|
|
|
Chaque fonction est aussi documentée dans un entête associé, directement dans
|
|
le code source.
|
|
|
|
|
|
5 - Langage
|
|
===========
|
|
|
|
PclTar a été développé en PHP3 mais est compatible avec PHP4. Les
|
|
extensions de fichiers (.php3) peuvent être modifié sans toucher à l'intérieur
|
|
des fichiers.
|
|
|
|
Le code de PclTar est entièrement documenté en anglais.
|
|
|
|
|
|
6 - Problèmes connus
|
|
====================
|
|
|
|
Liste des problèmes connus dans PclTar 1.0 (liste non exhaustive) :
|
|
|
|
- Seuls les archives GNU TAR au format "header POSIX" sont supportées
|
|
- Lors de l'extraction d'un fichier le checksupm de l'entête n'est pas vérifié
|
|
- Lors de l'extraction d'un fichier la date de dernière modification d'un
|
|
fichier n'est pas comparé avec celle du fichier existant.
|
|
- Lors de l'extraction d'un fichier les droits d'accès d'un fichier ne sont pas
|
|
reconduits
|
|
- Lors de l'archivage d'un dossier entier, le nom du dossier lui même n'est pas
|
|
archivé comme une entrée indépendante
|
|
- Lors de l'extraction de l'entrée décrivant un dossier, le dossier n'est créé que si
|
|
au moins un fichier est archivé pour ce dossier.
|
|
|
|
Les bugs connus et les contournements possibles ou les versions de correction
|
|
seront mis à jour sur le site http://www.phpconcept.net
|
|
|
|
Merci d'y documenter les bugs que vous rencontrez afin qu'ils soient pris en compte
|
|
dans les versions futures !
|
|
|
|
7 - License
|
|
===========
|
|
|
|
La librairie PclTar 1.3 est distribuées sous license GNU/GPL.
|
|
Vous pouvez donc l'utiliser gratuitement.
|
|
|
|
CEPENDANT, si vous publiez un script, une application, une librairie ou tout
|
|
code incluant PclTar (entier ou partiel), VOUS DEVEZ :
|
|
- Publier votre travail sous license GNU/GPL (c'est à dire gratuitement),
|
|
- Indiquer quelque part dans la documentation (le fichier readme par exemple) que
|
|
vous utilisez PclTar, faire référence à l'auteur et au site Web
|
|
http://www.phpconcept.net
|
|
|
|
J'apprécierai aussi que vous m'envoyez un mail (vincent@blavet.net) afin que
|
|
je sache que PclTar est utilisé quelque part (mais ce n'est pas obligatoire ;-) ).
|
|
|
|
Pour plus d'information voir http://www.gnu.org
|
|
|
|
|
|
8 - Avertissement
|
|
=================
|
|
|
|
Cette application a été créée de façon non professionnelle.
|
|
Son usage est au risque et péril de celui qui l'utilise, en aucun cas l'auteur
|
|
de ce code ne pourra être tenu pour responsable des éventuels dégats qu'il pourrait
|
|
engendrer.
|
|
Il est entendu cependant que l'auteur a réalisé ce code par plaisir et n'y a
|
|
caché aucun virus ni malveillance.
|
|
|
|
|
|
9 - Auteur
|
|
==========
|
|
|
|
Ce code a été écrit par Vincent Blavet (vincent@blavet.net) sur ses temps de loisir.
|
|
|