##
4 ファイルとディレクトリ

`access`( | path, mode)

  実 uid/gid を使って path に対するアクセスが可能か調べます。 ほとんどのオペレーティングシステムは実行 uid/gid を使うため、 このルーチンは suid/sgid 環境において、プログラムを起動した ユーザが path に対するアクセス権をもっているかを調べる ために使われます。path が存在するかどうかを調べるには mode を `F_OK` にします。ファイル操作許可 (permission) を調べるために `R_OK`、 `W_OK`、`X_OK` から一つまたはそれ以上のフラグと OR をとることもできます。 アクセスが許可されている場合 `True` を、そうでない場合 `False` を返します。詳細は access(2) のマニュアルページを参照して ください。 利用できる環境: Macintosh、 Unix、 Windows

  注意: `access()` を使ってユーザーが例えばファイルを開く権限を持っているか `open()` を使って実際にそうする前に調べることはセキュリティ・ホールを 作り出してしまいます。というのは、調べる時点と開く時点の時間差を利用して そのユーザーがファイルを操作してしまうかもしれないからです。

  注意: I/O 操作は `access()` が成功を思わせるときにも失敗することがありえます。 特にネットワーク・ファイルシステムにおける操作が 通常の POSIX 許可ビット・モデルをはみ出す意味論を備える場合には そのようなことが起こりえます。

`F_OK`
  `access()` の mode に渡すための値で、 path が存在するかどうかを調べます。

`R_OK`
  `access()` の mode に渡すための値で、 path が読み出し可能かどうかを調べます。

`W_OK`
  `access()` の mode に渡すための値で、 path が書き込み可能かどうかを調べます。

`X_OK`
  `access()` の mode に渡すための値で、 path が実行可能かどうかを調べます。

`chdir`( | path)

  現在の作業ディレクトリ (current working directory) を path に 設定します。利用できる環境: Macintosh、 Unix、Windows。

`getcwd`( | )

  現在の作業ディレクトリを表現する文字列を返します。 利用できる環境: Macintosh、 Unix、Windows。

`getcwdu`( | )

  現在の作業ディレクトリを表現するユニコードオブジェクトを返します。 利用できる環境: Macintosh、 Unix、 Windows バージョン 2.3 で 新たに追加 された仕様です。

`chroot`( | path)

  現在のプロセスに対してルートディレクトリを path に変更します。 利用できる環境: Macintosh、Unix。 バージョン 2.2 で 新たに追加 された仕様です。

`chmod`( | path, mode)

  path のモードを数値 mode に変更します。 mode は、(`stat` モジュールで定義されている) 以下の値のいずれかまたはビット単位の OR で組み合わせた値を取り得ます:
  - `S_ISUID`
  - `S_ISGID`
  - `S_ENFMT`
  - `S_ISVTX`
  - `S_IREAD`
  - `S_IWRITE`
  - `S_IEXEC`
  - `S_IRWXU`
  - `S_IRUSR`
  - `S_IWUSR`
  - `S_IXUSR`
  - `S_IRWXG`
  - `S_IRGRP`
  - `S_IWGRP`
  - `S_IXGRP`
  - `S_IRWXO`
  - `S_IROTH`
  - `S_IWOTH`
  - `S_IXOTH`
  利用できる環境: Macintosh、 Unix、 Windows。

  注意: Windows でも `chmod()` はサポートされていますが、 ファイルの読み込み専用フラグを (定数 `S_IWRITE` と `S_IREAD`、または対応する整数値を通して) 設定できるだけです。 他のビットは全て無視されます。

`chown`( | path, uid, gid)

  path の所有者 (owner) id とグループ id を、数値 uid および gid に変更します。いずれかの id を変更せずにおくには、 その値として -1 をセットします。 利用できる環境: Macintosh、 Unix。

`lchown`( | path, uid, gid)

  Change the owner and group id of path to the numeric uid and gid. This function will not follow symbolic links. path の所有者 (owner) id とグループ id を、数値 uid および gid に変更します。この関数はシンボリックリンクをたどりません。 利用できる環境: Macintosh、 Unix。 バージョン 2.3 で 新たに追加 された仕様です。

`link`( | src, dst)

  src を指しているハードリンク dst を作成します。 利用できる環境: Macintosh、 Unix。

