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  }