tar

Documentation

Overview

tarパッケージは、tarアーカイブへのアクセスを実装します。

テープアーカイブ（tar）は、ストリーミング方式で読み書きできるファイル形式で、 一連のファイルを格納するために使用されます。 このパッケージは、GNUおよびBSD tarツールによって生成されたものを含め、 このフォーマットのほとんどのバリエーションをカバーすることを目的としています。

Example (Minimal)

package main

import (
	"github.com/shogo82148/std/archive/tar"
	"github.com/shogo82148/std/bytes"
	"github.com/shogo82148/std/fmt"
	"github.com/shogo82148/std/io"
	"github.com/shogo82148/std/log"
	"github.com/shogo82148/std/os"
)

func main() {
	// Create and add some files to the archive.
	var buf bytes.Buffer
	tw := tar.NewWriter(&buf)
	var files = []struct {
		Name, Body string
	}{
		{"readme.txt", "This archive contains some text files."},
		{"gopher.txt", "Gopher names:\nGeorge\nGeoffrey\nGonzo"},
		{"todo.txt", "Get animal handling license."},
	}
	for _, file := range files {
		hdr := &tar.Header{
			Name: file.Name,
			Mode: 0600,
			Size: int64(len(file.Body)),
		}
		if err := tw.WriteHeader(hdr); err != nil {
			log.Fatal(err)
		}
		if _, err := tw.Write([]byte(file.Body)); err != nil {
			log.Fatal(err)
		}
	}
	if err := tw.Close(); err != nil {
		log.Fatal(err)
	}

	// Open and iterate through the files in the archive.
	tr := tar.NewReader(&buf)
	for {
		hdr, err := tr.Next()
		if err == io.EOF {
			break // End of archive
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Printf("Contents of %s:\n", hdr.Name)
		if _, err := io.Copy(os.Stdout, tr); err != nil {
			log.Fatal(err)
		}
		fmt.Println()
	}

}

Output:

Contents of readme.txt:
This archive contains some text files.
Contents of gopher.txt:
Gopher names:
George
Geoffrey
Gonzo
Contents of todo.txt:
Get animal handling license.

Index

• Constants
• Variables
• type FileInfoNames
• type Format
  • func (f Format) String() string
• type Header
  • func FileInfoHeader(fi fs.FileInfo, link string) (*Header, error)
  • func (h *Header) FileInfo() fs.FileInfo
• type Reader
  • func NewReader(r io.Reader) *Reader
  • func (tr *Reader) Next() (*Header, error)
  • func (tr *Reader) Read(b []byte) (int, error)
• type Writer
  • func NewWriter(w io.Writer) *Writer
  • func (tw *Writer) AddFS(fsys fs.FS) error
  • func (tw *Writer) Close() error
  • func (tw *Writer) Flush() error
  • func (tw *Writer) Write(b []byte) (int, error)
  • func (tw *Writer) WriteHeader(hdr *Header) error

Examples

• Package (Minimal)

Constants

const (
	// Type '0' は通常のファイルを示します。
	TypeReg = '0'

	// Deprecated: 非推奨：かわりにTypeRegを使用してください。
	TypeRegA = '\x00'

	// Type '1'から'6'は、ヘッダーのみのフラグであり、データ本体を持たない場合があります。
	TypeLink    = '1'
	TypeSymlink = '2'
	TypeChar    = '3'
	TypeBlock   = '4'
	TypeDir     = '5'
	TypeFifo    = '6'

	// Type '7' は予約されています。
	TypeCont = '7'

	// Type 'x' は、PAXフォーマットで、次のファイルにのみ関連するキー-値レコードを格納するために使用されます。
	// このパッケージは、これらのタイプを透過的に処理します。
	TypeXHeader = 'x'

	// 'g' 型は、すべての後続ファイルに関連するキーと値のレコードを格納するために PAX 形式で使用されます。
	// このパッケージは、このようなヘッダーの解析と構成のみをサポートしていますが、現在はファイル間でグローバル状態を永続化することはできません。
	TypeXGlobalHeader = 'g'

	// 'S' 型は、GNU 形式でスパースファイルを示します。
	TypeGNUSparse = 'S'

	// 'L' 型と 'K' 型は、GNU 形式でメタファイルに使用されます。
	// このメタファイルは、次のファイルのパスまたはリンク名を格納するために使用されます。
	// このパッケージは、これらのタイプを透過的に処理します。
	TypeGNULongName = 'L'
	TypeGNULongLink = 'K'
)

Type flags for Header.Typeflag.

Variables

var (
	ErrHeader          = errors.New("archive/tar: invalid tar header")
	ErrWriteTooLong    = errors.New("archive/tar: write too long")
	ErrFieldTooLong    = errors.New("archive/tar: header field too long")
	ErrWriteAfterClose = errors.New("archive/tar: write after close")
	ErrInsecurePath    = errors.New("archive/tar: insecure file path")
)

Types

type FileInfoNames

type FileInfoNames interface {
	fs.FileInfo

	Uname() (string, error)

	Gname() (string, error)
}

FileInfoNames extends fs.FileInfo. Passing an instance of this to FileInfoHeader permits the caller to avoid a system-dependent name lookup by specifying the Uname and Gname directly.

type Format

type Format int

Formatはtarアーカイブのフォーマットを表します。

オリジナルのtarフォーマットはUnix V7で導入されました。 その後、V7フォーマットの制限を克服するために標準化または拡張を試みる複数の競合するフォーマットがありました。 最も一般的なフォーマットは、USTAR、PAX、GNUフォーマットで、それぞれ独自の利点と制限があります。

次の表は、各フォーマットの機能を示しています：

                  |  USTAR |       PAX |       GNU
------------------+--------+-----------+----------
Name              |   256B | unlimited | unlimited
Linkname          |   100B | unlimited | unlimited
Size              | uint33 | unlimited |    uint89
Mode              | uint21 |    uint21 |    uint57
Uid/Gid           | uint21 | unlimited |    uint57
Uname/Gname       |    32B | unlimited |       32B
ModTime           | uint33 | unlimited |     int89
AccessTime        |    n/a | unlimited |     int89
ChangeTime        |    n/a | unlimited |     int89
Devmajor/Devminor | uint21 |    uint21 |    uint57
------------------+--------+-----------+----------
string encoding   |  ASCII |     UTF-8 |    binary
sub-second times  |     no |       yes |        no
sparse files      |     no |       yes |       yes

この表の上部は、 Header フィールドを示しており、各フォーマットが各文字列フィールドに許可される最大バイト数と、 各数値フィールドを格納するために使用される整数型を報告します （タイムスタンプは、Unixエポックからの秒数として格納されます）。

表の下部は、各フォーマットの特殊な機能を示しています。 たとえば、サポートされる文字列エンコーディング、サブセカンドタイムスタンプのサポート、スパースファイルのサポートなどがあります。

Writerは現在、スパースファイルに対するサポートを提供していません。

const (

	// FormatUnknownは、フォーマットが不明であることを示します。
	FormatUnknown Format

	// FormatUSTARは、POSIX.1-1988で定義されたUSTARヘッダーフォーマットを表します。
	//
	// このフォーマットは、ほとんどのtarリーダーと互換性がありますが、
	// このフォーマットにはいくつかの制限があるため、一部の用途には適していません。
	// 特に、スパースファイル、8GiBを超えるファイル、256文字を超えるファイル名、および非ASCIIファイル名をサポートできません。
	//
	// 参考：
	//	http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06
	FormatUSTAR

	// FormatPAXは、POSIX.1-2001で定義されたPAXヘッダーフォーマットを表します。
	//
	// PAXは、Typeflag TypeXHeaderを持つ特別なファイルを書き込むことで、USTARを拡張します。
	// このファイルには、USTARの制限を克服するために使用される一連のキー-値レコードが含まれています。
	// さらに、タイムスタンプのサブセカンド解像度を提供する機能もあります。
	//
	// 一部の新しいフォーマットは、独自のキーを定義し、関連する値に特定の意味を割り当てることで、PAXに独自の拡張機能を追加します。
	// たとえば、PAXでのスパースファイルのサポートは、GNUマニュアルで定義されたキー（例：「GNU.sparse.map」）を使用して実装されています。
	//
	// 参考：
	//	http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html
	FormatPAX

	// FormatGNUは、GNUヘッダーフォーマットを表します。
	//
	// GNUヘッダーフォーマットは、USTARおよびPAX規格よりも古く、
	// それらとの互換性はありません。
	// GNUフォーマットは、任意のファイルサイズ、任意のエンコーディングと長さのファイル名、スパースファイルなどをサポートします。
	//
	// GNUフォーマットのアーカイブの解析ができるアプリケーションしかない場合を除き、PAXをGNUよりも選択することが推奨されます。
	//
	// 参考：
	//	https://www.gnu.org/software/tar/manual/html_node/Standard.html
	FormatGNU
)

Constants to identify various tar formats.

func (Format) String

func (f Format) String() string

type Header

type Header struct {
	// Typeflagはヘッダーエントリのタイプです。
	// ゼロ値は、Nameの末尾のスラッシュの有無に応じて、自動的にTypeRegまたはTypeDirに昇格します。
	Typeflag byte

	Name     string
	Linkname string

	Size  int64
	Mode  int64
	Uid   int
	Gid   int
	Uname string
	Gname string

	// Formatが指定されていない場合、Writer.WriteHeaderはModTimeを最も近い秒に丸め、
	// AccessTimeとChangeTimeフィールドを無視します。
	//
	// AccessTimeまたはChangeTimeを使用するには、FormatをPAXまたはGNUとして指定します。
	// サブセカンドの解像度を使用するには、FormatをPAXとして指定します。
	ModTime    time.Time
	AccessTime time.Time
	ChangeTime time.Time

	Devmajor int64
	Devminor int64

	// Xattrsは、"SCHILY.xattr."名前空間の下のPAXレコードとして拡張属性を保存します。
	//
	// 以下は意味的に等価です：
	//  h.Xattrs[key] = value
	//  h.PAXRecords["SCHILY.xattr."+key] = value
	//
	// Writer.WriteHeaderが呼び出されると、Xattrsの内容がPAXRecordsのものよりも優先されます。
	//
	// Deprecated: 代わりにPAXRecordsを使用してください。
	Xattrs map[string]string

	// PAXRecordsは、PAX拡張ヘッダーレコードのマップです。
	//
	// ユーザー定義のレコードは、次の形式のキーを持つべきです：
	//	VENDOR.keyword
	// ここで、VENDORはすべて大文字の何らかの名前空間であり、keywordは
	// '='文字を含んではなりません（例："GOLANG.pkg.version"）。
	// キーと値は非空のUTF-8文字列でなければなりません。
	//
	// Writer.WriteHeaderが呼び出されると、Headerの他のフィールドから派生した
	// PAXレコードは、PAXRecordsよりも優先されます。
	PAXRecords map[string]string

	// Formatはtarヘッダーの形式を指定します。
	//
	// これは、Reader.Nextによって形式の最善の推測として設定されます。
	// Readerは一部の非準拠ファイルを寛大に読み取るため、
	// これがFormatUnknownである可能性があります。
	//
	// Writer.WriteHeaderが呼び出されたときに形式が指定されていない場合、
	// このHeaderをエンコードできる最初の形式（USTAR、PAX、GNUの順）を使用します（Formatを参照）。
	Format Format
}

Header は、tar アーカイブ内の単一のヘッダーを表します。 一部のフィールドは、値が設定されていない場合があります。

将来の互換性のために、Reader.Next から Header を取得し、 いくつかの方法で変更し、Writer.WriteHeader に戻すユーザーは、 新しい Header を作成し、保存する必要があるフィールドをコピーすることで行う必要があります。

func FileInfoHeader

func FileInfoHeader(fi fs.FileInfo, link string) (*Header, error)

FileInfoHeaderは、fiから部分的に設定された Header を作成します。 fiがシンボリックリンクを記述している場合、FileInfoHeaderはlinkをリンクターゲットとして記録します。 fiがディレクトリを記述している場合、名前にスラッシュが追加されます。

fs.FileInfoのNameメソッドは、それが記述するファイルのベース名のみを返すため、 ファイルの完全なパス名を提供するためにHeader.Nameを変更する必要があるかもしれません。

fiが FileInfoNames を実装している場合、 Header.GnameとHeader.Unameはインターフェースのメソッドによって提供されます。

func (*Header) FileInfo

func (h *Header) FileInfo() fs.FileInfo

fs.FileInfoのNameメソッドは、説明するファイルのベース名のみを返すため、 ファイルの完全なパス名を提供するためにHeader.Nameを変更する必要がある場合があります。

fiが FileInfoNames を実装している場合、ヘッダーのGnameとUnameは、 インターフェースのメソッドによって提供されます。 FileInfoは、Headerのfs.FileInfoを返します。

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Readerはtarアーカイブの内容に順次アクセスするためのものです。 Reader.Next はアーカイブ内の次のファイル（最初のファイルを含む）に進み、 その後、Readerはファイルのデータにアクセスするためのio.Readerとして扱うことができます。

func NewReader

func NewReader(r io.Reader) *Reader

NewReaderはrから読み取りを行う新しい Reader を作成します。

func (*Reader) Next

func (tr *Reader) Next() (*Header, error)

Nextはtarアーカイブ内の次のエントリに進みます。 Header.Sizeは次のファイルの読み取り可能なバイト数を決定します。 現在のファイルに残っているデータは自動的に破棄されます。 アーカイブの末尾に達した場合、Nextはエラーio.EOFを返します。

Nextが [filepath.IsLocal] によって定義されるローカルでない名前に遭遇し、 GODEBUG環境変数に`tarinsecurepath=0`が含まれている場合、 Nextは ErrInsecurePath エラーを伴うヘッダーを返します。 将来のGoのバージョンでは、この動作がデフォルトで導入される可能性があります。 ローカルでない名前を受け入れたいプログラムは、 ErrInsecurePath エラーを無視して返されたヘッダーを使用できます。

func (*Reader) Read

func (tr *Reader) Read(b []byte) (int, error)

Readはtarアーカイブの現在のファイルから読み取ります。 それはそのファイルの終わりに達するとき（0、io.EOF）を返します、 次のファイルに進むために [Next] が呼び出されるまで。

現在のファイルがスパースである場合、 穴としてマークされた領域はNULバイトとして読み戻されます。

TypeLink 、 TypeSymlink 、 TypeChar 、 TypeBlock 、 TypeDir 、 TypeFifo などの特殊なタイプでReadを呼び出すと、 [Header.Size] が示す内容に関係なく、(0, io.EOF) が返されます。

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writerはtarアーカイブの順次書き込みを提供します。 Writer.WriteHeader は提供された Header で新しいファイルを開始し、 その後、Writerはそのファイルのデータを提供するためのio.Writerとして扱うことができます。

func NewWriter

func NewWriter(w io.Writer) *Writer

NewWriterはwに書き込む新しいWriterを作成します。

func (*Writer) AddFS

func (tw *Writer) AddFS(fsys fs.FS) error

AddFSは、fs.FSからファイルをアーカイブに追加します。 ファイルシステムのルートから開始してディレクトリツリーを走査し、 各ファイルをtarアーカイブに追加しながらディレクトリ構造を維持します。

func (*Writer) Close

func (tw *Writer) Close() error

Closeはパディングをフラッシュし、フッターを書き込むことでtarアーカイブを閉じます。 (以前の Writer.WriteHeader の呼び出しで)現在のファイルが完全に書き込まれていない場合、エラーが返されます。

func (*Writer) Flush

func (tw *Writer) Flush() error

Flushは現在のファイルのブロックパディングの書き込みを終了します。 Flushを呼び出す前に、現在のファイルは完全に書き込まれている必要があります。

これは、次の Writer.WriteHeader または Writer.Close の呼び出しで ファイルのパディングが暗黙的にフラッシュされるため、不要です。

func (*Writer) Write

func (tw *Writer) Write(b []byte) (int, error)

Writeは、tarアーカイブの現在のファイルに書き込みます。 Writer.WriteHeader の後にHeader.Sizeバイト以上が書き込まれた場合、Writeは Writer.WriteHeader エラーを返します。

TypeLink 、 TypeSymlink 、 TypeChar 、 TypeBlock 、 TypeDir 、 TypeFifo などの特殊なタイプでWriteを呼び出すと、 [Header.Size] が示す内容に関係なく、(0, ErrWriteTooLong)が返されます。

func (*Writer) WriteHeader

func (tw *Writer) WriteHeader(hdr *Header) error

WriteHeaderはhdrを書き込み、ファイルの内容を受け入れる準備をします。 Header.Sizeは、次のファイルの書き込み可能なバイト数を決定します。 現在のファイルが完全に書き込まれていない場合、エラーが返されます。 これにより、ヘッダを書き込す前に必要なパディングが暗黙的にフラッシュされます。