`listdir`( | path)

  ディレクトリ内のエントリ名が入ったリストを返します。 リスト内の順番は不定です。特殊エントリ `'.'` および `'..'` は、それらがディレクトリに入っていてもリストには含められません。 利用できる環境: Macintosh、 Unix、 Windows。

  バージョン 2.3 で 変更 された仕様: Windows NT/2k/XP と Unixでは、path が Unicode オ ブジェクトの場合、Unicode オブジェクトのリストが返されます。

`lstat`( | path)

  `stat()` に似ていますが、シンボリックリンクをたどりません。 利用できる環境: Macintosh、 Unix。

`mkfifo`( | path[, mode])

  数値で指定されたモード mode を持つ FIFO (名前付きパイプ) を path に作成します。mode の標準の値は `0666` (8進) です。現在の umask 値が前もって mode からマスクされます。 利用できる環境: Macintosh、 Unix。

  FIFO は通常のファイルのようにアクセスできるパイプです。FIFO は (例えば `os.unlink()` を使って) 削除されるまで 存在しつづけます。一般的に、FIFO は ``クライアント'' と ``サーバ'' 形式のプロセス間でランデブーを行うために使われます: このとき、 サーバは FIFO を読み出し用に開き、クライアントは書き込み用に 開きます。`mkfifo()` は FIFO を開かない -- 単にランデブー ポイントを作成するだけ -- なので注意してください。

`mknod`( | filename[, mode=0600, device])

  filename という名前で、ファイルシステム・ノード (ファイル、デバイス特殊 ファイル、または、名前つきパイプ) を作ります 。mode は、作ろうとす るノードの使用権限とタイプを、S_IFREG、S_IFCHR、S_IFBLK、S_IFIFO (これら の定数は `stat` で使用可能) のいずれかと（ビット OR で）組み合わ せて指定します。S_IFCHR と S_IFBLK を指定すると、device は新しく作 られたデバイス特殊ファイルを (おそらく `os.makedev()` を使って) 定義し、指定しなかった場合には無視します。 バージョン 2.3 で 新たに追加 された仕様です。

`major`( | device)

  生のデバイス番号から、デバイスのメジャー番号を取り出します。(たいてい `stat` の `st_dev` フィールドか `st_rdev`フィールドです) バージョン 2.3 で 新たに追加 された仕様です。

`minor`( | device)

  生のデバイス番号から、デバイスのマイナー番号を取り出します。(たいてい `stat` の `st_dev` フィールドか `st_rdev`フィールドです) バージョン 2.3 で 新たに追加 された仕様です。

`makedev`( | major, minor)

  major と minor から、新しく生のデバイス番号を作ります。 バージョン 2.3 で 新たに追加 された仕様です。

`mkdir`( | path[, mode])

  数値で指定されたモード mode をもつディレクトリ path を作成します。mode の標準の値は `0777` (8進)です。 システムによっては、 mode は無視されます。利用の際には、 現在の umask 値が前もってマスクされます。 利用できる環境: Macintosh、 Unix、Windows。

`makedirs`( | path[, mode])

  再帰的なディレクトリ作成関数です。 `mkdir()` に似て いますが、末端 (leaf) となるディレクトリを作成するために必要な 中間の全てのディレクトリを作成します。末端ディレクトリが すでに存在する場合や、作成ができなかった場合には `error` 例外を送出します。mode の標準の値は `0777` (8進)です。 システムによっては、 mode は無視されます。利用の際には、 現在の umask 値が前もってマスクされます。 注意: `makedirs()` は作り出すパス要素が os.pardir を 含むと混乱することになります。 バージョン 1.5.2 で 新たに追加 された仕様です。 バージョン 2.3 で 変更 された仕様: この関数は UNC パスを正しく扱えるようになりました

`pathconf`( | path, name)

  指定されたファイルに関係するシステム設定情報を返します。 varname には取得したい設定名を指定します; これは定義済みのシステム固有値名の文字列で、多くの標準 (POSIX.1、 Unix 95、 Unix 98 その他) で定義されています。 プラットフォームによっては別の名前も定義しています。 ホストオペレーティングシステムの関知する名前は `pathconf_names` 辞書で与えられています。このマップ型オブジェクトに入っていない設定 変数については、 name に整数を渡してもかまいません。 利用できる環境: Macintosh、Unix

  もし name が文字列でかつ不明である場合、 `ValueError` を送出します。name の指定値がホストシステムでサポートされておらず、 `pathconf_names` にも入っていない場合、`errno.EINVAL` をエラー番号として `OSError` を送出します。

