Node.js v0.8.23 マニュアル & ドキュメンテーション

Index | View on single page | View as JSON

File System

File System#

Stability: 3 - Stable

File I/O は POSIX 標準の関数に対する単純なラッパーとして提供されます。このモジュールを使用するには require('fs') してください。全てのメソッドは非同期と同期の形式があります。

非同期の形式は常に最後の引数として完了コールバックを受け取ります。引数として渡される完了コールバックはメソッドに依存しますが、最初の引数は常に例外のために予約されています。操作が成功で完了すると最初の引数は null または undefined となります

同期の形式では、全ての例外はすぐにスローされます。例外は try/catch で捕まえることも、そのまま通過させることもできます。

非同期バージョンの例です:

var fs = require('fs');

fs.unlink('/tmp/hello', function (err) {
  if (err) throw err;
  console.log('successfully deleted /tmp/hello');
});

同期バージョンです:

var fs = require('fs');

fs.unlinkSync('/tmp/hello')
console.log('successfully deleted /tmp/hello');

非同期メソッドでは順序の保証はありません。以下のような傾向のエラーがあります。

fs.rename('/tmp/hello', '/tmp/world', function (err) {
  if (err) throw err;
  console.log('renamed complete');
});
fs.stat('/tmp/world', function (err, stats) {
  if (err) throw err;
  console.log('stats: ' + JSON.stringify(stats));
});

fs.stat は fs.rename より先に実行される可能性がありrます。正しい方法はコールバックをチェーンすることです。

fs.rename('/tmp/hello', '/tmp/world', function (err) {
  if (err) throw err;
  fs.stat('/tmp/world', function (err, stats) {
    if (err) throw err;
    console.log('stats: ' + JSON.stringify(stats));
  });
});

忙しいプロセスでは、プログラマはこれらの非同期バージョンを使うことが強く推奨されます。同期バージョンはそれが完了するまでプロセス全体をブロックします－全ての接続を停止します。

ファイル名には相対パスを使うことが出来ます。しかし、このパスは process.cwd() からの相対パスであることを思い出してください。

fs.rename(oldPath, newPath, [callback])#

