...

パッケージ tar

import "archive/tar"
概要
目次

概要 ▾

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

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

例 (Minimal)

コード:

// いくつかのファイルを作成してアーカイブに追加します。
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)
}

// アーカイブ内のファイルを開いて繰り返します。
tr := tar.NewReader(&buf)
for {
    hdr, err := tr.Next()
    if err == io.EOF {
        break // アーカイブの終わり
    }
    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()
}

出力:

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.

定数

Header.Typeflag のタイプフラグです。

const (
    // タイプ '0' は通常のファイルを示します。
    TypeReg  = '0'
    TypeRegA = '\x00' // 非推奨: 代わりに TypeReg を使用してください。

    // タイプ '1' から '6' はヘッダーのみのフラグであり,データ本体を持たない場合があります。
    TypeLink    = '1' // ハードリンク
    TypeSymlink = '2' // シンボリックリンク
    TypeChar    = '3' // キャラクタデバイスノード
    TypeBlock   = '4' // ブロックデバイスノード
    TypeDir     = '5' // ディレクトリ
    TypeFifo    = '6' // FIFO ノード

    // タイプ '7' は予約されています。
    TypeCont = '7'

    // タイプ 'x' は,次のファイルにのみ関連するキーバリューレコードを格納するために
    // PAX フォーマットによって使用されます。
    // このパッケージはこれらの型を透過的に扱います。
    TypeXHeader = 'x'

    // タイプ 'g' は,後続のすべてのファイルに関連するキーバリューレコードを保管するために
    // PAX フォーマットによって使用されます。
    // このパッケージは,ヘッダのパースと作成のみをサポートしていますが,
    // 現在のところファイル間でのグローバルステートの永続化はサポートしていません。
    TypeXGlobalHeader = 'g'

    // タイプ 'S' は, GNU フォーマットのスパースファイルを示します。
    TypeGNUSparse = 'S'

    // タイプ 'L' と 'K' は,次のファイルのパスまたはリンク名を格納するメタファイルのために
    // GNU フォーマットによって使用されます。
    // このパッケージはこれらの型を透過的に扱います。
    TypeGNULongName = 'L'
    TypeGNULongLink = 'K'
)

変数

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")
)

type Format 1.10

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

表の上部にはヘッダーフィールドが表示され,各形式は各文字列フィールドに許可される最大バイト数と各数値フィールドの格納に使用される整数型です (タイムスタンプは Unix エポック以降の秒数です) 。

表の下部には,サポートされている文字列エンコーディング, 1 秒未満のタイムスタンプのサポート,またはスパースファイルのサポートなど,各形式の特殊機能が示されています。

Writer は現在,スパースファイルをサポートしていません。

type Format int

さまざまな tar フォーマットを識別するための定数です。

const (

    // FormatUnknown は,形式が不明であることを示します。
    FormatUnknown Format

    // FormatUSTAR は POSIX.1-1988 で定義されている USTAR ヘッダフォーマットを表します。
    //
    // このフォーマットはほとんどの tar リーダーと互換性がありますが,
    // フォーマットにはいくつかの制限があり,用途によっては不適切です。
    // とりわけ,スパースファイル, 8 ギガバイトを超えるファイル, 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 の欠点を克服するために使用される一連の Key-Value レコードが含まれています。
    // さらに,タイムスタンプに対して 1 秒未満の精度を持つことができます。
    //
    // 新しいフォーマットの中には,独自のキーを定義し,
    // 関連する値に特定の意味を割り当てることによって,独自の拡張を PAX に追加するものがあります。
    // 例えば,PAX におけるスパースファイルサポートは,GNUN マニュアルによって定義されたキー
    // (例えば, "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
)

func (Format) String 1.10

func (f Format) String() string

Header (ヘッダ) は, tar アーカイブ内の 1 つのヘッダを表します。 いくつかのフィールドは入っていないかもしれません。

上位互換性のために, Reader.Next から Header を取得し,それを何らかの方法で変更してから Writer.WriteHeader に戻す場合,新しい Header を作成し,保存したいフィールドをコピーすべきです。

