minitar 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,306 +1,304 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- class Minitar
4
- # Implements the POSIX tar header as a Ruby class. The structure of
5
- # the POSIX tar header is:
6
- #
7
- # struct tarfile_entry_posix
8
- # { // pack unpack
9
- # char name[100]; // ASCII (+ Z unless filled) a100 Z100
10
- # char mode[8]; // 0 padded, octal, null a8 A8
11
- # char uid[8]; // 0 padded, octal, null a8 A8
12
- # char gid[8]; // 0 padded, octal, null a8 A8
13
- # char size[12]; // 0 padded, octal, null a12 A12
14
- # char mtime[12]; // 0 padded, octal, null a12 A12
15
- # char checksum[8]; // 0 padded, octal, null, space a8 A8
16
- # char typeflag[1]; // see below a a
17
- # char linkname[100]; // ASCII + (Z unless filled) a100 Z100
18
- # char magic[6]; // "ustar\0" a6 A6
19
- # char version[2]; // "00" a2 A2
20
- # char uname[32]; // ASCIIZ a32 Z32
21
- # char gname[32]; // ASCIIZ a32 Z32
22
- # char devmajor[8]; // 0 padded, octal, null a8 A8
23
- # char devminor[8]; // 0 padded, octal, null a8 A8
24
- # char prefix[155]; // ASCII (+ Z unless filled) a155 Z155
25
- # };
26
- #
27
- # The #typeflag is one of several known values. POSIX indicates that "A POSIX-compliant
28
- # implementation must treat any unrecognized typeflag value as a regular file."
29
- class PosixHeader
30
- BLOCK_SIZE = 512
31
- MAGIC_BYTES = "ustar"
32
-
33
- GNU_EXT_LONG_LINK = "././@LongLink"
34
-
35
- # Fields that must be set in a POSIX tar(1) header.
36
- REQUIRED_FIELDS = [:name, :size, :prefix, :mode].freeze
37
- # Fields that may be set in a POSIX tar(1) header.
38
- OPTIONAL_FIELDS = [
39
- :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version, :uname,
40
- :gname, :devmajor, :devminor
41
- ].freeze
42
-
43
- # All fields available in a POSIX tar(1) header.
44
- FIELDS = (REQUIRED_FIELDS + OPTIONAL_FIELDS).freeze
3
+ # Implements the POSIX tar header as a Ruby class. The structure of
4
+ # the POSIX tar header is:
5
+ #
6
+ # ```c
7
+ # struct tarfile_entry_posix
8
+ # { // pack unpack
9
+ # char name[100]; // ASCII (+ Z unless filled) a100 Z100
10
+ # char mode[8]; // 0 padded, octal, null a8 A8
11
+ # char uid[8]; // 0 padded, octal, null a8 A8
12
+ # char gid[8]; // 0 padded, octal, null a8 A8
13
+ # char size[12]; // 0 padded, octal, null a12 A12
14
+ # char mtime[12]; // 0 padded, octal, null a12 A12
15
+ # char checksum[8]; // 0 padded, octal, null, space a8 A8
16
+ # char typeflag[1]; // see below a a
17
+ # char linkname[100]; // ASCII + (Z unless filled) a100 Z100
18
+ # char magic[6]; // "ustar\0" a6 A6
19
+ # char version[2]; // "00" a2 A2
20
+ # char uname[32]; // ASCIIZ a32 Z32
21
+ # char gname[32]; // ASCIIZ a32 Z32
22
+ # char devmajor[8]; // 0 padded, octal, null a8 A8
23
+ # char devminor[8]; // 0 padded, octal, null a8 A8
24
+ # char prefix[155]; // ASCII (+ Z unless filled) a155 Z155
25
+ # };
26
+ # ```
27
+ #
28
+ # The #typeflag is one of several known values. POSIX indicates that "A POSIX-compliant
29
+ # implementation must treat any unrecognized typeflag value as a regular file."
30
+ class Minitar::PosixHeader
31
+ BLOCK_SIZE = 512
32
+ MAGIC_BYTES = "ustar"
33
+
34
+ GNU_EXT_LONG_LINK = "././@LongLink"
35
+
36
+ # Fields that must be set in a POSIX tar(1) header.
37
+ REQUIRED_FIELDS = [:name, :size, :prefix, :mode].freeze
38
+ # Fields that may be set in a POSIX tar(1) header.
39
+ OPTIONAL_FIELDS = [
40
+ :uid, :gid, :mtime, :checksum, :typeflag, :linkname, :magic, :version, :uname,
41
+ :gname, :devmajor, :devminor
42
+ ].freeze
43
+
44
+ # All fields available in a POSIX tar(1) header.
45
+ FIELDS = (REQUIRED_FIELDS + OPTIONAL_FIELDS).freeze
46
+
47
+ FIELDS.each do |f|
48
+ attr_reader f.to_sym
49
+ end
45
50
 
