1[vset PACKAGE_VERSION 0.11] 2[comment {-*- tcl -*- doctools manpage}] 3[manpage_begin tar n [vset PACKAGE_VERSION]] 4[keywords archive] 5[keywords {tape archive}] 6[keywords tar] 7[moddesc {Tar file handling}] 8[titledesc {Tar file creation, extraction & manipulation}] 9[category {File formats}] 10[require Tcl 8.4] 11[require tar [opt [vset PACKAGE_VERSION]]] 12[description] 13 14[para] Note: Starting with version 0.8 the tar reader commands 15(contents, stats, get, untar) support the GNU LongName extension 16(header type 'L') for large paths. 17 18[para] 19 20[list_begin definitions] 21 22[call [cmd ::tar::contents] [arg tarball] [opt [option -chan]]] 23 24Returns a list of the files contained in [arg tarball]. The order is not sorted and depends on the order 25files were stored in the archive. 26[para] 27 28If the option [option -chan] is present [arg tarball] is interpreted as an open channel. 29It is assumed that the channel was opened for reading, and configured for binary input. 30The command will [emph not] close the channel. 31 32[call [cmd ::tar::stat] [arg tarball] [opt file] [opt [option -chan]]] 33 34Returns a nested dict containing information on the named [opt file] in [arg tarball], 35or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys 36"[const mode] [const uid] [const gid] [const size] [const mtime] [const type] [const linkname] [const uname] [const gname] 37 [const devmajor] [const devminor]" 38 39[example { 40% ::tar::stat tarball.tar 41foo.jpg {mode 0644 uid 1000 gid 0 size 7580 mtime 811903867 type file linkname {} uname user gname wheel devmajor 0 devminor 0} 42}] 43 44[para] 45If the option [option -chan] is present [arg tarball] is interpreted as an open channel. 46It is assumed that the channel was opened for reading, and configured for binary input. 47The command will [emph not] close the channel. 48 49[call [cmd ::tar::untar] [arg tarball] [arg args]] 50 51Extracts [arg tarball]. [arg -file] and [arg -glob] limit the extraction 52to files which exactly match or pattern match the given argument. No error is 53thrown if no files match. Returns a list of filenames extracted and the file 54size. The size will be null for non regular files. Leading path seperators are 55stripped so paths will always be relative. 56 57[list_begin options] 58[opt_def -dir dirName] 59Directory to extract to. Uses [cmd pwd] if none is specified 60[opt_def -file fileName] 61Only extract the file with this name. The name is matched against the complete path 62stored in the archive including directories. 63[opt_def -glob pattern] 64Only extract files patching this glob style pattern. The pattern is matched against the complete path 65stored in the archive. 66[opt_def -nooverwrite] 67Dont overwrite files that already exist 68[opt_def -nomtime] 69Leave the file modification time as the current time instead of setting it to the value in the archive. 70[opt_def -noperms] 71In Unix, leave the file permissions as the current umask instead of setting them to the values in the archive. 72 73[opt_def -chan] 74If this option is present [arg tarball] is interpreted as an open channel. 75It is assumed that the channel was opened for reading, and configured for binary input. 76The command will [emph not] close the channel. 77 78[list_end] 79[para] 80 81[example { 82% foreach {file size} [::tar::untar tarball.tar -glob *.jpg] { 83puts "Extracted $file ($size bytes)" 84} 85}] 86 87[call [cmd ::tar::get] [arg tarball] [arg fileName] [opt [option -chan]]] 88 89Returns the contents of [arg fileName] from the [arg tarball]. 90 91[para][example { 92% set readme [::tar::get tarball.tar doc/README] { 93% puts $readme 94} 95}] 96 97[para] If the option [option -chan] is present [arg tarball] is 98interpreted as an open channel. It is assumed that the channel was 99opened for reading, and configured for binary input. The command will 100[emph not] close the channel. 101 102[para] An error is thrown when [arg fileName] is not found in the tar 103archive. 104 105[call [cmd ::tar::create] [arg tarball] [arg files] [arg args]] 106 107Creates a new tar file containing the [arg files]. [arg files] must be specified 108as a single argument which is a proper list of filenames. 109 110[list_begin options] 111[opt_def -dereference] 112Normally [cmd create] will store links as an actual link pointing at a file that may 113or may not exist in the archive. Specifying this option will cause the actual file point to 114 by the link to be stored instead. 115 116[opt_def -chan] 117If this option is present [arg tarball] is interpreted as an open channel. 118It is assumed that the channel was opened for writing, and configured for binary output. 119The command will [emph not] close the channel. 120 121[list_end] 122[para] 123 124[example { 125% ::tar::create new.tar [glob -nocomplain file*] 126% ::tar::contents new.tar 127file1 file2 file3 128}] 129 130[call [cmd ::tar::add] [arg tarball] [arg files] [arg args]] 131 132Appends [arg files] to the end of the existing [arg tarball]. [arg files] must be specified 133as a single argument which is a proper list of filenames. 134 135[list_begin options] 136[opt_def -dereference] 137Normally [cmd add] will store links as an actual link pointing at a file that may 138or may not exist in the archive. Specifying this option will cause the actual file point to 139 by the link to be stored instead. 140[opt_def -prefix string] 141Normally [cmd add] will store files under exactly the name specified as 142argument. Specifying a [opt -prefix] causes the [arg string] to be 143prepended to every name. 144[opt_def -quick] 145The only sure way to find the position in the [arg tarball] where new 146files can be added is to read it from start, but if [arg tarball] was 147written with a "blocksize" of 1 (as this package does) then one can 148alternatively find this position by seeking from the end. The 149[opt -quick] option tells [cmd add] to do the latter. 150[list_end] 151[para] 152 153[call [cmd ::tar::remove] [arg tarball] [arg files]] 154 155Removes [arg files] from the [arg tarball]. No error will result if the file does not exist in the 156tarball. Directory write permission and free disk space equivalent to at least the size of the tarball 157will be needed. 158 159[example { 160% ::tar::remove new.tar {file2 file3} 161% ::tar::contents new.tar 162file3 163}] 164 165[list_end] 166 167[vset CATEGORY tar] 168[include ../common-text/feedback.inc] 169[manpage_end] 170