`pathconf_names`
  `pathconf()` および `fpathconf()` が受理する システム設定名を、ホストオペレーティングシステムで定義されている 整数値に対応付けている辞書です。この辞書はシステムでどの 設定名が定義されているかを決定するために利用できます。 利用できる環境: Macintosh、 Unix。

`readlink`( | path)

  シンボリックリンクが指しているパスを表す文字列を返します。 返される値は絶対パスにも、相対パスにもなり得ます; 相対 パスの場合、 `os.path.join(os.path.dirname(path), result)` を使って絶対パスに変換することができます。 利用できる環境: Macintosh、 Unix。

`remove`( | path)

  ファイル path を削除します。path がディレクトリの 場合、`OSError` が送出されます; ディレクトリの削除については `rmdir()` を参照してください。この関数は下で述べられている `unlink()` 関数と同一です。Windows では、使用中のファイル を削除しようと試みると例外を送出します; Unixでは、ディレクトリ エントリは削除されますが、記憶装置上にアロケーションされたファイル領域は 元のファイルが使われなくなるまで残されます。 利用できる環境: Macintosh、 Unix、Windows。

`removedirs`( | path)

  再帰的なディレクトリ削除関数です。`rmdir()` と同じように 動作しますが、末端ディレクトリがうまく削除できるかぎり、 `removedirs()` は path に現れる親ディレクトリをエラー が送出されるまで (このエラーは通常、 指定したディレクトリの親ディレクトリが空でないことを意味するだけ なので無視されます) 順に削除することを試みます。 例えば、"`os.removedirs('foo/bar/baz')`" では最初にディレクトリ "`'foo/bar/baz'`" を削除し、次に "`'foo/bar'`"、さらに "`'foo'`" をそれらが空ならば削除します。 末端のディレクトリが削除できなかった場合には `OSError` が送出されます。 バージョン 1.5.2 で 新たに追加 された仕様です。

`rename`( | src, dst)

  ファイルまたはディレクトリ src を dst に名前変更します。 dst がディレクトリの場合、`OSError` が送出 されます。 Unixでは、 dst が存在し、かつファイルの場合、 ユーザの権限があるかぎり暗黙のうちに元のファイルが削除されます。 この操作はいくつかの Unix 系において、src と dst が異なるファイルシステム上にあると失敗することがあります。 ファイル名の変更が成功する場合、この操作は原子的 (atomic) 操作 となります (これは POSIX 要求仕様です) Windows では、 dst が既に存在する場合には、たとえファイルの場合でも `OSError` が送出されます; これは dst が既に 存在するファイル名の場合、名前変更の原子的操作を実装する手段が ないからです。 利用できる環境: Macintosh、 Unix、Windows。

`renames`( | old, new)

  再帰的にディレクトリやファイル名を変更する関数です。 `rename()` のように動作しますが、新たなパス名を持つ ファイルを配置するために必要な途中のディレクトリ構造をまず作成 しようと試みます。 名前変更の後、元のファイル名のパス要素は `removedirs()` を使って右側から順に枝刈りされてゆきます。 バージョン 1.5.2 で 新たに追加 された仕様です。

  注意: この関数はコピー元の末端のディレクトリまたはファイルを削除する 権限がない場合には失敗します。

`rmdir`( | path)

  ディレクトリ path を削除します。 利用できる環境: Macintosh、 Unix、Windows。