46
- FIELDS.each do |f|
47
- attr_reader f.to_sym
48
- end
51
+ ##
52
+ def name=(value)
53
+ valid_name!(value)
54
+ @name = value
55
+ end
49
56
 
50
- ##
51
- def name=(value)
52
- valid_name!(value)
53
- @name = value
57
+ attr_writer :size
58
+
59
+ # The pack format passed to Array#pack for encoding a header.
60
+ HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155"
61
+ # The unpack format passed to String#unpack for decoding a header.
62
+ HEADER_UNPACK_FORMAT = "Z100A8A8A8a12A12A8aZ100A6A2Z32Z32A8A8Z155"
63
+
64
+ class << self
65
+ # Creates a new PosixHeader from a data stream.
66
+ def from_stream(stream) = from_data(stream.read(BLOCK_SIZE))
67
+
68
+ # Creates a new PosixHeader from a BLOCK_SIZE-byte data buffer.
69
+ def from_data(data)
70
+ fields = data.unpack(HEADER_UNPACK_FORMAT)
71
+ name = fields.shift
72
+ mode = fields.shift.oct
73
+ uid = fields.shift.oct
74
+ gid = fields.shift.oct
75
+ size = parse_numeric_field(fields.shift)
76
+ mtime = fields.shift.oct
77
+ checksum = fields.shift.oct
78
+ typeflag = fields.shift
79
+ linkname = fields.shift
80
+ magic = fields.shift
81
+ version = fields.shift.oct
82
+ uname = fields.shift
83
+ gname = fields.shift
84
+ devmajor = fields.shift.oct
85
+ devminor = fields.shift.oct
86
+ prefix = fields.shift
87
+
88
+ empty = !data.each_byte.any?(&:nonzero?)
89
+
90
+ new(
91
+ name: name,
92
+ mode: mode,
93
+ uid: uid,
94
+ gid: gid,
95
+ size: size,
96
+ mtime: mtime,
97
+ checksum: checksum,
98
+ typeflag: typeflag,
99
+ magic: magic,
100
+ version: version,
101
+ uname: uname,
102
+ gname: gname,
103
+ devmajor: devmajor,
104
+ devminor: devminor,
105
+ prefix: prefix,
106
+ empty: empty,
107
+ linkname: linkname
108
+ )
54
109
  end
55
110
 
56
- attr_writer :size
57
-
58
- # The pack format passed to Array#pack for encoding a header.
59
- HEADER_PACK_FORMAT = "a100a8a8a8a12a12a7aaa100a6a2a32a32a8a8a155"
60
- # The unpack format passed to String#unpack for decoding a header.
61
- HEADER_UNPACK_FORMAT = "Z100A8A8A8a12A12A8aZ100A6A2Z32Z32A8A8Z155"
62
-
63
- class << self
64
- # Creates a new PosixHeader from a data stream.
65
- def from_stream(stream) = from_data(stream.read(BLOCK_SIZE))
66
-
67
- # Creates a new PosixHeader from a BLOCK_SIZE-byte data buffer.
68
- def from_data(data)
69
- fields = data.unpack(HEADER_UNPACK_FORMAT)
70
- name = fields.shift
71
- mode = fields.shift.oct
72
- uid = fields.shift.oct
73
- gid = fields.shift.oct
74
- size = parse_numeric_field(fields.shift)
75
- mtime = fields.shift.oct
76
- checksum = fields.shift.oct
77
- typeflag = fields.shift
78
- linkname = fields.shift
79
- magic = fields.shift
80
- version = fields.shift.oct
81
- uname = fields.shift
82
- gname = fields.shift
83
- devmajor = fields.shift.oct
84
- devminor = fields.shift.oct
85
- prefix = fields.shift
86
-
87
- empty = !data.each_byte.any?(&:nonzero?)
88
-
89
- new(
90
- name: name,
91
- mode: mode,
92
- uid: uid,
93
- gid: gid,
94
- size: size,
95
- mtime: mtime,
96
- checksum: checksum,
97
- typeflag: typeflag,
98
- magic: magic,
99
- version: version,
100
- uname: uname,
101
- gname: gname,
102
- devmajor: devmajor,
103
- devminor: devminor,
104
- prefix: prefix,
105
- empty: empty,
106
- linkname: linkname
107
- )
108
- end
109
-
110
- private
111
-
112
- def parse_numeric_field(string)
113
- return string.oct if /\A[0-7 \0]*\z/.match?(string) # \0 appears as a padding
114
- return parse_base256(string) if string.bytes.first == 0x80 || string.bytes.first == 0xff
115
- raise ArgumentError, "#{string.inspect} is not a valid numeric field"
116
- end
111
+ private
117
112
 
