"tarfile" — tar アーカイブファイルの読み書き
********************************************

バージョン 2.3 で追加.

**ソースコード:** Lib/tarfile.py

======================================================================

The "tarfile" module makes it possible to read and write tar archives,
including those using gzip or bz2 compression. Use the "zipfile"
module to read or write ".zip" files, or the higher-level functions in
shutil.

いくつかの事実と形態:

* reads and writes "gzip" and "bz2" compressed archives if the
  respective modules are available.

* POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。

* read/write support for the GNU tar format including *longname* and
  *longlink* extensions, read-only support for the *sparse* extension.

* POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。

  バージョン 2.6 で追加.

* ディレクトリ、一般ファイル、ハードリンク、シンボリックリンク、fifo
  、 キャラクターデバイスおよびブロックデバイスを処理します。また、タ
  イム スタンプ、アクセス許可や所有者のようなファイル情報の取得および
  保存が 可能です。

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

   パス名 *name* の "TarFile" オブジェクトを返します。"TarFile" オブジ
   ェクトと、利用できるキーワード引数に関する詳細な情報については、
   TarFile オブジェクト 節を参照してください。

   *mode* は "'filemode[:compression]'" の形式をとる文字列でなければな
   りません。デフォルトの値は "'r'" です。以下に *mode* のとりうる組み
   合わせすべてを示します:

   +--------------------+-----------------------------------------------+
   | mode               | action                                        |
   +====================+===============================================+
   | "'r' または 'r:*'" | 圧縮方法に関して透過的に、読み込み用にオープ  |
   |                    | ンします (推奨)。                             |
   +--------------------+-----------------------------------------------+
   | "'r:'"             | 非圧縮で読み込み用に排他的にオープンします。  |
   +--------------------+-----------------------------------------------+
   | "'r:gz'"           | gzip 圧縮で読み込み用にオープンします。       |
   +--------------------+-----------------------------------------------+
   | "'r:bz2'"          | bzip2 圧縮で読み込み用にオープンします。      |
   +--------------------+-----------------------------------------------+
   | "'a' または 'a:'"  | 非圧縮で追記用にオープンします。ファイルが存  |
   |                    | 在しない場合は新たに作 成されます。           |
   +--------------------+-----------------------------------------------+
   | "'w' または 'w:'"  | 非圧縮で書き込み用にオープンします。          |
   +--------------------+-----------------------------------------------+
   | "'w:gz'"           | gzip 圧縮で書き込み用にオープンします。       |
   +--------------------+-----------------------------------------------+
   | "'w:bz2'"          | bzip2 圧縮で書き込み用にオープンします。      |
   +--------------------+-----------------------------------------------+

   Note that "'a:gz'" or "'a:bz2'" is not possible. If *mode* is not
   suitable to open a certain (compressed) file for reading,
   "ReadError" is raised. Use *mode* "'r'" to avoid this.  If a
   compression method is not supported, "CompressionError" is raised.

   If *fileobj* is specified, it is used as an alternative to a file
   object opened for *name*. It is supposed to be at position 0.

   For modes "'w:gz'", "'r:gz'", "'w:bz2'", "'r:bz2'",
   "tarfile.open()" accepts the keyword argument *compresslevel*
   (default "9") to specify the compression level of the file.

   For special purposes, there is a second format for *mode*:
   "'filemode|[compression]'".  "tarfile.open()" will return a
   "TarFile" object that processes its data as a stream of blocks.  No
   random seeking will be done on the file. If given, *fileobj* may be
   any object that has a "read()" or "write()" method (depending on
   the *mode*). *bufsize* specifies the blocksize and defaults to "20
   * 512" bytes. Use this variant in combination with e.g.
   "sys.stdin", a socket file object or a tape device. However, such a
   "TarFile" object is limited in that it does not allow random
   access, see 使用例.  The currently possible modes:

   +---------------+----------------------------------------------+
   | モード        | 動作                                         |
   +===============+==============================================+
   | "'r|*'"       | tar ブロックの *stream* を圧縮方法に関して透 |
   |               | 過的に読み込み用にオー プンします。          |
   +---------------+----------------------------------------------+
   | "'r|'"        | 非圧縮 tar ブロックの *stream* を読み込み用  |
   |               | にオープンします。                           |
   +---------------+----------------------------------------------+
   | "'r|gz'"      | gzip 圧縮の *stream* を読み込み用にオープン  |
   |               | します。                                     |
   +---------------+----------------------------------------------+
   | "'r|bz2'"     | bzip2 圧縮の *stream* を読み込み用にオープン |
   |               | します。                                     |
   +---------------+----------------------------------------------+
   | "'w|'"        | 非圧縮の *stream* を書き込み用にオープンしま |
   |               | す。                                         |
   +---------------+----------------------------------------------+
   | "'w|gz'"      | gzip 圧縮の *stream* を書き込み用にオープン  |
   |               | します。                                     |
   +---------------+----------------------------------------------+
   | "'w|bz2'"     | bzip2 圧縮の *stream* を書き込み用にオープン |
   |               | します。                                     |
   +---------------+----------------------------------------------+

