www/plugins-dist/svp/lib/pcltar/readme.txt

   1 // --------------------------------------------------------------------------------
   2 // PclTar 1.3.1 - readme.txt
   3 // --------------------------------------------------------------------------------
   4 // License GNU/GPL - Vincent Blavet - January 2003
   5 // http://www.phpconcept.net
   6 // --------------------------------------------------------------------------------
   7
   8                                                   (Voir version Française à la fin)
   9
  10 0 - Sommaire
  11 ============
  12     1 - Introduction
  13     2 - Install
  14     3 - What's new
  15     4 - Using PclTar
  16     5 - Manual
  17     6 - Language
  18     7 - Known bugs
  19     8 - License
  20     9 - Warning
  21    10 - Author
  22
  23 1 - Introduction
  24 ================
  25
  26   PclTar is a library that allow you to create a GNU TAR archive,
  27   to add files or directories, to extract all the archive or a part of it.
  28   So far tests show that the files generated by PclTar are readable by
  29   gzip tools and WinZip application.
  30
  31   PclTar is made of the following files, placed in the same 'lib' directory :
  32     - pcltar.lib.php3
  33     - pcltrace.lib.php3
  34     - pclerror.lib.php3
  35
  36   Today the libraries PclTrace and PclError are mandatory to run PclTar.
  37
  38   The extension of the files can be modified to .php (or other) without any
  39   internal modification.
  40
  41   The files can be put into any directory as far as the calling script/application
  42   has a valid path to it (see section using PclTar).
  43
  44
  45 2 - Install
  46 ===========
  47
  48   PclTar 1.3 is released in three format :
  49
  50     - Zip traditionnal format (pcltar-1-3.zip),
  51     - Compressed GNU TAR format (pcltar-1-3.tgz),
  52     - PhpZip auto-extract PhpZip (pcltar-1-3.piz).
  53
  54   The Zip and compressed GNU TAR file also include the auto-extract PhpZip file, which
  55   might be usefull for a remote auto-install.
  56
  57   a. Zip archive
  58      Unzip the Zip file in a folder.
  59      The files are in the 'lib' directory, but may be moved in any other directory.
  60
  61   b. Compressed GNU TAR archive
  62      Extract the Compressed GNU TAR file in a folder.
  63      The files are in the 'lib' directory, but may be moved in any other directory.
  64
  65   c. Auto-extract PhpZip archive
  66      Download *** IN BINARY MODE *** the auto-extract PhpZip archive on your web site
  67      in the destination directory 'myfolder'.
  68      Launch the extract by calling http://mydomain.com/myfolder/pcltar-1-3.piz.php3.
  69      The files are automatically placed in the 'lib' directory of the 'myfolder'
  70      directory.
  71
  72 3 - What's new
  73 ==============
  74
  75   In version 1.3.1 :
  76
  77   - Remove deprecated call to functions with references
  78
  79   In version 1.3 :
  80
  81   - Add the function PclTarExtractIndex()
  82   - Correction of a bug with folders. When folder are archived, the size is sometime not
  83     null. PclTar now force the size to be zero when the archived file is a folder. When
  84     un-archiving the size is also forced to 0 when the item is a folder.
  85   - Modify function PclTarDelete() : When you give the name of a directory to be deleted, the
  86     directory entry and the files of the directory are deleted.
  87   - Correct bug in the path add/remove options in functions. When a path is removed,
  88     sometime the 'home' path was not.
  89   - Correct a bug in directory extraction : The directory is created but the status in
  90     the resulting file list is set to write_error.
  91   - Correct a bug : missing update of file cache (clearstatcache())
  92
  93   In version 1.2 :
  94
  95   - Add a new function PclTarMerge(), which allow to merge two archives.
  96   - Add the add_path/remove_path ability to the PclTarCreate() function
  97   - The add list/dir function now support empty directory. Before version 1.2, directories
  98     where not identified as separate entries, there where in the archive, only if there is at
  99     least one file.
 100   - Optimization of PclTarHandleAddList()
 101
 102   In version 1.1 :
 103
 104   - Adding check of header checksum while extracting a file from the archive,
 105   - Enhancement in POSIX header creation. In the first version PclTar use a temporary
 106     file for checksum calculation. It is now directly computed.
 107   - Adding field "status" in file description, remove fields "link", "magic", "version",
 108     "uname", "gname", "devmajor" and "devminor", because they do not carry interesting info.
 109   - While extracting, a check is done if the file exists or not. If an error occurs in the
 110     file extraction, the file is skipped, and the function tries to extract the next one.
 111     In previous release, the extraction was stopped.
 112   - While extracting a file, the mtime is now updated with the value stored in the archive.
 113     Note that the mode (R/W) is not set today (default RW).
 114
 115   - New function PclTarDelete($tarname, $filelist), which deletes the files specified in
 116     $filelist.
 117   - New function PclTarUpdate(), which replace old files with new ones (depending of last
 118     modification date). If the file does not exist, it is added at the end of the archive.
 119   - Values for the file properties array :
 120     filename (with path),
 121     size,
 122     mode (decimal value of the octal value),
 123     uid,
 124     gid,
 125     mtime (last modification date like time() function result),
 126     typeflag ("0" or "" = file, "5" = directory, "1" = link),
 127     status (ok, added, updated, not_updated, already_a_directory,
 128             write_protected, newer_exist, path_creation_fail, write_error)
 129   - Add a "remove path" property in the extract functions. This allow to extract file
 130     in an other directory than the expected directory.
 131   - Add new function PclTarAddList()
 132   - Add parameter $p_mode in PclTarList()
 133
 134 4 - Using PclTar
 135 ========================
 136
 137   In order to use PclTar 1.3, an application (or a script) must include
 138   the PclTar file pcltar.lib.php3.
 139   Because PclTar 1.3 include two other libraries (PclTrace and PclError), a
 140   way to include these libraries must be done. Several solutions are available :
 141
 142   - Include each library in the application/script (in this order) :
 143     <?
 144     include ("my_lib_dir/pclerror.lib.php3");
 145     include ("my_lib_dir/pcltrace.lib.php3");
 146     include ("my_lib_dir/pcltar.lib.php3");
 147     [...]
 148     ?>
 149
 150   - Give the library path knownledge to PclTar :
 151     <?
 152     $g_pcltar_lib_dir = "my_lib_dir";
 153     include ("my_lib_dir/pcltar.lib.php3");
 154     [...]
 155     ?>
 156
 157   - Modify the $g_pcltar_lib_dir value in pcltar.lib.php3
 158
 159   - Use the global include directory configured in php.ini, and modify the
 160     $g_pcltar_lib_dir value in pcltar.lib.php3 and set it to ''
 161
 162   Note that PclTar file (pcltar.lib.php3) may be included several time without any
 163   problem. However this is not recomended for performance reason.
 164
 165   After the include(s), the functions defined by PclTar can be directly used
 166   (see manual section).
 167
 168
 169 5 - Manual
 170 ==========
 171
 172   PclTar introduce functions to create, add, list, delete and extract files in a GNU
 173   TAR archive. The GNU TAR archive can be compressed or not.
 174
 175   A more complete documentation of the PclTar function is available at
 176   http://www.phpconcept.net
 177
 178   Each public function is documented in an appropriate header directly in the source
 179   code.
 180
 181
 182
 183 6 - Langage
 184 ===========
 185
 186   PclTar was developped in PHP3 but is compatible with PHP4. The files
 187   extension can be modified without any action needed inside the files.
 188
 189   PclTar code is fully documented (nearly step by step) in english.
 190
 191
 192 7 - Known bugs
 193 ==============
 194
 195   Here is a list of known bugs in PclTar 1.0 (not exhaustive list) :
 196
 197   - Only GNU TAR archive with POSIX header are supported
 198   - While extracting a file, the header checksum is not checked.
 199   - While extracting a file, the last modified date is not checked with the one
 200     of the file that will be replaced.
 201   - While extracting a file, the file mode (access right by user, ...) is not
 202     reproduced.
 203   - While archiving a full directory, the directory it self is not archived.
 204   - While extracting a directory name the directory is created only if there is
 205     a file inside. Should be created even if no file is inside.
 206
 207   Known bugs will be updated in http://www.phpconcept.net
 208
 209
 210 8 - License
 211 ===========
 212
 213   PclTar 1.3 Library is released under GNU/GPL license.
 214   This library is free, so you can use it at no cost.
 215
 216   HOWEVER, if you release a script, an application, a library or any kind of
 217   code including PclTar library (or a part of it), YOU MUST :
 218   - Release your work under GNU/GPL license (free software),
 219   - You must indicate in the documentation (or a readme file), that your work
 220     include PclTar Library, and make a reference to the author and the web site
 221     http://www.phpconcept.net
 222
 223   I will also appreciate that you send me a mail (vincent@blavet.net), just to
 224   be aware that someone is using PclTar (but this is not mandatory ;-) ).
 225
 226   For more information : http://www.gnu.org
 227
 228 9 - Warning
 229 =================
 230
 231   This library and the associated files are non commercial, non professional work.
 232   It should not have unexpected results. However if any damage is caused by this software
 233   the author can not be responsible.
 234   The use of this software is at the risk of the user.
 235
 236 10 - Author
 237 ==========
 238
 239   This software was written by Vincent Blavet (vincent@blavet.net) on its leasure time.
 240
 241
 242
 243 ********************************************************************************
 244 *                            VERSION FRANCAISE                                 *
 245 ********************************************************************************
 246
 247
 248 0 - Sommaire
 249 ============
 250     1 - Introduction
 251     2 - Installation
 252     3 - Nouveautés
 253     4 - Démarrer avec PclTar
 254     5 - Manuel
 255     6 - Langage
 256     7 - Problèmes connus
 257     8 - License
 258     9 - Avertissement
 259    10 - Auteur
 260
 261
 262 1 - Introduction
 263 ================
 264
 265   PclTar est une librairie qui vous permet de créer des archives au format GNU TAR ou GNU
 266   TAR compressé, d'ajouter des fichiers ou des dossiers entiers et d'extraire le contenu
 267   total ou partiel des archives.
 268   A présent les tests ont montré que les archives créées par PclTar sont lisibles par les
 269   outils tar et gzip, ainsi que l'application WinZip.
 270
 271   PclTar est constituée des fichiers suivants, ils sont placés dans le dossier 'lib' :
 272     - pcltar.lib.php3
 273     - pcltrace.lib.php3
 274     - pclerror.lib.php3
 275
 276   Aujourd'hui les librairies PclTrace et PclError sont obligatoires pour faire fonctionner
 277   PclTar.
 278
 279   Les extensions de fichiers (.php3) peuvent être modifiés (en .php par exemple) sans
 280   nécessité d'intervenir à l'intérieur du fichier.
 281
 282   Les fichiers peuvent être placés dans n'importe quel dossier pour peu que l'application
 283   ou le script appelant utilise un chemin d'appel valide.
 284
 285
 286 2 - Installation
 287 ================
 288
 289   PclTar 1.3 est distribué sous trois formats :
 290
 291     - Format Zip traditionnel (pcltar-1-3.zip),
 292     - Format GNU TAR compressé (pcltar-1-3.tgz),
 293     - Format PhpZip auto-extract (pcltar-1-3.piz).
 294
 295   Les fichiers Zip and GNU TAR compressés contiennent aussi le format PhpZip
 296   auto-extract.
 297
 298   a. Archive Zip
 299      Décompressez l'archive Zip dans un dossier.
 300      Les fichiers sont dans le dossier 'lib' et peuvent être déplacés ailleurs.
 301
 302   b. Archive GNU TAR compressée
 303      Décompressez l'archive GNU TAR dans un dossier.
 304      Les fichiers sont dans le dossier 'lib' et peuvent être déplacés ailleurs.
 305
 306   c. Auto-extract PhpZip archive
 307      Téléchargez *** EN MODE BINAIRE *** l'archive PhpZip sur votre site Web dans
 308      le dossier souhaité 'mondossier'.
 309      Lancer l'extraction en appelant http://mondomaine.com/mondossier/pcltar-1-3.piz.php3
 310      Les fichiers sont dans le dossier 'lib' du dossier 'mondossier'.
 311
 312
 313 3 - Nouveautés
 314 ==============
 315
 316   En version 1.3.1 :
 317
 318   - Suppression des appels de fonctions par références
 319
 320   En version 1.3 :
 321
 322   - Ajout de la fonction PclTarExtractIndex()
 323   - Correction d'un bug avec l'archivage des dossiers. Parfois la taille des
 324     dossiers archivés était non nul ce qui entrainait une erreur lors de l'extraction.
 325     PclTar force désormais la taille à zéro lorsqu'il s'agit d'un dossier. De même lors
 326     de l'extraction il ignore la taille éventuellement incorrecte.
 327   - Modification de la fonction PclTarDelete() : Lorsque l'on donne le nom d'un dossier
 328     à supprimer, le dossier et les fichiers se trouvant dedans sont supprimés.
 329     Avant la version 1.3 seulement l'entrée concernant le dossier était supprimée.
 330   - Correction d'un bug dans les propriétés d'ajout/suppression de chemin. Lorsque l'on
 331     indiquait un chemin à supprimer, cela se passait bien pour les fichiers et
 332     sous-dossiers, mais le dossier en lui-même n'était pas ignoré.
 333   - Correction d'un bug dans l'extraction d'un dossier : Le dossier est normalement créé,
 334     mais le status de l'opération pour ce dossier était en 'write_erreor'.
 335   - Correction d'un bug sur la validité des dates de dernière modification des
 336     fichiers. Utilisation  plus systèmatique de clearstatcache().
 337
 338   En version 1.2 :
 339
 340   - Ajout d'une nouvelle fonction PclTarMerge(), qui permet d'ajouter à une archive le
 341     contenu d'une autre.
 342   - Ajout des propriétés "ajout de path/suppression de path" pour la fonction PclTarCreate().
 343   - Les archives générées par PclTar supportent maintenant les dossiers vide. Avant la
 344     version 1.2, un dossier n'était ajouté que lorsqu'il y avait au moins un fichier dedans.
 345   - Optimisation du code de PclTarHandleAddList()
 346
 347   En version 1.1 :
 348
 349   - Ajout de la vérification du checksum lors de l'extraction d'un fichier.
 350   - Amélioration de la création des entêtes POSIX. En version 1.0 PclTar utilisait un fichier
 351     temporaire pour calculer le checksum. Ce n'est plus le cas à partir de la version 1.2.
 352   - Ajout d'un champ "status" dans le tableau de description des propriétés d'un fichier.
 353     Les champs "link", "magic", "version", "uname", "gname", "devmajor" and "devminor" sont
 354     eux supprimés car ils ne contiennent aucune information interessante.
 355   - Lors de l'extraction une vérification est faite pour savoir si le fichier existe déjà ou non.
 356     Si une erreur arrive lors de l'extraction le fichier est sauté et la fonction cherche à
 357     extraire le fichier suivant. Dans la version précédente l'extraction était arrêtée.
 358   - Lors de l'extraction d'un fichier la date de dernière modification est mise à jour avec
 359     celle mémorisée dans l'archive.
 360     Notez que ce n'est pas le cas pour le mode (R/W) qui reste celui par défaut.
 361   - Nouvelle fonction PclTarDelete($tarname, $filelist), qui supprime de l'archive les fichiers
 362     spécifiés dans $filelist.
 363   - Nouvelle fonction PclTarUpdate(), qui remplace les anciens fichiers par les nouveaux
 364     (en fonction de la date de dernière modification). Si le fichier n'existe pas il est
 365     ajouté en fin d'archive.
 366   - Le tableau contenant les propriétés d'un fichier a les champs suivants :
 367     filename (with path),
 368     size,
 369     mode (decimal value of the octal value),
 370     uid,
 371     gid,
 372     mtime (last modification date like time() function result),
 373     typeflag ("0" or "" = file, "5" = directory, "1" = link),
 374     status (ok, added, updated, not_updated, already_a_directory,
 375             write_protected, newer_exist, path_creation_fail, write_error)
 376   - Ajout d'une propriété "chemin à retirer" dans les fonctions d'extraction. Cela permet
 377     d'extraire un fichier ou un dossier dans un dossier différent de celui qui a été mémorizé.
 378   - Ajout de la focntion PclTarAddList()
 379   - Ajout du parametre $p_mode dans PclTarList()
 380
 381 3 - Démarrer avec PclTar
 382 ========================
 383
 384   Pour utiliser PclTar, une application ou un script doivent inclure le fichier
 385   pcltar.lib.php3.
 386   PclTar utilisant deux librairies annexes (PclTrace et PclError), une configuration
 387   est nécessaire pour que PclTar retrouve le chemin d'inclusion des deux librairies.
 388   Plusieurs solutions, au choix, sont possibles :
 389
 390   - Inclure chaque librarie dans l'application/script :
 391     <?
 392     include ("my_lib_dir/pclerror.lib.php3");
 393     include ("my_lib_dir/pcltrace.lib.php3");
 394     include ("my_lib_dir/pcltar.lib.php3");
 395     [...]
 396     ?>
 397
 398   - Donner à PclTar la connaissance du chemin d'inclusion :
 399     <?
 400     $g_pcltar_lib_dir = "my_lib_dir";
 401     include ("my_lib_dir/pcltar.lib.php3");
 402     [...]
 403     ?>
 404
 405   - Modifier la variable $g_pcltar_lib_dir dans pcltar.lib.php3
 406
 407   - Utiliser le chemin d'include par défaut (configuré dans php.ini), sans oublier de
 408     modifier la variable $g_pcltar_lib_dir pour la mettre à ''.
 409
 410   Il est à noter que le fichier pcltar.lib.php3 peut être inclu plusieurs fois sans
 411   impact autre qu'une légère perte de performance.
 412
 413
 414 4 - Manuel
 415 ==========
 416
 417   PclTar définit des fonctions pour créer, ajouter, lister, détruire et extraire des
 418   fichiers depuis une archive GNU TAR. Cette archive peut être compressée ou non.
 419
 420   Une description plus complète de PclTar est disponible sur
 421   http://www.phpconcept.net
 422
 423   Chaque fonction est aussi documentée dans un entête associé, directement dans
 424   le code source.
 425
 426
 427 5 - Langage
 428 ===========
 429
 430   PclTar a été développé en PHP3 mais est compatible avec PHP4. Les
 431   extensions de fichiers (.php3) peuvent être modifié sans toucher à l'intérieur
 432   des fichiers.
 433
 434   Le code de PclTar est entièrement documenté en anglais.
 435
 436
 437 6 - Problèmes connus
 438 ====================
 439
 440   Liste des problèmes connus dans PclTar 1.0 (liste non exhaustive) :
 441
 442   - Seuls les archives GNU TAR au format "header POSIX" sont supportées
 443   - Lors de l'extraction d'un fichier le checksupm de l'entête n'est pas vérifié
 444   - Lors de l'extraction d'un fichier la date de dernière modification d'un
 445     fichier n'est pas comparé avec celle du fichier existant.
 446   - Lors de l'extraction d'un fichier les droits d'accès d'un fichier ne sont pas
 447     reconduits
 448   - Lors de l'archivage d'un dossier entier, le nom du dossier lui même n'est pas
 449     archivé comme une entrée indépendante
 450   - Lors de l'extraction de l'entrée décrivant un dossier, le dossier n'est créé que si
 451     au moins un fichier est archivé pour ce dossier.
 452
 453   Les bugs connus et les contournements possibles ou les versions de correction
 454   seront mis à jour sur le site http://www.phpconcept.net
 455
 456   Merci d'y documenter les bugs que vous rencontrez afin qu'ils soient pris en compte
 457   dans les versions futures !
 458
 459 7 - License
 460 ===========
 461
 462   La librairie PclTar 1.3 est distribuées sous license GNU/GPL.
 463   Vous pouvez donc l'utiliser gratuitement.
 464
 465   CEPENDANT, si vous publiez un script, une application, une librairie ou tout
 466   code incluant PclTar (entier ou partiel), VOUS DEVEZ :
 467   - Publier votre travail sous license GNU/GPL (c'est à dire gratuitement),
 468   - Indiquer quelque part dans la documentation (le fichier readme par exemple) que
 469     vous utilisez PclTar, faire référence à l'auteur et au site Web
 470     http://www.phpconcept.net
 471
 472   J'apprécierai aussi que vous m'envoyez un mail (vincent@blavet.net) afin que
 473   je sache que PclTar est utilisé quelque part (mais ce n'est pas obligatoire ;-) ).
 474
 475   Pour plus d'information voir http://www.gnu.org
 476
 477
 478 8 - Avertissement
 479 =================
 480
 481    Cette application a été créée de façon non professionnelle.
 482    Son usage est au risque et péril de celui qui l'utilise, en aucun cas l'auteur
 483    de ce code ne pourra être tenu pour responsable des éventuels dégats qu'il pourrait
 484    engendrer.
 485    Il est entendu cependant que l'auteur a réalisé ce code par plaisir et n'y a
 486    caché aucun virus ni malveillance.
 487
 488
 489 9 - Auteur
 490 ==========
 491
 492 Ce code a été écrit par Vincent Blavet (vincent@blavet.net) sur ses temps de loisir.
 493