118
- def parse_base256(string)
119
- # https://www.gnu.org/software/tar/manual/html_node/Extensions.html
120
- bytes = string.bytes
121
- case bytes.first
122
- when 0x80 # Positive number: *non-leading* bytes, number in big-endian order
123
- bytes[1..].inject(0) { |r, byte| (r << 8) | byte }
124
- when 0xff # Negative number: *all* bytes, two's complement in big-endian order
125
- result = bytes.inject(0) { |r, byte| (r << 8) | byte }
126
- bit_length = bytes.size * 8
127
- result - (1 << bit_length)
128
- else
129
- raise ArgumentError, "Invalid binary field format"
130
- end
131
- end
113
+ def parse_numeric_field(string)
114
+ return string.oct if /\A[0-7 \0]*\z/.match?(string) # \0 appears as a padding
115
+ return parse_base256(string) if string.bytes.first == 0x80 || string.bytes.first == 0xff
116
+ raise ArgumentError, "#{string.inspect} is not a valid numeric field"
132
117
  end
133
118
 
134
- # Creates a new PosixHeader. A PosixHeader cannot be created unless +name+, +size+,
135
- # +prefix+, and +mode+ are provided.
136
- def initialize(v)
137
- REQUIRED_FIELDS.each do |f|
138
- raise ArgumentError, "Field #{f} is required." unless v.key?(f)
119
+ def parse_base256(string)
120
+ # https://www.gnu.org/software/tar/manual/html_node/Extensions.html
121
+ bytes = string.bytes
122
+ case bytes.first
123
+ when 0x80 # Positive number: *non-leading* bytes, number in big-endian order
124
+ bytes[1..].inject(0) { |r, byte| (r << 8) | byte }
125
+ when 0xff # Negative number: *all* bytes, two's complement in big-endian order
126
+ result = bytes.inject(0) { |r, byte| (r << 8) | byte }
127
+ bit_length = bytes.size * 8
128
+ result - (1 << bit_length)
129
+ else
130
+ raise ArgumentError, "Invalid binary field format"
139
131
  end
132
+ end
133
+ end
140
134
 
141
- v[:mtime] = v[:mtime].to_i
142
- v[:checksum] ||= ""
143
- v[:typeflag] ||= "0"
144
- v[:magic] ||= MAGIC_BYTES
145
- v[:version] ||= "00"
146
-
147
- FIELDS.each do |f|
148
- instance_variable_set(:"@#{f}", v[f])
149
- end
135
+ # Creates a new PosixHeader from a Hash. A PosixHeader cannot be created unless `name`,
136
+ # `size`, `prefix`, and `mode` are provided.
137
+ def initialize(v)
138
+ REQUIRED_FIELDS.each do |f|
139
+ raise ArgumentError, "Field #{f} is required." unless v.key?(f)
140
+ end
150
141
 
151
- @empty = v[:empty]
142
+ v[:mtime] = v[:mtime].to_i
143
+ v[:checksum] ||= ""
144
+ v[:typeflag] ||= "0"
145
+ v[:magic] ||= MAGIC_BYTES
146
+ v[:version] ||= "00"
152
147
 
153
- valid_name!(v[:name]) unless v[:empty]
148
+ FIELDS.each do |f|
149
+ instance_variable_set(:"@#{f}", v[f])
154
150
  end
155
151
 
156
- # Indicates if the header was an empty header.
157
- def empty? = @empty
152
+ @empty = v[:empty]
158
153
 
159
- # Indicates if the header has a valid magic value.
160
- def valid? = empty? || @magic == MAGIC_BYTES
161
-
162
- # Returns +true+ if the header is a long name special header which indicates
163
- # that the next block of data is the filename.
164
- def long_name? = typeflag == "L" && name == GNU_EXT_LONG_LINK
154
+ valid_name!(v[:name]) unless v[:empty]
155
+ end
165
156
 
166
- # Returns +true+ if the header is a PAX extended header which contains
167
- # metadata for the next file entry.
168
- def pax_header? = typeflag == "x"
157
+ # Indicates if the header was an empty header.
158
+ def empty? = @empty
169
159
 
