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