class tarfile.TarFile

   Class for reading and writing tar archives. Do not use this class
   directly, better use "tarfile.open()" instead. See TarFile オブジェ
   クト.

tarfile.is_tarfile(name)

   もし *name* が tar アーカイブファイルであり、"tarfile" モジュールで
   読み込める場合に "True" を返します。

class tarfile.TarFileCompat(filename, mode='r', compression=TAR_PLAIN)

   Class for limited access to tar archives with a "zipfile"-like
   interface. Please consult the documentation of the "zipfile" module
   for more details. *compression* must be one of the following
   constants:

   TAR_PLAIN

      Constant for an uncompressed tar archive.

   TAR_GZIPPED

      Constant for a "gzip" compressed tar archive.

   バージョン 2.6 で撤廃: The "TarFileCompat" class has been removed
   in Python 3.

exception tarfile.TarError

   すべての "tarfile" 例外のための基本クラスです。

exception tarfile.ReadError

   tar アーカイブがオープンされた時、"tarfile" モジュールで操作できな
   いか、あるいは何か無効であるとき送出されます。

exception tarfile.CompressionError

   圧縮方法がサポートされていないか、あるいはデータを正しくデコードで
   きない時に送出されます。

exception tarfile.StreamError

   ストリームのような "TarFile" オブジェクトで典型的な制限のために送出
   されます。

exception tarfile.ExtractError

   "TarFile.extract()" を使った時に *致命的でない* エラーに対して送出
   されます。ただし "TarFile.errorlevel""== 2" の場合に限ります。

モジュールレベルで以下の定数が利用できます。

tarfile.ENCODING

   既定の文字エンコーディング。Windows では "'utf-8'" 、それ以外では
   "sys.getfilesystemencoding()" の返り値です。

exception tarfile.HeaderError

   "TarInfo.frombuf()" メソッドが取得したバッファーが不正だったときに
   送出されます。

   バージョン 2.6 で追加.

以下の各定数は、"tarfile" モジュールが作成できる tar アーカイブフォー
マットを定義しています。詳細は、サポートしている tar フォーマット を参
照してください。

tarfile.USTAR_FORMAT

   POSIX.1-1988 (ustar) フォーマット。

tarfile.GNU_FORMAT

   GNU tar フォーマット。

tarfile.PAX_FORMAT

   POSIX.1-2001 (pax) フォーマット。

tarfile.DEFAULT_FORMAT

   アーカイブを作成する際のデフォルトのフォーマット。現在は
   "GNU_FORMAT" です。

