##
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、Windows。

`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。

`chroot`( | path)

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

`chmod`( | path, mode)

  path のモードを数値 mode に変更します。 mode は、(`stat` モジュールで定義されている) 以下の値のいずれかを取り得ます:
  - `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`
  利用できる環境: Unix、Windows。

`chown`( | path, uid, gid)

  path の所有者 (owner) id とグループ id を、数値 uid および gid に変更します。 利用できる環境: Unix。

`link`( | src, dst)

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

`listdir`( | path)

  ディレクトリ内のエントリ名が入ったリストを返します。 リスト内の順番は不定です。特殊エントリ `'.'` および `'..'` は、それらがディレクトリに入っていてもリストには含められません。 バージョン 2.3 で 変更 された仕様: Windows NT/2k/XP と Unix では、path が Unicode オ ブジェクトの場合、Unicode オブジェクトのリストが返されます。 利用できる環境: Macintosh、 Unix、Windows。

`lstat`( | path)

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

`mkfifo`( | path[, mode])

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

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

`mknod`( | path[, 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)

  生のデバイス番号から、デバイスのメジャー番号を取り出します。 バージョン 2.3 で 新たに追加 された仕様です。

`minor`( | device)

  生のデバイス番号から、デバイスのマイナー番号を取り出します。 バージョン 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進)です。 (Windows システムにのみ関係することですが、Universal Naming Convention パスは、``\\host\path`' という書式のパスです） バージョン 1.5.2 で 新たに追加 された仕様です。

`pathconf`( | path, name)

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

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

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

`readlink`( | path)

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

`remove`( | path)

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

`removedirs`( | path)

  再帰的なディレクトリ削除関数です。`rmdir()` と同じように 動作しますが、末端ディレクトリがうまく削除できるかぎり、パスを 構成する要素の右端となるディレクトリを刈り込んでゆき、指定したパス 全体が削除されるかエラーが送出されるまで続けます (このエラーは通常、 指定したディレクトリの親ディレクトリが空でないことを意味するだけ なので無視されます)。末端のディレクトリがうまく削除できない 場合には `error` を送出します。 バージョン 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では作成時刻) となっています。

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

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

  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 で 変更 された仕様: 返されたオブジェクトの属性としてのアクセス機能を追加しました

`stat_float_times`( | [newvalue])

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

  古いバージョンの Python と互換性を保つため、`stat_result` にタプル としてアクセスすると、常に整数が返されます。また、Python 2.2 との互換性 のため、タイムスタンプにフィールド名を指定してアクセスすると、整数で返さ れす。タイムスタンプの秒を小数点以下の精度で求めたいアプリケーションは、 タイムスタンプを浮動小数点型にするために、この関数を使うことができます。 実際に、小数点以下の桁に 0 以外の数値が得られるかどうかは、システムに依 存します。

  将来リリースされる Python は、この設定のデフォルト値を変更するでしょう。 浮動小数点型のタイムスタンプを扱えないアプリケーションは、この関数を使っ て、その機能を停止させることができます。

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

`statvfs`( | path)

  与えられた path に対して `statvfs()` システムコールを 実行します。戻り値はオブジェクトで、その属性は与えられたパスが収め られているファイルシステムについて記述したものです。かく属性は `statvfs` 構造体のメンバ: `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()` を使うよう検討してください。 利用できる環境: Unix、Windows。

`tmpnam`( | )

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

  警告: `tmpnam()` を使うと、symlink 攻撃に対して脆弱 になります; 代りに`tmpfile()` を使うよう検討してください。 利用できる環境: 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 を変更しても効果はあり ません。ボトムアップモードでは dirnames 自身が生成される前に dirnames内のディレクトリの情報が生成されるからです。

  デフォルトでは、`os.listdir()` 呼び出しから送出されたエラーは 無視されます。オプションの引数 onerror を指定するなら、 この値は関数でなければなりません; この関数は単一の引数として、 os.error インスタンスを伴って呼び出されます。この関数では エラーを報告して歩行を続けたり、例外を送出して歩行を中断したり できます。ファイル名は例外オブジェクトの `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 で 新たに追加 された仕様です。