`stat`( | path)

  与えられた path に対して `stat()` システムコールを 実行します。戻り値はオブジェクトで、その属性が `stat` 構造体の 以下に挙げる各メンバ: `st_mode` (保護モードビット)、 `st_ino` (i ノード番号)、 `st_dev` (デバイス)、 `st_nlink` (ハードリンク数)、 `st_uid` (所有者のユーザ ID)、 `st_gid` (所有者のグループ ID)、 `st_size` (ファイルのバイトサイズ)、 `st_atime` (最終アクセス時刻)、 `st_mtime` (最終更新時刻)、 `st_ctime` (プラットフォーム依存：Unixでは最終メタデータ変更時刻、 Windowsでは作成時刻) となっています。

      >>> import os
      >>> statinfo = os.stat('somefile.txt')
      >>> statinfo
      (33188, 422511L, 769L, 1, 1032, 100, 926L, 1105022698,1105022732, 1105022732)
      >>> statinfo.st_size
      926L
      >>>

  バージョン 2.3 で 変更 された仕様: もし `stat_float_times` が真を返す場合、時間値は浮動小数点で秒を計ります。ファイルシステムがサポートしていれば、秒の小数点以下の桁も含めて返されます。 Mac OS では、時間は常に浮動小数点です。詳細な説明は `stat_float_times` を参照してください

  (Linux のような) Unix システムでは、以下の属性: `st_blocks` (ファイル用にアロケーションされているブロック数)、 `st_blksize` (ファイルシステムのブロックサイズ)、 `st_rdev` (i ノードデバイスの場合、デバイスの形式)、 `st_flags` (ファイルに対するユーザー定義のフラグ) も利用可能なときがあります。

  他の (FreeBSD のような) Unix システムでは、以下の属性: `st_gen` (ファイル生成番号)、 `st_birthtime` (ファイル生成時刻) も利用可能なときがあります (ただし root がそれらを使うことにした場合以外は値が入っていないでしょう)。

  Mac OS システムでは、以下の属性: `st_rsize`、 `st_creator`、 `st_type`、 も利用可能なときがあります。

  RISCOS システムでは、以下の属性: `st_ftype` (file type)、 `st_attrs` (attributes)、 `st_obtype` (object type)、 も利用可能なときがあります。

  後方互換性のために、`stat()` の戻り値は少なくとも 10 個の 整数からなるタプルとしてアクセスすることができます。このタプルは もっとも重要な (かつ可搬性のある) `stat` 構造体のメンバを 与えており、以下の順番、 `st_mode`、 `st_ino`、 `st_dev`、 `st_nlink`、 `st_uid`、 `st_gid`、 `st_size`、 `st_atime`、 `st_mtime`、 `st_ctime`、 に並んでいます。

  実装によっては、この後ろにさらに値が付け加えられていることもあります。 Mac OS では、時刻の値は Mac OS の他の時刻表現値と同じように浮動小数点数 なので注意してください。 標準モジュール `stat` では、 `stat` 構造体から情報を引き出す上で便利な関数や定数を定義して います。(Windows では、いくつかのデータ要素はダミーの値が埋められて います。)

  注意: `st_atime`, `st_mtime`, および `st_ctime` メンバの厳密な意味や精度はオペレーティングシステムやファイルシステムによって 変わります。例えば、FAT や FAT32 ファイルシステムを使っているWindows システム では、`st_atime` の精度は 1 日に過ぎません。詳しくはお使いのオペレーティング システムのドキュメントを参照してください。

  利用できる環境: Macintosh、 Unix、Windows。

  バージョン 2.2 で 変更 された仕様: 返されたオブジェクトの属性としてのアクセス機能を追加しました バージョン 2.5 で 変更 された仕様: st_gen、 st_birthtime を追加しました

`stat_float_times`( | [newvalue])

  `stat_result` がタイムスタンプに浮動小数点オブジェクトを使うかどう かを決定します。newvalue が `True` の場合、 以後の `stat()` 呼び出しは浮動小数点を返し、 `False` の場合には以後整数を返します。newvalue が省略された場合、現在の設 定どおりの戻り値になります。

  古いバージョンの Python と互換性を保つため、`stat_result` にタプル としてアクセスすると、常に整数が返されます。

  バージョン 2.5 で 変更 された仕様: Python はデフォルトで浮動小数点数を返すようになりました。 浮動小数点数のタイムスタンプではうまく動かないアプリケーションはこの機能を利用して 昔ながらの振る舞いを取り戻すことができます。

  タイムスタンプの精度 (すなわち最小の小数部分) はシステム依存です。 システムによっては秒単位の精度しかサポートしません。 そういったシステムでは小数部分は常に 0 です。

  この設定の変更は、プログラムの起動時に、 __main__ モジュールの中でのみ行うことを推奨します。 ライブラリは決して、この設定を変更するべきではありません。 浮動小数点型のタイムスタンプを処理すると、不正確な動作をするようなライブ ラリを使う場合、ライブラリが修正されるまで、浮動小数点型を返す機能を停止 させておくべきです。