参考:

  "zipfile" モジュール
     "zipfile" 標準モジュールのドキュメント。

  アーカイブ化操作
     "shutil" が提供するより高水準のアーカイブ機能についてのドキュメン
     ト。

  GNU tar manual, Basic Tar Format
     GNU tar 拡張機能を含む、tar アーカイブファイルのためのドキュメン
     ト。


TarFile オブジェクト
====================

"TarFile" オブジェクトは、tar アーカイブへのインターフェースを提供しま
す。tar アーカイブは一連のブロックです。アーカイブメンバー (保存された
ファイル) は、ヘッダーブロックとそれに続くデータブロックで構成されてい
ます。一つの tar アーカイブにファイルを何回も保存することができます。
各アーカイブメンバーは、"TarInfo" オブジェクトで確認できます。詳細につ
いては TarInfo オブジェクト を参照してください。

"TarFile" オブジェクトは "with" 文のコンテキストマネージャーとして利用
できます。with ブロックが終了したときにオブジェクトはクローズされます
。例外が発生した時、内部で利用されているファイルオブジェクトのみがクロ
ーズされ、書き込み用にオープンされたアーカイブのファイナライズは行われ
ないことに注意してください。使用例 節のユースケースを参照してください
。

バージョン 2.7 で追加: コンテキスト管理のプロトコルがサポートされまし
た。

class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=None, pax_headers=None, debug=0, errorlevel=0)

   以下のすべての引数はオプションで、インスタンス属性としてもアクセス
   できます。

   *name* is the pathname of the archive. It can be omitted if
   *fileobj* is given. In this case, the file object’s "name"
   attribute is used if it exists.

   *mode* is either "'r'" to read from an existing archive, "'a'" to
   append data to an existing file or "'w'" to create a new file
   overwriting an existing one.

   *fileobj* が与えられていれば、それを使ってデータを読み書きします。
   もしそれが決定できれば、*mode* は *fileobj* のモードで上書きされま
   す。*fileobj* は位置 0 から利用されます。

   注釈: "TarFile" をクローズした時、*fileobj* はクローズされません
     。

   *format* はアーカイブのフォーマットを制御します。モジュールレベルで
   定義されている、"USTAR_FORMAT"、"GNU_FORMAT"、あるいは "PAX_FORMAT"
   のいずれかである必要があります。

   バージョン 2.6 で追加.

   *tarinfo* 引数を利用して、デフォルトの "TarInfo" クラスを別のクラス
   で置き換えることができます。

   バージョン 2.6 で追加.

   *dereference* が "False" だった場合、シンボリックリンクやハードリン
   クがアーカイブに追加されます。"True" だった場合、リンクのターゲット
   となるファイルの内容がアーカイブに追加されます。シンボリックリンク
   をサポートしていないシステムでは効果がありません。

   *ignore_zeros* が "False" だった場合、空ブロックをアーカイブの終端
   として扱います。"True" だった場合、空の (無効な) ブロックをスキップ
   して、可能な限り多くのメンバーを取得しようとします。このオプション
   は、連結されたり、壊れたアーカイブファイルを扱うときにのみ、意味が
   あります。

   *debug* は "0" (デバッグメッセージ無し) から "3" (全デバッグメッセ
   ージ) まで設定できます。このメッセージは "sys.stderr" に書き込まれ
   ます。

   If *errorlevel* is "0", all errors are ignored when using
   "TarFile.extract()". Nevertheless, they appear as error messages in
   the debug output, when debugging is enabled.  If "1", all *fatal*
   errors are raised as "OSError" or "IOError" exceptions. If "2", all
   *non-fatal* errors are raised as "TarError" exceptions as well.

   The *encoding* and *errors* arguments control the way strings are
   converted to unicode objects and vice versa. The default settings
   will work for most users. See section Unicode に関する問題 for in-
   depth information.

   バージョン 2.6 で追加.

   The *pax_headers* argument is an optional dictionary of unicode
   strings which will be added as a pax global header if *format* is
   "PAX_FORMAT".

   バージョン 2.6 で追加.