type Header struct {
    // Typeflag はヘッダエントリの種類です。
    // Name の末尾にスラッシュがあるかどうかに応じて,
    // ゼロ値が自動的に TypeReg または TypeDir になります。
    Typeflag byte

    Name     string // ファイルエントリの名前
    Linkname string // リンクのターゲット名 (TypeLink または TypeSymlink で有効)

    Size  int64  // 論理ファイルサイズ (バイト)
    Mode  int64  // パーミッションビットとモードビット
    Uid   int    // 所有者のユーザー ID
    Gid   int    // 所有者のグループ ID
    Uname string // 所有者のユーザー名
    Gname string // 所有者のグループ名

    // Format が指定されていない場合, Writer.WriteHeader は ModTime を最も近い秒に丸めて,
    // AccessTime フィールドと ChangeTime フィールドを無視します。
    //
    // AccessTime または ChangeTime を使用するには,Format を PAX または GNU として指定します。
    // 1 秒未満の精度を使用するには,Format を PAX として指定します。
    ModTime    time.Time // 修正時間
    AccessTime time.Time // アクセス時間 (PAX または GNU のサポートが必要)
    ChangeTime time.Time // 変更時間 (PAX または GNU サポートが必要)

    Devmajor int64 // メジャーデバイス番号 (TypeChar または TypeBlock で有効)
    Devminor int64 // マイナーデバイス番号 (TypeChar または TypeBlock で有効)

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

    // PAXRecords は, PAX 拡張ヘッダーレコードのマップです。
    //
    // ユーザー定義レコードには,次の形式のキーであるべきです。
    //	VENDOR.keyword
    // VENDOR はすべて大文字の名前空間で, keyword は '=' 文字を含むことはできません
    // (例: "GOLANG.pkg.version") 。
    // キーと値は空でない UTF-8 文字列であるべきです。
    //
    // Writer.WriteHeader が呼び出されると, Header の他のフィールドから作られた
    // PAX レコードが PAXRecords よりも優先されます。
    PAXRecords map[string]string // Go 1.10

    // Format は, tar ヘッダーの形式を指定します。
    //
    // これは, Reader.Next によって,ベストエフォートで推測されるフォーマットで設定されます。
    // Reader は自由で非準拠ファイルも読むので, FormatUnknown となるかもしれません。
    //
    // Writer.WriteHeader が呼び出されたときに形式が指定されていない場合は,
    // このヘッダーをエンコードできる最初の形式 (USTAR, PAX, GNU の順)
    // が使用されます (Format を参照) 。
    Format Format // Go 1.10
}

func FileInfoHeader 1.1

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

FileInfoHeader は, fi から部分的に入力された Header を作成します。 fi がシンボリックリンクを表す場合, FileInfoHeader はリンク先として link を記録します。 fi がディレクトリを表す場合,スラッシュが名前に追加されます。

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

func (*Header) FileInfo 1.1

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

FileInfo はヘッダーの os.FileInfo を返します。

type Reader

Reader は tar アーカイブの内容へのシーケンシャルアクセスを提供します。 Reader.Next はアーカイブ内の次のファイル (最初のファイルを含む) に進み,その後 Reader はファイルのデータにアクセスする io.Reader として扱うことができます。

type Reader struct {
    // エクスポートされていないフィールドがあります
}

func NewReader

func NewReader(r io.Reader) *Reader

NewReader は, r から読み取る新しい Reader を作成します。

func (*Reader) Next

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

Next は tar アーカイブの次のエントリに進みます。 Header.Size は,次のファイル用に読み込むことができるバイト数を決定します。 現在のファイルに残っているデータは自動的に破棄されます。

入力の終わりに io.EOF が返されます。

func (*Reader) Read

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

Read は, tar アーカイブ内の現在のファイルから読み取ります。 そのファイルの終わりに達すると, Next を呼び出して次のファイルに進むまで (0, io.EOF) を返します。

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

TypeLink, TypeSymlink, TypeChar, TypeBlock, TypeDir, および TypeFifo などの特殊な型で Read を呼び出すと, Header.Size の指定内容に関係なく, (0, io.EOF) が返されます。

type Writer

Writer は tar アーカイブの連続書き込みを提供します。 Write.WriteHeader は Header を渡して新しいファイルを開始し,それから, Writer を io.Writer として使ってファイルのデータを書き込みます。

type Writer struct {
    // エクスポートされていないフィールドがあります
}

func NewWriter

func NewWriter(w io.Writer) *Writer

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

func (*Writer) Close

func (tw *Writer) Close() error

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

func (*Writer) Flush

func (tw *Writer) Flush() error

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

次回の WriteHeader または Close の呼び出しで暗黙的にファイルのパディングが消去されるため,これは不要です。

func (*Writer) Write

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

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

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 は,次のファイルに書き込めるバイト数を決定します。 現在のファイルが完全に書き込まれていない場合,これはエラーを返します。 これは,ヘッダーを書き込む前に必要なパディングを暗黙的にフラッシュします。