170
- # Sets the +name+ to the +value+ provided and clears +prefix+.
171
- #
172
- # Used by Minitar::Reader#each_entry to set the long name when processing GNU long
173
- # filename extensions.
174
- #
175
- # The +value+ must be the complete name, including leading directory components.
176
- def long_name=(value)
177
- valid_name!(value)
160
+ # Indicates if the header has a valid magic value.
161
+ def valid? = empty? || @magic == MAGIC_BYTES
178
162
 
179
- @prefix = ""
180
- @name = value
181
- end
163
+ # Returns `true` if the header is a long name special header which indicates
164
+ # that the next block of data is the filename.
165
+ def long_name? = typeflag == "L" && name == GNU_EXT_LONG_LINK
182
166
 
183
- # A string representation of the header.
184
- def to_s
185
- update_checksum
186
- header(@checksum)
187
- end
188
- alias_method :to_str, :to_s
167
+ # Returns `true` if the header is a PAX extended header which contains
168
+ # metadata for the next file entry.
169
+ def pax_header? = typeflag == "x"
189
170
 
190
- # TODO: In Minitar 2, PosixHeader#to_str will be removed.
171
+ # Sets the `name` to the `value` provided and clears `prefix`.
172
+ #
173
+ # Used by Minitar::Reader#each_entry to set the long name when processing GNU long
174
+ # filename extensions.
175
+ #
176
+ # The `value` must be the complete name, including leading directory components.
177
+ def long_name=(value)
178
+ valid_name!(value)
191
179
 
192
- # Update the checksum field.
193
- def update_checksum
194
- hh = header(" " * 8)
195
- @checksum = oct(calculate_checksum(hh), 6)
196
- end
180
+ @prefix = ""
181
+ @name = value
182
+ end
197
183
 
198
- private
184
+ # A string representation of the header.
185
+ def to_s
186
+ update_checksum
187
+ header(@checksum)
188
+ end
189
+ alias_method :to_str, :to_s
199
190
 
200
- def valid_name!(value)
201
- return if value.is_a?(String) && !value.empty?
202
- raise ArgumentError, "Field name must be a non-empty string"
203
- end
191
+ # TODO: In Minitar 2, PosixHeader#to_str will be removed.
204
192
 
205
- def oct(num, len)
206
- if num.nil?
207
- "\0" * (len + 1)
208
- else
209
- "%0#{len}o" % num
210
- end
211
- end
193
+ # Update the checksum field.
194
+ def update_checksum
195
+ hh = header(" " * 8)
196
+ @checksum = oct(calculate_checksum(hh), 6)
197
+ end
198
+ ##
199
+ # :attr_accessor: name
200
+ # The name of the file. Required.
201
+ #
202
+ # By default, limited to 100 bytes, but may be up to BLOCK_SIZE bytes if using the
203
+ # GNU long name tar extension.
204
+
205
+ ##
206
+ # :attr_accessor: size
207
+ # The size of the file. Required.
208
+
209
+ ##
210
+ # :attr_reader: prefix
211
+ # The prefix of the file; the path before #name. Limited to 155 bytes.
212
+ # Required.
213
+
214
+ ##
215
+ # :attr_reader: mode
216
+ # The Unix file mode of the file. Stored as an octal integer. Required.
217
+
218
+ ##
219
+ # :attr_reader: uid
220
+ # The Unix owner user ID of the file. Stored as an octal integer.
221
+
222
+ ##
223
+ # :attr_reader: uname
224
+ # The user name of the Unix owner of the file.
225
+
226
+ ##
227
+ # :attr_reader: gid
228
+ # The Unix owner group ID of the file. Stored as an octal integer.
229
+
230
+ ##
231
+ # :attr_reader: gname
232
+ # The group name of the Unix owner of the file.
233
+
234
+ ##
235
+ # :attr_reader: mtime
236
+ # The modification time of the file in epoch seconds. Stored as an
237
+ # octal integer.
238
+
239
+ ##
240
+ # :attr_reader: checksum
241
+ # The checksum of the file. Stored as an octal integer. Calculated
242
+ # before encoding the header as a string.
243
+
244
+ ##
245
+ # :attr_reader: typeflag
246
+ # The type of record in the file.
247
+ #
248
+ # - `0`: Regular file. NULL should be treated as a synonym, for compatibility purposes.
249
+ # - `1`: Hard link.
250
+ # - `2`: Symbolic link.
251
+ # - `3`: Character device node.
252
+ # - `4`: Block device node.
253
+ # - `5`: Directory.
254
+ # - `6`: FIFO node.
255
+ # - `7`: Reserved.
256
+ # - `L`: GNU extension for long filenames when #name is `././@LongLink`.
257
+
258
+ ##
259
+ # :attr_reader: linkname
260
+ # The target of the symbolic link.
261
+
262
+ ##
263
+ # :attr_reader: magic
264
+ # Always "ustar\0".
265
+
266
+ ##
267
+ # :attr_reader: version
268
+ # Always "00"
269
+
270
+ ##
271
+ # :attr_reader: devmajor
272
+ # The major device ID. Not currently used.
273
+
274
+ ##
275
+ # :attr_reader: devminor
276
+ # The minor device ID. Not currently used.
277
+
278
+ private
279
+
280
+ def valid_name!(value)
281
+ return if value.is_a?(String) && !value.empty?
282
+ raise ArgumentError, "Field name must be a non-empty string"
283
+ end
212
284
 