classmethod TarFile.open(...)

   代替コンストラクターです。モジュールレベルでの "tarfile.open()" 関
   数は、実際はこのクラスメソッドへのショートカットです。

TarFile.getmember(name)

   メンバー *name* に対する "TarInfo" オブジェクトを返します。*name*
   がアーカイブに見つからなければ、"KeyError" が送出されます。

   注釈: アーカイブ内にメンバーが複数ある場合は、最後に出現するもの
     が最新 のバージョンとみなされます。

TarFile.getmembers()

   "TarInfo" アーカイブのメンバーをオブジェクトのリストとして返します
   。このリストはアーカイブ内のメンバーと同じ順番です。

TarFile.getnames()

   メンバーをその名前のリストを返します。これは "getmembers()" で返さ
   れるリストと同じ順番です。

TarFile.list(verbose=True)

   Print a table of contents to "sys.stdout". If *verbose* is "False",
   only the names of the members are printed. If it is "True", output
   similar to that of **ls -l** is produced.

TarFile.next()

   "TarFile" が読み込み用にオープンされている時、アーカイブの次のメン
   バーを "TarInfo" オブジェクトとして返します。もしそれ以上利用可能な
   ものがなければ、"None" を返します。

TarFile.extractall(path=".", members=None)

   すべてのメンバーをアーカイブから現在の作業ディレクトリまたは *path*
   に抽出します。オプションの *members* が与えられるときには、
   "getmembers()" で返されるリストの一部でなければなりません。所有者、
   変更時刻、アクセス権限のようなディレクトリ情報はすべてのメンバーが
   抽出された後にセットされます。これは二つの問題を回避するためです。
   一つはディレクトリの変更時刻はその中にファイルが作成されるたびにリ
   セットされるということ、もう一つはディレクトリに書き込み許可がなけ
   ればその中のファイル抽出は失敗してしまうということです。

   警告: 内容を信頼できない tar アーカイブを、事前の内部チェック前に
     展開し てはいけません。ファイルが *path* の外側に作られる可能性が
     ありま す。例えば、""/"" で始まる絶対パスのファイル名や、2 重ドッ
     ト "".."" で始まるパスのファイル名です。

   バージョン 2.5 で追加.

TarFile.extract(member, path="")

   Extract a member from the archive to the current working directory,
   using its full name. Its file information is extracted as
   accurately as possible. *member* may be a filename or a "TarInfo"
   object. You can specify a different directory using *path*.

   注釈: "extract()" メソッドはいくつかの展開に関する問題を扱いませ
     ん。ほ とんどの場合、"extractall()" メソッドの利用を考慮するべき
     です。

   警告: "extractall()" の警告を参してください。

TarFile.extractfile(member)

   Extract a member from the archive as a file object. *member* may be
   a filename or a "TarInfo" object. If *member* is a regular file, a
   file-like object is returned. If *member* is a link, a file-like
   object is constructed from the link’s target. If *member* is none
   of the above, "None" is returned.

   注釈: The file-like object is read-only.  It provides the methods
     "read()", "readline()", "readlines()", "seek()", "tell()", and
     "close()", and also supports iteration over its lines.

TarFile.add(name, arcname=None, recursive=True, exclude=None, filter=None)

   Add the file *name* to the archive. *name* may be any type of file
   (directory, fifo, symbolic link, etc.). If given, *arcname*
   specifies an alternative name for the file in the archive.
   Directories are added recursively by default. This can be avoided
   by setting *recursive* to "False". If *exclude* is given it must be
   a function that takes one filename argument and returns a boolean
   value. Depending on this value the respective file is either
   excluded ("True") or added ("False"). If *filter* is specified it
   must be a function that takes a "TarInfo" object argument and
   returns the changed "TarInfo" object. If it instead returns "None"
   the "TarInfo" object will be excluded from the archive. See 使用例
   for an example.

   バージョン 2.6 で変更: Added the *exclude* parameter.

   バージョン 2.7 で変更: *filter* パラメータが追加されました。

   バージョン 2.7 で撤廃: The *exclude* parameter is deprecated,
   please use the *filter* parameter instead.  For maximum
   portability, *filter* should be used as a keyword argument rather
   than as a positional argument so that code won’t be affected when
   *exclude* is ultimately removed.

