Debian Codegraph @

upstream/mageia-cauldron/man3pm/Archive::Tar::File.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Archive::Tar::File 3pm"
61 .TH Archive::Tar::File 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Archive::Tar::File \- a subclass for in\-memory extracted file from Archive::Tar
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& my @items = $tar\->get_files;
72 \&
73 \& print $_\->name, \*(Aq \*(Aq, $_\->size, "\en" for @items;
74 \&
75 \& print $object\->get_content;
76 \& $object\->replace_content(\*(Aqnew content\*(Aq);
77 \&
78 \& $object\->rename( \*(Aqnew/full/path/to/file.c\*(Aq );
79 .Ve
80 .SH DESCRIPTION
81 .IX Header "DESCRIPTION"
82 Archive::Tar::File provides a neat little object layer for in\-memory
83 extracted files. It\*(Aqs mostly used internally in Archive::Tar to tidy
84 up the code, but there\*(Aqs no reason users shouldn\*(Aqt use this API as
85 well.
86 .SS Accessors
87 .IX Subsection "Accessors"
88 A lot of the methods in this package are accessors to the various
89 fields in the tar header:
90 .IP name 4
91 .IX Item "name"
92 The file\*(Aqs name
93 .IP mode 4
94 .IX Item "mode"
95 The file\*(Aqs mode
96 .IP uid 4
97 .IX Item "uid"
98 The user id owning the file
99 .IP gid 4
100 .IX Item "gid"
101 The group id owning the file
102 .IP size 4
103 .IX Item "size"
104 File size in bytes
105 .IP mtime 4
106 .IX Item "mtime"
107 Modification time. Adjusted to mac\-time on MacOS if required
108 .IP chksum 4
109 .IX Item "chksum"
110 Checksum field for the tar header
111 .IP type 4
112 .IX Item "type"
113 File type \-\- numeric, but comparable to exported constants \-\- see
114 Archive::Tar\*(Aqs documentation
115 .IP linkname 4
116 .IX Item "linkname"
117 If the file is a symlink, the file it\*(Aqs pointing to
118 .IP magic 4
119 .IX Item "magic"
120 Tar magic string \-\- not useful for most users
121 .IP version 4
122 .IX Item "version"
123 Tar version string \-\- not useful for most users
124 .IP uname 4
125 .IX Item "uname"
126 The user name that owns the file
127 .IP gname 4
128 .IX Item "gname"
129 The group name that owns the file
130 .IP devmajor 4
131 .IX Item "devmajor"
132 Device major number in case of a special file
133 .IP devminor 4
134 .IX Item "devminor"
135 Device minor number in case of a special file
136 .IP prefix 4
137 .IX Item "prefix"
138 Any directory to prefix to the extraction path, if any
139 .IP raw 4
140 .IX Item "raw"
141 Raw tar header \-\- not useful for most users
142 .SH Methods
143 .IX Header "Methods"
144 .ie n .SS "Archive::Tar::File\->new( file => $path )"
145 .el .SS "Archive::Tar::File\->new( file => \f(CW$path\fP )"
146 .IX Subsection "Archive::Tar::File->new( file => $path )"
147 Returns a new Archive::Tar::File object from an existing file.
148 .PP
149 Returns undef on failure.
150 .ie n .SS "Archive::Tar::File\->new( data => $path, $data, $opt )"
151 .el .SS "Archive::Tar::File\->new( data => \f(CW$path\fP, \f(CW$data\fP, \f(CW$opt\fP )"
152 .IX Subsection "Archive::Tar::File->new( data => $path, $data, $opt )"
153 Returns a new Archive::Tar::File object from data.
154 .PP
155 \&\f(CW$path\fR defines the file name (which need not exist), \f(CW$data\fR the
156 file contents, and \f(CW$opt\fR is a reference to a hash of attributes
157 which may be used to override the default attributes (fields in the
158 tar header), which are described above in the Accessors section.
159 .PP
160 Returns undef on failure.
161 .ie n .SS "Archive::Tar::File\->new( chunk => $chunk )"
162 .el .SS "Archive::Tar::File\->new( chunk => \f(CW$chunk\fP )"
163 .IX Subsection "Archive::Tar::File->new( chunk => $chunk )"
164 Returns a new Archive::Tar::File object from a raw 512\-byte tar
165 archive chunk.
166 .PP
167 Returns undef on failure.
168 .ie n .SS "$bool = $file\->extract( [ $alternative_name ] )"
169 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->extract( [ \f(CW$alternative_name\fP ] )"
170 .IX Subsection "$bool = $file->extract( [ $alternative_name ] )"
171 Extract this object, optionally to an alternative name.
172 .PP
173 See \f(CW\*(C`Archive::Tar\->extract_file\*(C'\fR for details.
174 .PP
175 Returns true on success and false on failure.
176 .ie n .SS "$path = $file\->full_path"
177 .el .SS "\f(CW$path\fP = \f(CW$file\fP\->full_path"
178 .IX Subsection "$path = $file->full_path"
179 Returns the full path from the tar header; this is basically a
180 concatenation of the \f(CW\*(C`prefix\*(C'\fR and \f(CW\*(C`name\*(C'\fR fields.
181 .ie n .SS "$bool = $file\->validate"
182 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->validate"
183 .IX Subsection "$bool = $file->validate"
184 Done by Archive::Tar internally when reading the tar file:
185 validate the header against the checksum to ensure integer tar file.
186 .PP
187 Returns true on success, false on failure
188 .ie n .SS "$bool = $file\->has_content"
189 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->has_content"
190 .IX Subsection "$bool = $file->has_content"
191 Returns a boolean to indicate whether the current object has content.
192 Some special files like directories and so on never will have any
193 content. This method is mainly to make sure you don\*(Aqt get warnings
194 for using uninitialized values when looking at an object\*(Aqs content.
195 .ie n .SS "$content = $file\->get_content"
196 .el .SS "\f(CW$content\fP = \f(CW$file\fP\->get_content"
197 .IX Subsection "$content = $file->get_content"
198 Returns the current content for the in\-memory file
199 .ie n .SS "$cref = $file\->get_content_by_ref"
200 .el .SS "\f(CW$cref\fP = \f(CW$file\fP\->get_content_by_ref"
201 .IX Subsection "$cref = $file->get_content_by_ref"
202 Returns the current content for the in\-memory file as a scalar
203 reference. Normal users won\*(Aqt need this, but it will save memory if
204 you are dealing with very large data files in your tar archive, since
205 it will pass the contents by reference, rather than make a copy of it
206 first.
207 .ie n .SS "$bool = $file\->replace_content( $content )"
208 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->replace_content( \f(CW$content\fP )"
209 .IX Subsection "$bool = $file->replace_content( $content )"
210 Replace the current content of the file with the new content. This
211 only affects the in\-memory archive, not the on\-disk version until
212 you write it.
213 .PP
214 Returns true on success, false on failure.
215 .ie n .SS "$bool = $file\->rename( $new_name )"
216 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->rename( \f(CW$new_name\fP )"
217 .IX Subsection "$bool = $file->rename( $new_name )"
218 Rename the current file to \f(CW$new_name\fR.
219 .PP
220 Note that you must specify a Unix path for \f(CW$new_name\fR, since per tar
221 standard, all files in the archive must be Unix paths.
222 .PP
223 Returns true on success and false on failure.
224 .ie n .SS "$bool = $file\->chmod( $mode )"
225 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->chmod( \f(CW$mode\fP )"
226 .IX Subsection "$bool = $file->chmod( $mode )"
227 Change mode of \f(CW$file\fR to \f(CW$mode\fR. The mode can be a string or a number
228 which is interpreted as octal whether or not a leading 0 is given.
229 .PP
230 Returns true on success and false on failure.
231 .ie n .SS "$bool = $file\->chown( $user [, $group])"
232 .el .SS "\f(CW$bool\fP = \f(CW$file\fP\->chown( \f(CW$user\fP [, \f(CW$group\fP])"
233 .IX Subsection "$bool = $file->chown( $user [, $group])"
234 Change owner of \f(CW$file\fR to \f(CW$user\fR. If a \f(CW$group\fR is given that is changed
235 as well. You can also pass a single parameter with a colon separating the
236 use and group as in \*(Aqroot:wheel\*(Aq.
237 .PP
238 Returns true on success and false on failure.
239 .SH "Convenience methods"
240 .IX Header "Convenience methods"
241 To quickly check the type of a \f(CW\*(C`Archive::Tar::File\*(C'\fR object, you can
242 use the following methods:
243 .ie n .IP $file\->is_file 4
244 .el .IP \f(CW$file\fR\->is_file 4
245 .IX Item "$file->is_file"
246 Returns true if the file is of type \f(CW\*(C`file\*(C'\fR
247 .ie n .IP $file\->is_dir 4
248 .el .IP \f(CW$file\fR\->is_dir 4
249 .IX Item "$file->is_dir"
250 Returns true if the file is of type \f(CW\*(C`dir\*(C'\fR
251 .ie n .IP $file\->is_hardlink 4
252 .el .IP \f(CW$file\fR\->is_hardlink 4
253 .IX Item "$file->is_hardlink"
254 Returns true if the file is of type \f(CW\*(C`hardlink\*(C'\fR
255 .ie n .IP $file\->is_symlink 4
256 .el .IP \f(CW$file\fR\->is_symlink 4
257 .IX Item "$file->is_symlink"
258 Returns true if the file is of type \f(CW\*(C`symlink\*(C'\fR
259 .ie n .IP $file\->is_chardev 4
260 .el .IP \f(CW$file\fR\->is_chardev 4
261 .IX Item "$file->is_chardev"
262 Returns true if the file is of type \f(CW\*(C`chardev\*(C'\fR
263 .ie n .IP $file\->is_blockdev 4
264 .el .IP \f(CW$file\fR\->is_blockdev 4
265 .IX Item "$file->is_blockdev"
266 Returns true if the file is of type \f(CW\*(C`blockdev\*(C'\fR
267 .ie n .IP $file\->is_fifo 4
268 .el .IP \f(CW$file\fR\->is_fifo 4
269 .IX Item "$file->is_fifo"
270 Returns true if the file is of type \f(CW\*(C`fifo\*(C'\fR
271 .ie n .IP $file\->is_socket 4
272 .el .IP \f(CW$file\fR\->is_socket 4
273 .IX Item "$file->is_socket"
274 Returns true if the file is of type \f(CW\*(C`socket\*(C'\fR
275 .ie n .IP $file\->is_longlink 4
276 .el .IP \f(CW$file\fR\->is_longlink 4
277 .IX Item "$file->is_longlink"
278 Returns true if the file is of type \f(CW\*(C`LongLink\*(C'\fR.
279 Should not happen after a successful \f(CW\*(C`read\*(C'\fR.
280 .ie n .IP $file\->is_label 4
281 .el .IP \f(CW$file\fR\->is_label 4
282 .IX Item "$file->is_label"
283 Returns true if the file is of type \f(CW\*(C`Label\*(C'\fR.
284 Should not happen after a successful \f(CW\*(C`read\*(C'\fR.
285 .ie n .IP $file\->is_unknown 4
286 .el .IP \f(CW$file\fR\->is_unknown 4
287 .IX Item "$file->is_unknown"
288 Returns true if the file type is \f(CW\*(C`unknown\*(C'\fR