`statvfs`( | path)

  与えられた path に対して `statvfs()` システムコールを 実行します。戻り値はオブジェクトで、その属性は与えられたパスが収め られているファイルシステムについて記述したものです。かく属性は `statvfs` 構造体のメンバ: `f_bsize`、 `f_frsize`、 `f_blocks`、 `f_bfree`、 `f_bavail`、 `f_files`、 `f_ffree`、 `f_favail`、 `f_flag`、 `f_namemax`、 に対応します。 利用できる環境: Unix。

  後方互換性のために、戻り値は上の順にそれぞれ対応する属性値が並んだ タプルとしてアクセスすることもできます。 標準モジュール `statvfs` では、 シーケンスとしてアクセスする場合に、`statvfs` 構造体から情報を 引き出す上便利な関数や定数を定義しています; これは 属性として各フィールドにアクセスできないバージョンの Python で 動作する必要のあるコードを書く際に便利です。 バージョン 2.2 で 変更 された仕様: 返されたオブジェクトの属性としてのアクセス機能を追加しました

`symlink`( | src, dst)

  src を指しているシンボリックリンクを dst に作成します。 利用できる環境: Unix。

`tempnam`( | [dir[, prefix]])

  一時ファイル (temporary file) を生成する上でファイル名として相応しい 一意なパス名を返します。この値は一時的なディレクトリエントリ を表す絶対パスで、dir ディレクトリの下か、dir が省略 されたり `None` の場合には一時ファイルを置くための共通の ディレクトリの下になります。prefix が与えられており、かつ `None` でない場合、ファイル名の先頭につけられる短い 接頭辞になります。アプリケーションは `tempnam()` が返したパス名を使って正しくファイルを生成し、生成したファイルを 管理する責任があります; 一時ファイルの自動消去機能は提供されて いません。 警告: `tempnam()` を使うと、symlink 攻撃に対して脆弱 になります; 代りに`tmpfile()` (第14.1.2節) を使うよう検討してください。 利用できる環境: Macintosh、 Unix、 Windows。

`tmpnam`( | )

  一時ファイル (temporary file) を生成する上でファイル名として相応しい 一意なパス名を返します。この値は一時ファイルを置くための共通の ディレクトリ下の一時的なディレクトリエントリを表す絶対パスです。 アプリケーションは `tmpnam()` が返したパス名を使って正しくファイルを生成し、生成したファイルを 管理する責任があります; 一時ファイルの自動消去機能は提供されて いません。

  警告: `tmpnam()` を使うと、symlink 攻撃に対して脆弱 になります; 代りに`tmpfile()` (第14.1.2節) を使うよう検討してください。 利用できる環境: Unix、Windows。 この関数はおそらく Windows では使うべきではないでしょう; Micorosoft の `tmpnam()` 実装では、常に現在のドライブの ルートディレクトリ下のファイル名を生成しますが、これは一般的には テンポラリファイルを置く場所としてはひどい場所です (アクセス権限によっては、この名前をつかってファイルを開くことすら できないかもしれません)。

`TMP_MAX`
  `tmpnam()` がテンポラリ名を再利用し始めるまでに生成できる 一意な名前の最大数です。

`unlink`( | path)

  ファイル path を削除します。`remove()` と同じです; `unlink()` の名前は伝統的な Unix の関数名です。 利用できる環境: Macintosh、 Unix、Windows。

`utime`( | path, times)

  path で指定されたファイルに最終アクセス時刻および最終修正時刻 を設定します。times が `None` の場合、ファイルの最終 アクセス時刻および最終更新時刻は現在の時刻になります。そうでない 場合、 times は 2 要素のタプルで、`(atime, mtime)` の形式をとらなくてはなりません。これらはそれぞれアクセス時刻および修正時刻 を設定するために使われます。 path にディレクトリを指定できるかどうかは、オペレーティングシステム がディレクトリをファイルの一種として実装しているかどうかに依存します (例えば、 Windows はそうではありません)。ここで設定した時刻の値は、オペレーティング システムがアクセス時刻や更新時刻を記録する際の精度によっては、後で`stat()` 呼び出したときの値と同じにならないかも知れないので注意してください。 `stat()` も参照してください。 バージョン 2.0 で 変更 された仕様: times として `None` をサポートするように しました 利用できる環境: Macintosh、 Unix、Windows。

