github.com/eun/go@v0.0.0-20170811110501-92cfd07a6cfd/src/archive/tar/writer.go (about) 1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package tar 6 7 // TODO(dsymonds): 8 // - catch more errors (no first header, etc.) 9 10 import ( 11 "bytes" 12 "errors" 13 "fmt" 14 "io" 15 "path" 16 "sort" 17 "strconv" 18 "strings" 19 "time" 20 ) 21 22 var ( 23 ErrWriteTooLong = errors.New("archive/tar: write too long") 24 ErrFieldTooLong = errors.New("archive/tar: header field too long") 25 ErrWriteAfterClose = errors.New("archive/tar: write after close") 26 errInvalidHeader = errors.New("archive/tar: header field too long or contains invalid values") 27 ) 28 29 // A Writer provides sequential writing of a tar archive in POSIX.1 format. 30 // A tar archive consists of a sequence of files. 31 // Call WriteHeader to begin a new file, and then call Write to supply that file's data, 32 // writing at most hdr.Size bytes in total. 33 type Writer struct { 34 w io.Writer 35 err error 36 nb int64 // number of unwritten bytes for current file entry 37 pad int64 // amount of padding to write after current file entry 38 closed bool 39 usedBinary bool // whether the binary numeric field extension was used 40 preferPax bool // use PAX header instead of binary numeric header 41 hdrBuff block // buffer to use in writeHeader when writing a regular header 42 paxHdrBuff block // buffer to use in writeHeader when writing a PAX header 43 } 44 45 // NewWriter creates a new Writer writing to w. 46 func NewWriter(w io.Writer) *Writer { return &Writer{w: w} } 47 48 // Flush finishes writing the current file's block padding. 49 // The current file must be fully written before Flush can be called. 50 // 51 // Deprecated: This is unecessary as the next call to WriteHeader or Close 52 // will implicitly flush out the file's padding. 53 func (tw *Writer) Flush() error { 54 if tw.nb > 0 { 55 tw.err = fmt.Errorf("archive/tar: missed writing %d bytes", tw.nb) 56 return tw.err 57 } 58 tw.err = tw.writePadding() 59 return tw.err 60 } 61 62 func (tw *Writer) writePadding() error { 63 if _, err := tw.w.Write(zeroBlock[:tw.pad]); err != nil { 64 return err 65 } 66 tw.pad = 0 67 return nil 68 } 69 70 var ( 71 minTime = time.Unix(0, 0) 72 // There is room for 11 octal digits (33 bits) of mtime. 73 maxTime = minTime.Add((1<<33 - 1) * time.Second) 74 ) 75 76 // WriteHeader writes hdr and prepares to accept the file's contents. 77 // WriteHeader calls Flush if it is not the first header. 78 // Calling after a Close will return ErrWriteAfterClose. 79 func (tw *Writer) WriteHeader(hdr *Header) error { 80 // TODO(dsnet): Add PAX timestamps with nanosecond support. 81 hdrCpy := *hdr 82 hdrCpy.ModTime = hdrCpy.ModTime.Truncate(time.Second) 83 84 switch allowedFormats, _ := hdrCpy.allowedFormats(); { 85 case allowedFormats&formatUSTAR > 0: 86 // TODO(dsnet): Implement and call specialized writeUSTARHeader. 87 return tw.writeHeader(&hdrCpy, true) 88 case allowedFormats&formatPAX > 0: 89 // TODO(dsnet): Implement and call specialized writePAXHeader. 90 return tw.writeHeader(&hdrCpy, true) 91 case allowedFormats&formatGNU > 0: 92 // TODO(dsnet): Implement and call specialized writeGNUHeader. 93 return tw.writeHeader(&hdrCpy, true) 94 default: 95 return ErrHeader 96 } 97 } 98 99 // WriteHeader writes hdr and prepares to accept the file's contents. 100 // WriteHeader calls Flush if it is not the first header. 101 // Calling after a Close will return ErrWriteAfterClose. 102 // As this method is called internally by writePax header to allow it to 103 // suppress writing the pax header. 104 func (tw *Writer) writeHeader(hdr *Header, allowPax bool) error { 105 if tw.closed { 106 return ErrWriteAfterClose 107 } 108 if tw.err == nil { 109 tw.Flush() 110 } 111 if tw.err != nil { 112 return tw.err 113 } 114 115 // a map to hold pax header records, if any are needed 116 paxHeaders := make(map[string]string) 117 118 // TODO(dsnet): we might want to use PAX headers for 119 // subsecond time resolution, but for now let's just capture 120 // too long fields or non ascii characters 121 122 // We need to select which scratch buffer to use carefully, 123 // since this method is called recursively to write PAX headers. 124 // If allowPax is true, this is the non-recursive call, and we will use hdrBuff. 125 // If allowPax is false, we are being called by writePAXHeader, and hdrBuff is 126 // already being used by the non-recursive call, so we must use paxHdrBuff. 127 header := &tw.hdrBuff 128 if !allowPax { 129 header = &tw.paxHdrBuff 130 } 131 copy(header[:], zeroBlock[:]) 132 133 // Wrappers around formatter that automatically sets paxHeaders if the 134 // argument extends beyond the capacity of the input byte slice. 135 var f formatter 136 var formatString = func(b []byte, s string, paxKeyword string) { 137 needsPaxHeader := paxKeyword != paxNone && len(s) > len(b) || !isASCII(s) 138 if needsPaxHeader { 139 paxHeaders[paxKeyword] = s 140 } 141 142 // Write string in a best-effort manner to satisfy readers that expect 143 // the field to be non-empty. 144 s = toASCII(s) 145 if len(s) > len(b) { 146 s = s[:len(b)] 147 } 148 f.formatString(b, s) // Should never error 149 } 150 var formatNumeric = func(b []byte, x int64, paxKeyword string) { 151 if !fitsInOctal(len(b), x) { 152 if paxKeyword != paxNone && tw.preferPax { 153 // Use PAX format. 154 f.formatOctal(b, 0) 155 paxHeaders[paxKeyword] = strconv.FormatInt(x, 10) 156 return 157 } else { 158 // Use GNU format. 159 tw.usedBinary = true 160 } 161 } 162 f.formatNumeric(b, x) 163 } 164 165 // Handle out of range ModTime carefully. 166 var modTime int64 167 if !hdr.ModTime.Before(minTime) && !hdr.ModTime.After(maxTime) { 168 modTime = hdr.ModTime.Unix() 169 } 170 171 v7 := header.V7() 172 formatString(v7.Name(), hdr.Name, paxPath) 173 // TODO(dsnet): The GNU format permits the mode field to be encoded in 174 // base-256 format. Thus, we can use formatNumeric instead of formatOctal. 175 f.formatOctal(v7.Mode(), hdr.Mode) 176 formatNumeric(v7.UID(), int64(hdr.Uid), paxUid) 177 formatNumeric(v7.GID(), int64(hdr.Gid), paxGid) 178 formatNumeric(v7.Size(), hdr.Size, paxSize) 179 // TODO(dsnet): Consider using PAX for finer time granularity. 180 formatNumeric(v7.ModTime(), modTime, paxNone) 181 v7.TypeFlag()[0] = hdr.Typeflag 182 formatString(v7.LinkName(), hdr.Linkname, paxLinkpath) 183 184 ustar := header.USTAR() 185 formatString(ustar.UserName(), hdr.Uname, paxUname) 186 formatString(ustar.GroupName(), hdr.Gname, paxGname) 187 formatNumeric(ustar.DevMajor(), hdr.Devmajor, paxNone) 188 formatNumeric(ustar.DevMinor(), hdr.Devminor, paxNone) 189 190 // TODO(dsnet): The logic surrounding the prefix field is broken when trying 191 // to encode the header as GNU format. The challenge with the current logic 192 // is that we are unsure what format we are using at any given moment until 193 // we have processed *all* of the fields. The problem is that by the time 194 // all fields have been processed, some work has already been done to handle 195 // each field under the assumption that it is for one given format or 196 // another. In some situations, this causes the Writer to be confused and 197 // encode a prefix field when the format being used is GNU. Thus, producing 198 // an invalid tar file. 199 // 200 // As a short-term fix, we disable the logic to use the prefix field, which 201 // will force the badly generated GNU files to become encoded as being 202 // the PAX format. 203 // 204 // As an alternative fix, we could hard-code preferPax to be true. However, 205 // this is problematic for the following reasons: 206 // * The preferPax functionality is not tested at all. 207 // * This can result in headers that try to use both the GNU and PAX 208 // features at the same time, which is also wrong. 209 // 210 // The proper fix for this is to use a two-pass method: 211 // * The first pass simply determines what set of formats can possibly 212 // encode the given header. 213 // * The second pass actually encodes the header as that given format 214 // without worrying about violating the format. 215 // 216 // See the following: 217 // https://golang.org/issue/12594 218 // https://golang.org/issue/17630 219 // https://golang.org/issue/9683 220 const usePrefix = false 221 222 // try to use a ustar header when only the name is too long 223 _, paxPathUsed := paxHeaders[paxPath] 224 if usePrefix && !tw.preferPax && len(paxHeaders) == 1 && paxPathUsed { 225 prefix, suffix, ok := splitUSTARPath(hdr.Name) 226 if ok { 227 // Since we can encode in USTAR format, disable PAX header. 228 delete(paxHeaders, paxPath) 229 230 // Update the path fields 231 formatString(v7.Name(), suffix, paxNone) 232 formatString(ustar.Prefix(), prefix, paxNone) 233 } 234 } 235 236 if tw.usedBinary { 237 header.SetFormat(formatGNU) 238 } else { 239 header.SetFormat(formatUSTAR) 240 } 241 242 // Check if there were any formatting errors. 243 if f.err != nil { 244 tw.err = f.err 245 return tw.err 246 } 247 248 if allowPax { 249 for k, v := range hdr.Xattrs { 250 paxHeaders[paxXattr+k] = v 251 } 252 } 253 254 if len(paxHeaders) > 0 { 255 if !allowPax { 256 return errInvalidHeader 257 } 258 if err := tw.writePAXHeader(hdr, paxHeaders); err != nil { 259 return err 260 } 261 } 262 tw.nb = hdr.Size 263 tw.pad = (blockSize - (tw.nb % blockSize)) % blockSize 264 265 _, tw.err = tw.w.Write(header[:]) 266 return tw.err 267 } 268 269 // splitUSTARPath splits a path according to USTAR prefix and suffix rules. 270 // If the path is not splittable, then it will return ("", "", false). 271 func splitUSTARPath(name string) (prefix, suffix string, ok bool) { 272 length := len(name) 273 if length <= nameSize || !isASCII(name) { 274 return "", "", false 275 } else if length > prefixSize+1 { 276 length = prefixSize + 1 277 } else if name[length-1] == '/' { 278 length-- 279 } 280 281 i := strings.LastIndex(name[:length], "/") 282 nlen := len(name) - i - 1 // nlen is length of suffix 283 plen := i // plen is length of prefix 284 if i <= 0 || nlen > nameSize || nlen == 0 || plen > prefixSize { 285 return "", "", false 286 } 287 return name[:i], name[i+1:], true 288 } 289 290 // writePaxHeader writes an extended pax header to the 291 // archive. 292 func (tw *Writer) writePAXHeader(hdr *Header, paxHeaders map[string]string) error { 293 // Prepare extended header 294 ext := new(Header) 295 ext.Typeflag = TypeXHeader 296 // Setting ModTime is required for reader parsing to 297 // succeed, and seems harmless enough. 298 ext.ModTime = hdr.ModTime 299 // The spec asks that we namespace our pseudo files 300 // with the current pid. However, this results in differing outputs 301 // for identical inputs. As such, the constant 0 is now used instead. 302 // golang.org/issue/12358 303 dir, file := path.Split(hdr.Name) 304 fullName := path.Join(dir, "PaxHeaders.0", file) 305 306 ascii := toASCII(fullName) 307 if len(ascii) > nameSize { 308 ascii = ascii[:nameSize] 309 } 310 ext.Name = ascii 311 // Construct the body 312 var buf bytes.Buffer 313 314 // Keys are sorted before writing to body to allow deterministic output. 315 keys := make([]string, 0, len(paxHeaders)) 316 for k := range paxHeaders { 317 keys = append(keys, k) 318 } 319 sort.Strings(keys) 320 321 for _, k := range keys { 322 rec, err := formatPAXRecord(k, paxHeaders[k]) 323 if err != nil { 324 return err 325 } 326 fmt.Fprint(&buf, rec) 327 } 328 329 ext.Size = int64(len(buf.Bytes())) 330 if err := tw.writeHeader(ext, false); err != nil { 331 return err 332 } 333 if _, err := tw.Write(buf.Bytes()); err != nil { 334 return err 335 } 336 return tw.writePadding() 337 } 338 339 // Write writes to the current entry in the tar archive. 340 // Write returns the error ErrWriteTooLong if more than 341 // hdr.Size bytes are written after WriteHeader. 342 func (tw *Writer) Write(b []byte) (n int, err error) { 343 if tw.closed { 344 err = ErrWriteAfterClose 345 return 346 } 347 overwrite := false 348 if int64(len(b)) > tw.nb { 349 b = b[0:tw.nb] 350 overwrite = true 351 } 352 n, err = tw.w.Write(b) 353 tw.nb -= int64(n) 354 if err == nil && overwrite { 355 err = ErrWriteTooLong 356 return 357 } 358 tw.err = err 359 return 360 } 361 362 // Close closes the tar archive, flushing any unwritten 363 // data to the underlying writer. 364 func (tw *Writer) Close() error { 365 if tw.err != nil || tw.closed { 366 return tw.err 367 } 368 tw.Flush() 369 tw.closed = true 370 if tw.err != nil { 371 return tw.err 372 } 373 374 // trailer: two zero blocks 375 for i := 0; i < 2; i++ { 376 _, tw.err = tw.w.Write(zeroBlock[:]) 377 if tw.err != nil { 378 break 379 } 380 } 381 return tw.err 382 }