非同期の rename(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.renameSync(oldPath, newPath)#

同期の rename(2)。

fs.truncate(fd, len, [callback])#

非同期の ftruncate(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.truncateSync(fd, len)#

同期の ftruncate(2)。

fs.chown(path, uid, gid, [callback])#

非同期の chown(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.chownSync(path, uid, gid)#

同期の chown(2)。

fs.fchown(fd, uid, gid, [callback])#

非同期の fchown(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.fchownSync(fd, uid, gid)#

同期の fchown(2)。

fs.lchown(path, uid, gid, [callback])#

非同期の lchown(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.lchownSync(path, uid, gid)#

同期の lchown(2)。

fs.chmod(path, mode, [callback])#

非同期の chmod(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.chmodSync(path, mode)#

同期の chmod(2)。

fs.fchmod(fd, mode, [callback])#

非同期の fchmod(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.fchmodSync(fd, mode)#

同期の fchmod(2)。

fs.lchmod(path, mode, [callback])#

非同期の lchmod(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

Mac OS X でのみ利用可能です。

fs.lchmodSync(path, mode)#

同期の lchmod(2)。

fs.stat(path, [callback])#

非同期の stat(2)。コールバックは 2 つの引数を受け取る (err, stats)で、 stats は fs.Stats オブジェクトです。詳細は fs.Stats の節を参照してください。

より詳しくは後述の fs.Stats の節を参照してください。

fs.lstat(path, [callback])#

非同期の lstat(2)。コールバックは 2 つの引数を受け取る (err, stats)で、 stats は fs.Stats オブジェクトです。 lstat() はパスがシンボリックリンクだった場合に、参照先のファイルではなくそのリンク自身が調べられる点を除いて stat() と同じす。

fs.fstat(fd, [callback])#

非同期の fstat(2)。コールバックは 2 つの引数を受け取る (err, stats) で、 stats は fs.Stats オブジェクトです。状態を取得するファイルをファイル記述子 fd で指定することを除いて、 fstat() は stat() と同じです。

fs.statSync(path)#

同期の stat(2)。fs.Stats のインスタンスを返します。

fs.lstatSync(path)#

同期の lstat(2)。fs.Stats のインスタンスを返します。

fs.fstatSync(fd)#

同期の fstat(2)。fs.Stats のインスタンスを返します。

fs.link(srcpath, dstpath, [callback])#

非同期の link(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.linkSync(srcpath, dstpath)#

同期の link(2)。

fs.symlink(srcpath, dstpath, [type], [callback])#

非同期の symlink(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 type 引数は 'dir'、'file'、または 'junction' (デフォルトは 'file') です。これは Windows でのみ使われます (他のプラットフォームでは無視されます)。 Windows のジャンクションポイントは対象に絶対パスを要求することに注意してください。 'junction' を使うと、destination 引数は自動的に絶対パスに正規化されます。

fs.symlinkSync(srcpath, dstpath, [type])#

同期の symlink(2)。

fs.readlink(path, [callback])#

非同期の readlink(2)。コールバックは 2 つの引数を受け取る (err, linkString)です。

fs.readlinkSync(path)#

同期の readlink(2)。シンボリックリンクの持つ文字列値を返します。

fs.realpath(path, [cache], callback)#

非同期の realpath(2)。コールバックは 2 つの引数を受け取る (err, resolvedPath)です。相対パスを解決するために process.cwd を使用することができます。 cache はオブジェクトで、パスがキーとして含まれていればその値が強制的に解決されたパスとして扱われ、fs.stat によってパスが実在するかどうかの確認が省かれます。

例:

var cache = {'/etc':'/private/etc'};
fs.realpath('/etc/passwd', cache, function (err, resolvedPath) {
  if (err) throw err;
  console.log(resolvedPath);
});

fs.realpathSync(path, [cache])#

同期の realpath(2)。解決されたパスを返します。

fs.unlink(path, [callback])#

非同期の unlink(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.unlinkSync(path)#

同期の unlink(2)。

fs.rmdir(path, [callback])#

非同期の rmdir(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.rmdirSync(path)#

同期の rmdir(2)。

fs.mkdir(path, [mode], [callback])#

非同期の mkdir(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。 mode のデフォルトは 0777 です。

fs.mkdirSync(path, [mode])#

同期の mkdir(2)。

fs.readdir(path, [callback])#

非同期の readdir(3)。ディレクトリの内容を読み込みます。コールバックは 2 つの引数を受け取る (err, files)で、 files は '.' と '..' を除くディレクトリ内のファイル名の配列です。

fs.readdirSync(path)#

同期の readdir(3)。'.' と '..' を除くディレクトリ内のファイル名の配列を返します。

fs.close(fd, [callback])#

非同期の close(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.closeSync(fd)#

同期の close(2)。

fs.open(path, flags, [mode], [callback])#

非同期のファイルオープン。open(2) を参照してください。フラグは以下になります:

'r' - ファイルを読み込み専用でオープンします。ファイルが存在しない場合は例外が発生します。
'r+' - ファイルを読み書き両用でオープンします。ファイルが存在しない場合は例外が発生します。
'rs' - ファイルを同期モードで読み込むためにオープンします。オペレーティングシステムにローカルファイルシステムのキャッシュをバイパスするように指示します。

これは主に NFS にマウントされたファイルをオープンして、潜在的に古いローカルキャッシュをスキップするのに役立ちます。これはI/O パフォーマンスにとても深刻な影響を与えるため、必要でない限り使用しないでください。

これは fs.open() を同期的なブロッキング呼び出しにするわけではないことに注意してください。それが必要な場合は fs.openSync() を使用すべきです。
'rs+' - ファイルを読み書き両方でオープンし、OS に同期的にオープンするように伝えます。これを使用する際の警告は 'rs' の注意を参照してください。
'w' - ファイルを書き込み専用でオープンします。ファイルは作成される (存在しない場合) または長さ 0 に切り詰められます (存在する場合)。
'wx' - 'w' と似ていますが、ファイルを排他モードでオープンします。
'w+' - ファイルを読み書き両用でオープンします。ファイルは作成される (存在しない場合) または長さ 0 に切り詰められます (存在する場合)。
'wx+' - 'w+' と似ていますが、ファイルを排他モードでオープンします。
'a' - ファイルを追記用でオープンします。ファイルが存在しない場合は作成されます。
'ax' - 'a' と似ていますが、ファイルを排他モードでオープンします。
'a+' - ファイルを読み込みおよび追記用でオープンします。ファイルが存在しない場合は作成されます。
'ax+' - 'a+' と似ていますが、ファイルを排他モードでオープンします。

mode のデフォルトは 0666 です。コールバックは 2 つの引数を受け取る (err, fd)です。

排他モード (O_EXCL) は、path が新しいファイルとして作成されることを確実にします。指定された名前のファイルが既に存在する場合、 fs.open() は失敗します。 POSIX システムでは、シンボリックリンクは辿られません。排他モードはネットワークファイルシステムでは動くかもしれませんし、動かないかもしれません。

fs.openSync(path, flags, [mode])#

同期の open(2)。

fs.utimes(path, atime, mtime, [callback])#

fs.utimesSync(path, atime, mtime)#

渡されたパスが参照するファイルのタイムスタンプを変更します。

fs.futimes(fd, atime, mtime, [callback])#

fs.futimesSync(fd, atime, mtime)#

渡されたファイル記述子が参照するファイルのタイムスタンプを変更します。

fs.fsync(fd, [callback])#

非同期の fsync(2)。完了コールバックには発生し得る例外以外に引数が渡されることはありません。

fs.fsyncSync(fd)#

同期の fsync(2)。

fs.write(fd, buffer, offset, length, position, [callback])#

fd で指定されたファイルに buffer を書き込みます。

offset と length は書き込まれるバッファの部分を決定します。

position はデータが書き込まれる位置をファイルの先頭からのオフセットで示します。 position が null の場合、データは現在の位置から書き込まれます。 pwrite(2) を参照してください。

コールバックは 3 つの引数が与えられる (err, written, buffer) で、 written は buffer から書き込まれたバイト数を示します。

同じファイルに対してコールバックされるのを待つことなく fs.write() を何度も呼び出すことは、安全ではないことに注意してください。このシナリオでは、 fs.createWriteStream() を強く推奨します。

fs.writeSync(fd, buffer, offset, length, position)#

同期版の fs.write()。書き込まれたバイト数を返します。

fs.read(fd, buffer, offset, length, position, [callback])#

fd で指定されたファイルからデータを読み込みます。

buffer はデータが書き込まれるバッファです。

offset は読み込みを開始するバッファ内のオフセットです。

length は読み込むバイト数を指定する整数です。

position はファイルの読み込みを開始する位置を指定する整数です。 position が null の場合、データは現在の位置から読み込まれます。

コールバックは3つの引数が与えられる (err, bytesRead, buffer) です。

fs.readSync(fd, buffer, offset, length, position)#

同期版の fs.read。bytesRead の数を返します。

fs.readFile(filename, [encoding], [callback])#

ファイル全体の内容を非同期に読み込みます。例:

fs.readFile('/etc/passwd', function (err, data) {
  if (err) throw err;
  console.log(data);
});

コールバックは 2 つの引数が渡される (err, data) で、data はファイルの内容です。

エンコーディングが指定されなければ、生のバッファが渡されます。

fs.readFileSync(filename, [encoding])#

同期版の fs.readFile。filename の内容を返します。

encoding が指定されるとこの関数は文字列を返します。そうでなければバッファを返します。

fs.writeFile(filename, data, [encoding], [callback])#

非同期にデータをファイルに書き込みます。ファイルが既に存在する場合は置き換えられます。 data は文字列またはバッファです。 data がバッファの場合、encoding は無視されます。デフォルトは 'utf8' です。

例:

fs.writeFile('message.txt', 'Hello Node', function (err) {
  if (err) throw err;
  console.log('It\'s saved!');
});

fs.writeFileSync(filename, data, [encoding])#

同期版の fs.writeFile。

fs.appendFile(filename, data, encoding='utf8', [callback])#

非同期にデータをファイルに追加します。ファイルが存在しなければ作成されます。 data は文字列またはバッファです。 data がバッファの場合、encoding は無視されます。デフォルトは 'utf8' です。

例:

fs.appendFile('message.txt', 'data to append', function (err) {
  if (err) throw err;
  console.log('The "data to append" was appended to file!');
});

fs.appendFileSync(filename, data, encoding='utf8')#

同期版の fs.appendFile。

fs.watchFile(filename, [options], listener)#

Stability: 2 - Unstable.  Use fs.watch instead, if possible.

filename の変更を監視します。コールバックの listener はファイルがアクセスされる度に呼び出されます。

第 2 引数はオプションです． options が与えられる場合、それは boolean の persistent と interval の二つのメンバを含むオブジェクトです。 persistent はファイルが監視されている間、プロセスが実行し続けることを示します。 interval は対象をポーリングする間隔をミリ秒で示しますデフォルトは { persistent: true, interval: 5007 } です。

listener は現在の状態オブジェクトと前の状態オブジェクトの 2 つの引数を受け取ります:

fs.watchFile('message.text', function (curr, prev) {
  console.log('the current mtime is: ' + curr.mtime);
  console.log('the previous mtime was: ' + prev.mtime);
});

これらの状態オブジェクトは fs.Stat のインスタンスです。

もしファイルがアクセスされただけでなく、変更された時の通知が必要であれば、curr.mtime と prev.mtime を比較する必要があります。

fs.unwatchFile(filename, [listener])#

Stability: 2 - Unstable.  Use fs.watch instead, if available.

filename の変更に対する監視を終了します。 listener が指定された場合は該当の listener だけが取り除かれます。そうでなければ、全ての リスナが取り除かれ、 filenam の監視は事実上終了します。

監視されていないファイル名を指定した fs.unwatchFile() の呼び出しはエラーになるのではなく、何もしません。

fs.watch(filename, [options], [listener])#

Stability: 2 - Unstable.

filename の変更を監視します。 filename はファイルまたはディレクトリのどちらかです。戻り値のオブジェクトは fs.FSWatcher です。

第 2 引数はオプションです。もし指定されるなら、options は boolean の persistent プロパティを持つオブジェクトであるべきです。 persistent はファイルが監視されている間、プロセスが実行し続けることを示します。デフォルトは { persistent: true } です。

リスナーコールバックは二つの引数 (event, filename) を与えられます。 event は 'rename' または 'change'、そして filename はイベントを引き起こしたファイルの名前です。

Caveats#

fs.watch API はプラットフォーム間で 100% 完全ではありmせんし、いくつかのシチュエーションで利用不可能です。

Availability#

この機能は下層のオペレーティングシステムが提供するファイルシステム変更の通知に依存します。

Linux システムでは inotify が使われます。
BSD システム (OS X を含みます) では kqueue が使われます。
SunOS システム (Solaris および SmartOS を含みます) では event ports が使われます。
Windows システムでは、この機能は ReadDirectoryChangesW に依存します。

何らかの理由で下層の機能が使えない場合、fs.watch() は使えません。たとえば、ネットワークファイルシステム (NFS、SMB、その他) はしばしば信頼できないか全く動作しません。

stat をポーリングする fs.watchFile() を使うことはできますが、それは遅くて信頼性はより低くなります。

Filename Argument#

コールバックに提供される filename 引数は、全てのプラットフォームでサポートされるわけではありません (現時点では Linux と Windows でのみサポートされます)。サポートされるプラットフォームであっても、filename が常に提供されることが保証されているわけではありません。そのため、コールバックは filename 引数が常に提供されると仮定せず、それが null だったときの代替手段を持つべきです。

fs.watch('somedir', function (event, filename) {
  console.log('event is: ' + event);
  if (filename) {
    console.log('filename provided: ' + filename);
  } else {
    console.log('filename not provided');
  }
});

fs.exists(path, [callback])#

与えられたパスがファイルシステム上に存在するかどうか検査します。そして引数の callback を真か偽か検査の結果とともに呼び出します。例:

fs.exists('/etc/passwd', function (exists) {
  util.debug(exists ? "it's there" : "no passwd!");
});

fs.existsSync(path)#

同期版の fs.exists です。

Class: fs.Stats#

fs.stat()、fs.lstat()、fs.fstat()、そしてそれらの同期版から返されるオブジェクトはこの型です。

stats.isFile()
stats.isDirectory()
stats.isBlockDevice()
stats.isCharacterDevice()
stats.isSymbolicLink() (fs.lstat() でのみ有効)
stats.isFIFO()
stats.isSocket()

util.inspect(stats) は通常のファイルに対して次のような文字列を返します。

{ dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT }

atime、mtime、そして ctime は Date オブジェクトであり、その値を比較するには適切な方法があるということに注意してください。もっとも一般的に使われる getTime() は 1970 年 1 月 1 日からの経過時間をミリ秒単位で返します。それは比較には十分ですが、曖昧な情報を表示するには別の方法を使ってください。より詳しい情報は MDN JavaScript Reference で探すことができます。

fs.createReadStream(path, [options])#

新しい ReadStream オブジェクトを返します (Readable Stream を参照してください)。

options は以下のデフォルト値を持つオブジェクトです:

{ flags: 'r',
  encoding: null,
  fd: null,
  mode: 0666,
  bufferSize: 64 * 1024
}

ファイル全体を読み込む代わりに一部の範囲を読み込むため、 options に start および end を含めることができます。 start と end はどちらも包含的で0から始まります。 encoding は 'utf8'、'ascii'、または 'base64' です。

100 バイトの長さを持つファイルの最後の 10 バイトを読み込む例:

fs.createReadStream('sample.txt', {start: 90, end: 99});

Class: fs.ReadStream#

ReadStream は Readable Stream です。

Event: 'open'#

fd {Integer} ReadStream で使われるファイル記述子。

ReadStream のファイルがオープンされた場合に生成されます。

fs.createWriteStream(path, [options])#

新しい WriteStream オブジェクトを返します (Writable Stream を参照してください)。

options は以下のデフォルト値を持つオブジェクトです:

{ flags: 'w',
  encoding: null,
  mode: 0666 }

options にはデータをファイルのどの位置に書き込むかを指定する start を含めることができます。ファイルを置換するのではなく変更する場合は、 flags にデフォルトの w ではなく r+ が必要となります。

fs.WriteStream#

WriteStream は Writable Stream です。

Event: 'open'#

fd {Integer} WriteStream で使われるファイル記述子。

WriteStream のファイルがオープンされた場合に生成されます。

file.bytesWritten#

これまでに書き込まれたバイト数。書き込みがキューイングされたままのデータは含まれません。

Class: fs.FSWatcher#

fs.watch() が返すオブジェクトはこの型です。

watcher.close()#

fs.FSWatcher に与えられたファイルの監視を終了します。

Event: 'change'#

event {String} ファイルシステム変更の種類です。
filename {String} 変更されたファイル名です (もし利用可能であれば)。

監視しているファイルまたはディレクトリに変更があると生成されます。詳しくは fs.watch を参照してください。

Event: 'error'#

error Error object

エラーが発生すると生成されます。

Table of Contents

File System#

fs.rename(oldPath, newPath, [callback])#

fs.renameSync(oldPath, newPath)#

fs.truncate(fd, len, [callback])#

fs.truncateSync(fd, len)#

fs.chown(path, uid, gid, [callback])#

fs.chownSync(path, uid, gid)#

fs.fchown(fd, uid, gid, [callback])#

fs.fchownSync(fd, uid, gid)#

fs.lchown(path, uid, gid, [callback])#

fs.lchownSync(path, uid, gid)#

fs.chmod(path, mode, [callback])#

fs.chmodSync(path, mode)#

fs.fchmod(fd, mode, [callback])#

fs.fchmodSync(fd, mode)#

fs.lchmod(path, mode, [callback])#

fs.lchmodSync(path, mode)#

fs.stat(path, [callback])#

fs.lstat(path, [callback])#

fs.fstat(fd, [callback])#

fs.statSync(path)#

fs.lstatSync(path)#

fs.fstatSync(fd)#

fs.link(srcpath, dstpath, [callback])#

fs.linkSync(srcpath, dstpath)#

fs.symlink(srcpath, dstpath, [type], [callback])#

fs.symlinkSync(srcpath, dstpath, [type])#

fs.readlink(path, [callback])#

fs.readlinkSync(path)#

fs.realpath(path, [cache], callback)#

fs.realpathSync(path, [cache])#

fs.unlink(path, [callback])#

fs.unlinkSync(path)#

fs.rmdir(path, [callback])#

fs.rmdirSync(path)#

fs.mkdir(path, [mode], [callback])#

fs.mkdirSync(path, [mode])#

fs.readdir(path, [callback])#

fs.readdirSync(path)#

fs.close(fd, [callback])#

fs.closeSync(fd)#

fs.open(path, flags, [mode], [callback])#

fs.openSync(path, flags, [mode])#

fs.utimes(path, atime, mtime, [callback])#

fs.utimesSync(path, atime, mtime)#

fs.futimes(fd, atime, mtime, [callback])#

fs.futimesSync(fd, atime, mtime)#

fs.fsync(fd, [callback])#

fs.fsyncSync(fd)#

fs.write(fd, buffer, offset, length, position, [callback])#

fs.writeSync(fd, buffer, offset, length, position)#

fs.read(fd, buffer, offset, length, position, [callback])#

fs.readSync(fd, buffer, offset, length, position)#

fs.readFile(filename, [encoding], [callback])#

fs.readFileSync(filename, [encoding])#

fs.writeFile(filename, data, [encoding], [callback])#

fs.writeFileSync(filename, data, [encoding])#

fs.appendFile(filename, data, encoding='utf8', [callback])#

fs.appendFileSync(filename, data, encoding='utf8')#

fs.watchFile(filename, [options], listener)#

fs.unwatchFile(filename, [listener])#

fs.watch(filename, [options], [listener])#

Caveats#

Availability#

Filename Argument#

fs.exists(path, [callback])#

fs.existsSync(path)#

Class: fs.Stats#

fs.createReadStream(path, [options])#

Class: fs.ReadStream#

Event: 'open'#

fs.createWriteStream(path, [options])#

fs.WriteStream#

Event: 'open'#

file.bytesWritten#

Class: fs.FSWatcher#

watcher.close()#

Event: 'change'#

Event: 'error'#