`walk`( | top[, topdown`=True` [, onerror`=None`]])

  `walk()` は、ディレクトリツリー以下のファイル名を、ツリーを トップダウンとボトムアップの両方向に歩行することで生成します。 ディレクトリ top を根に持つディレクトリツリーに含まれる、 各ディレクトリ(top 自身を含む) から、タプル `(dirpath, dirnames, filenames)` を生成します。

  dirpath は文字列で、ディレクトリへのパスです。dirnames は dirpath 内のサブディレクトリ名のリスト (`'.'` と `'..'` は除く）です。filenames は dirpath 内の非ディレクトリ・ファ イル名のリストです。このリスト内の名前には、ファイル名までのパスが含まれ ないことに、注意してください。dirpath 内のファイルやディレクトリへ の (top からたどった) フルパスを得るには、 `os.path.join(dirpath, name)` してください。

  オプション引数 topdown が真であるか、指定されなかった場合、各ディ レクトリからタプルを生成した後で、サブディレクトリからタプルを生成します。 (ディレクトリはトップダウンで生成)。topdown が偽の場合、ディレクト リに対応するタプルは、そのディレクトリ以下の全てのサブディレクトリに対応 するタプルの後で (ボトムアップで) 生成されます

  topdown が真のとき、呼び出し側は dirnames リストを、インプレ ースで (たとえば、`del` やスライスを使った代入で) 変更でき、 `walk()` はdirnames に残っているサブディレクトリ内のみを 再帰します。これにより、検索を省略したり、特定の訪問順序を強制したり、呼 び出し側が `walk()` を再開する前に、呼び出し側が作った、または 名前を変更したディレクトリを、`walk()` に知らせたりすることがで きます。topdown が偽のときに dirnames を変更しても効果はあり ません。ボトムアップモードでは dirpath 自身が生成される前に dirnames 内のディレクトリの情報が生成されるからです。

  デフォルトでは、`os.listdir()` 呼び出しから送出されたエラーは 無視されます。オプションの引数 onerror を指定するなら、 この値は関数でなければなりません; この関数は単一の引数として、 `OSError` インスタンスを伴って呼び出されます。この関数では エラーを報告して歩行を続けたり、例外を送出して歩行を中断したり できます。ファイル名は例外オブジェクトの `filename` 属性として 取得できることに注意してください。

  注意: 相対パスを渡した場合、`walk()` の回復の間でカレント作業ディレク トリを変更しないでください。`walk()` はカレントディレクトリを変 更しませんし、呼び出し側もカレントディレクトリを変更しないと仮定していま す。

  注意: シンボリックリンクをサポートするシステムでは、サブディレクトリへのリンク が dirnames リストに含まれますが、`walk()` はそのリンクを たどりません (シンボリックリンクをたどると、無限ループに陥りやすくなりま す)。リンクされたディレクトリをたどるには、 `os.path.islink(path)` でリンク先ディレクトリを確認し、各ディ レクトリに対して `walk(path)` を実行するとよいでしょう。

  以下の例では、最初のディレクトリ以下にある各ディレクトリに含まれる、非ディレクトリファイルのバイト数を表示します。ただし、CVS サブディレクトリより下を見に行きません。

      import os
      from os.path import join, getsize
      for root, dirs, files in os.walk('python/Lib/email'):
          print root, "consumes",
          print sum(getsize(join(root, name)) for name in files),
          print "bytes in", len(files), "non-directory files"
          if 'CVS' in dirs:
              dirs.remove('CVS')  # don't visit CVS directories

  次の例では、ツリーをボトムアップで歩行することが不可欠になります; `rmdir()` はディレクトリが空になる前に削除させないからです:

      # Delete everything reachable from the directory named in 'top',
      # assuming there are no symbolic links.
      # CAUTION:  This is dangerous!  For example, if top == '/', it
      # could delete all your disk files.
      import os
      for root, dirs, files in os.walk(top, topdown=False):
          for name in files:
              os.remove(os.path.join(root, name))
          for name in dirs:
              os.rmdir(os.path.join(root, name))

  バージョン 2.3 で 新たに追加 された仕様です。