TarFile.addfile(tarinfo, fileobj=None)

   Add the "TarInfo" object *tarinfo* to the archive. If *fileobj* is
   given, "tarinfo.size" bytes are read from it and added to the
   archive.  You can create "TarInfo" objects directly, or by using
   "gettarinfo()".

   注釈: On Windows platforms, *fileobj* should always be opened
     with mode "'rb'" to avoid irritation about the file size.

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

   Create a "TarInfo" object from the result of "os.stat()" or
   equivalent on an existing file.  The file is either named by
   *name*, or specified as a file object *fileobj* with a file
   descriptor.  If given, *arcname* specifies an alternative name for
   the file in the archive, otherwise, the name is taken from
   *fileobj*’s "name" attribute, or the *name* argument.

   "TarInfo" の属性の一部は、"addfile()" を使用して追加する前に修正で
   きます。ファイルオブジェクトが、ファイルの先頭にある通常のファイル
   オブジェクトでない場合、 "size" などの属性は修正が必要かもしれませ
   ん。これは、 "GzipFile" などの属性に当てはまります。"name" も修正で
   きるかもしれず、この場合、*arcname* はダミーの文字列にすることがで
   きます。

TarFile.close()

   "TarFile" をクローズします。書き込みモードでは、完了ゼロブロックが
   2 個アーカイブに追加されます。

TarFile.posix

   Setting this to "True" is equivalent to setting the "format"
   attribute to "USTAR_FORMAT", "False" is equivalent to "GNU_FORMAT".

   バージョン 2.4 で変更: *posix* defaults to "False".

   バージョン 2.6 で撤廃: Use the "format" attribute instead.

TarFile.pax_headers

   pax グローバルヘッダーに含まれる key-value ペアの辞書です。

   バージョン 2.6 で追加.


TarInfo オブジェクト
====================

"TarInfo" オブジェクトは "TarFile" の一つのメンバーを表します。ファイ
ルに必要なすべての属性 (ファイルタイプ、ファイルサイズ、時刻、アクセス
権限、所有者等のような) を保存する他に、そのタイプを決定するのに役に立
ついくつかのメソッドを提供します。これにはファイルのデータそのものは *
含まれません* 。

"TarInfo" オブジェクトは "TarFile" のメソッド "getmember()"、
"getmembers()" および "gettarinfo()" によって返されます。

class tarfile.TarInfo(name="")

   "TarInfo" オブジェクトを作成します。

TarInfo.frombuf(buf)

   "TarInfo" オブジェクトを文字列バッファー *buf* から作成して返します
   。

   バージョン 2.6 で追加: Raises "HeaderError" if the buffer is
   invalid..

TarInfo.fromtarfile(tarfile)

   "TarFile" オブジェクトの *tarfile* から、次のメンバーを読み込んで、
   それを "TarInfo" オブジェクトとして返します。

   バージョン 2.6 で追加.

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='strict')

   "TarInfo" オブジェクトから文字列バッファーを作成します。引数につい
   ての情報は、"TarFile" クラスのコンストラクターを参照してください。

   バージョン 2.6 で変更: The arguments were added.

"TarInfo" オブジェクトには以下のデータ属性があります:

TarInfo.name

   アーカイブメンバーの名前。

TarInfo.size

   バイト単位でのサイズ。

TarInfo.mtime

   最後に変更された時刻。

TarInfo.mode

   許可ビット。