213
- def calculate_checksum(hdr)
214
- hdr.unpack("C*").inject(:+)
285
+ def oct(num, len)
286
+ if num.nil?
287
+ "\0" * (len + 1)
288
+ else
289
+ "%0#{len}o" % num
215
290
  end
291
+ end
216
292
 
217
- def header(chksum)
218
- arr = [name, oct(mode, 7), oct(uid, 7), oct(gid, 7), oct(size, 11),
219
- oct(mtime, 11), chksum, " ", typeflag, linkname, magic, version,
220
- uname, gname, oct(devmajor, 7), oct(devminor, 7), prefix]
221
- str = arr.pack(HEADER_PACK_FORMAT)
222
- str + "\0" * ((BLOCK_SIZE - str.bytesize) % BLOCK_SIZE)
223
- end
293
+ def calculate_checksum(hdr)
294
+ hdr.unpack("C*").inject(:+)
295
+ end
224
296
 
225
- ##
226
- # :attr_accessor: name
227
- # The name of the file. Required.
228
- #
229
- # By default, limited to 100 bytes, but may be up to BLOCK_SIZE bytes if using the
230
- # GNU long name tar extension.
231
-
232
- ##
233
- # :attr_accessor: size
234
- # The size of the file. Required.
235
-
236
- ##
237
- # :attr_reader: prefix
238
- # The prefix of the file; the path before #name. Limited to 155 bytes.
239
- # Required.
240
-
241
- ##
242
- # :attr_reader: mode
243
- # The Unix file mode of the file. Stored as an octal integer. Required.
244
-
245
- ##
246
- # :attr_reader: uid
247
- # The Unix owner user ID of the file. Stored as an octal integer.
248
-
249
- ##
250
- # :attr_reader: uname
251
- # The user name of the Unix owner of the file.
252
-
253
- ##
254
- # :attr_reader: gid
255
- # The Unix owner group ID of the file. Stored as an octal integer.
256
-
257
- ##
258
- # :attr_reader: gname
259
- # The group name of the Unix owner of the file.
260
-
261
- ##
262
- # :attr_reader: mtime
263
- # The modification time of the file in epoch seconds. Stored as an
264
- # octal integer.
265
-
266
- ##
267
- # :attr_reader: checksum
268
- # The checksum of the file. Stored as an octal integer. Calculated
269
- # before encoding the header as a string.
270
-
271
- ##
272
- # :attr_reader: typeflag
273
- # The type of record in the file.
274
- #
275
- # +0+:: Regular file. NULL should be treated as a synonym, for compatibility
276
- # purposes.
277
- # +1+:: Hard link.
278
- # +2+:: Symbolic link.
279
- # +3+:: Character device node.
280
- # +4+:: Block device node.
281
- # +5+:: Directory.
282
- # +6+:: FIFO node.
283
- # +7+:: Reserved.
284
- # +L+:: GNU extension for long filenames when #name is <tt>././@LongLink</tt>.
285
-
286
- ##
287
- # :attr_reader: linkname
288
- # The target of the symbolic link.
289
-
290
- ##
291
- # :attr_reader: magic
292
- # Always "ustar\0".
293
-
294
- ##
295
- # :attr_reader: version
296
- # Always "00"
297
-
298
- ##
299
- # :attr_reader: devmajor
300
- # The major device ID. Not currently used.
301
-
302
- ##
303
- # :attr_reader: devminor
304
- # The minor device ID. Not currently used.
297
+ def header(chksum)
298
+ arr = [name, oct(mode, 7), oct(uid, 7), oct(gid, 7), oct(size, 11),
299
+ oct(mtime, 11), chksum, " ", typeflag, linkname, magic, version,
300
+ uname, gname, oct(devmajor, 7), oct(devminor, 7), prefix]
301
+ str = arr.pack(HEADER_PACK_FORMAT)
302
+ str + "\0" * ((BLOCK_SIZE - str.bytesize) % BLOCK_SIZE)
305
303
  end
306
304
  end