TarInfo.type

   ファイルタイプ。*type* は通常、定数 "REGTYPE"、"AREGTYPE"、
   "LNKTYPE"、"SYMTYPE"、"DIRTYPE"、"FIFOTYPE"、"CONTTYPE"、"CHRTYPE"
   、"BLKTYPE"、あるいは "GNUTYPE_SPARSE" のいずれかです。"TarInfo" オ
   ブジェクトのタイプをもっと簡単に解決するには、下記の "is*()" メソッ
   ドを使って下さい。

TarInfo.linkname

   リンク先ファイルの名前。これはタイプ "LNKTYPE" と "SYMTYPE" の
   "TarInfo" オブジェクトにだけ存在します。

TarInfo.uid

   ファイルメンバーを保存した元のユーザーのユーザー ID。

TarInfo.gid

   ファイルメンバーを保存した元のユーザーのグループ ID。

TarInfo.uname

   ファイルメンバーを保存した元のユーザーのユーザー名。

TarInfo.gname

   ファイルメンバーを保存した元のユーザーのグループ名。

TarInfo.pax_headers

   pax 拡張ヘッダーに関連付けられた、key-value ペアの辞書。

   バージョン 2.6 で追加.

"TarInfo" オブジェクトは便利な照会用のメソッドもいくつか提供しています
:

TarInfo.isfile()

   "Tarinfo" オブジェクトが一般ファイルの場合に、"True" を返します。

TarInfo.isreg()

   "isfile()" と同じです。

TarInfo.isdir()

   ディレクトリの場合に "True" を返します。

TarInfo.issym()

   シンボリックリンクの場合に "True" を返します。

TarInfo.islnk()

   ハードリンクの場合に "True" を返します。

TarInfo.ischr()

   キャラクターデバイスの場合に "True" を返します。

TarInfo.isblk()

   ブロックデバイスの場合に "True" を返します。

TarInfo.isfifo()

   FIFO の場合に "True" を返します。

TarInfo.isdev()

   キャラクターデバイス、ブロックデバイスあるいは FIFO のいずれかの場
   合に "True" を返します。


使用例
======

tar アーカイブから現在のディレクトリにすべて抽出する方法:

   import tarfile
   tar = tarfile.open("sample.tar.gz")
   tar.extractall()
   tar.close()

tar アーカイブの一部を、リストの代わりにジェネレーター関数を利用して
"TarFile.extractall()" で展開する方法:

   import os
   import tarfile

   def py_files(members):
       for tarinfo in members:
           if os.path.splitext(tarinfo.name)[1] == ".py":
               yield tarinfo

   tar = tarfile.open("sample.tar.gz")
   tar.extractall(members=py_files(tar))
   tar.close()

非圧縮 tar アーカイブをファイル名のリストから作成する方法:

   import tarfile
   tar = tarfile.open("sample.tar", "w")
   for name in ["foo", "bar", "quux"]:
       tar.add(name)
   tar.close()

"with" 文を利用した同じ例:

   import tarfile
   with tarfile.open("sample.tar", "w") as tar:
       for name in ["foo", "bar", "quux"]:
           tar.add(name)

gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法
:

   import tarfile
   tar = tarfile.open("sample.tar.gz", "r:gz")
   for tarinfo in tar:
       print tarinfo.name, "is", tarinfo.size, "bytes in size and is",
       if tarinfo.isreg():
           print "a regular file."
       elif tarinfo.isdir():
           print "a directory."
       else:
           print "something else."
   tar.close()

"TarFile.add()" 関数の *filter* 引数を利用してユーザー情報をリセットし
ながらアーカイブを作成する方法:

   import tarfile
   def reset(tarinfo):
       tarinfo.uid = tarinfo.gid = 0
       tarinfo.uname = tarinfo.gname = "root"
       return tarinfo
   tar = tarfile.open("sample.tar.gz", "w:gz")
   tar.add("foo", filter=reset)
   tar.close()


サポートしている tar フォーマット
=================================

"tarfile" モジュールは 3 種類の tar フォーマットを作成することができま
す:

* The POSIX.1-1988 ustar format ("USTAR_FORMAT"). It supports
  filenames up to a length of at best 256 characters and linknames up
  to 100 characters. The maximum file size is 8 gigabytes. This is an
  old and limited but widely supported format.

* The GNU tar format ("GNU_FORMAT"). It supports long filenames and
  linknames, files bigger than 8 gigabytes and sparse files. It is the
  de facto standard on GNU/Linux systems. "tarfile" fully supports the
  GNU tar extensions for long names, sparse file support is read-only.

* POSIX.1-2001 pax フォーマット ("PAX_FORMAT")。最も柔軟性があり、ほ
  ぼ 制限が無いフォーマットです。長いファイル名やリンク名、大きいファ
  イル をサポートし、パス名をポータブルな方法で保存します。しかし、現
  在のと ころ、すべての tar の実装が pax フォーマットを正しく扱えるわ
  けではあ りません。

  *pax* フォーマットは既存の *ustar* フォーマットの拡張です。*ustar*
  では保存できない情報を追加のヘッダーを利用して保存します。*pax* には
  2 種類のヘッダーがあります。1 つ目は拡張ヘッダーで、その次のファイル
  ヘッダーに影響します。2 つ目はグローバルヘッダーで、アーカイブ全体に
  対して有効で、それ以降のすべてのファイルに影響します。すべての pax
  ヘッダーの内容は、ポータブル性のために *UTF-8* で保存されます。

他にも、読み込みのみサポートしている tar フォーマットがいくつかありま
す:

* ancient V7 フォーマット。これは Unix 7th Edition から存在する、最
  初 の tar フォーマットです。通常のファイルとディレクトリのみ保存しま
  す 。名前は 100 文字を超えてはならず、ユーザー/グループ名に関する情
  報は 保存されません。いくつかのアーカイブは、フィールドが ASCII でな
  い文 字を含む場合に、ヘッダーのチェックサムの計算を誤ります。

* SunOS tar 拡張フォーマット。POSIX.1-2001 pax フォーマットの亜流で
  す が、互換性がありません。


Unicode に関する問題
====================

The tar format was originally conceived to make backups on tape drives
with the main focus on preserving file system information. Nowadays
tar archives are commonly used for file distribution and exchanging
archives over networks. One problem of the original format (that all
other formats are merely variants of) is that there is no concept of
supporting different character encodings. For example, an ordinary tar
archive created on a *UTF-8* system cannot be read correctly on a
*Latin-1* system if it contains non-ASCII characters. Names (i.e.
filenames, linknames, user/group names) containing these characters
will appear damaged.  Unfortunately, there is no way to autodetect the
encoding of an archive.

The pax format was designed to solve this problem. It stores non-ASCII
names using the universal character encoding *UTF-8*. When a pax
archive is read, these *UTF-8* names are converted to the encoding of
the local file system.

The details of unicode conversion are controlled by the *encoding* and
*errors* keyword arguments of the "TarFile" class.

The default value for *encoding* is the local character encoding. It
is deduced from "sys.getfilesystemencoding()" and
"sys.getdefaultencoding()". In read mode, *encoding* is used
exclusively to convert unicode names from a pax archive to strings in
the local character encoding. In write mode, the use of *encoding*
depends on the chosen archive format. In case of "PAX_FORMAT", input
names that contain non-ASCII characters need to be decoded before
being stored as *UTF-8* strings. The other formats do not make use of
*encoding* unless unicode objects are used as input names. These are
converted to 8-bit character strings before they are added to the
archive.

The *errors* argument defines how characters are treated that cannot
be converted to or from *encoding*. Possible values are listed in
section Codec 基底クラス. In read mode, there is an additional scheme
"'utf-8'" which means that bad characters are replaced by their
*UTF-8* representation. This is the default scheme. In write mode the
default value for *errors* is "'strict'" to ensure that name
information is not altered unnoticed.
