File-nodejs

文件系统模块是一个简单包装的标准 POSIX 文件 I/O 操作方法集。您可以通过调用require('fs')来获取该模块。文件系统模块中的所有方法均有异步和同步版本。

文件系统模块中的异步方法需要一个完成时的回调函数作为最后一个传入形参。 回调函数的构成由您调用的异步方法所决定，通常情况下回调函数的第一个形参为返回的错误信息。 如果异步操作执行正确并返回，该错误形参则为null或者undefined。

如果您使用的是同步版本的操作方法，则一旦出现错误，会以通常的抛出错误的形式返回错误。 你可以用try和catch等语句来拦截错误并使程序继续进行。

这里是一个异步版本的例子：

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

这是同步版本的例子:

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前执行.要等到正确的执行顺序应该用下面的方法:

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)函数可以忽略回调函数(callback)这个参数.如果忽略它,将会由一个默认回调函数(callback)来重新抛出(rethrow)错误.要获得原调用点的堆栈跟踪(trace)信息,需要在环境变量里设置NODE_DEBUG.

$ env NODE_DEBUG=fs node script.js
fs.js:66
        throw err;
              ^
Error: EISDIR, read
    at rethrow (fs.js:61:21)
    at maybeCallback (fs.js:79:42)
    at Object.fs.readFile (fs.js:153:18)
    at bad (/path/to/script.js:2:17)
    at Object.<anonymous> (/path/to/script.js:5:1)
    <etc.>

fs.rename(oldPath, newPath, callback)

重命名某个文件,异步版本的rename函数(2).完成时的回调函数(callback)只接受一个参数:可能出现的异常信息.

fs.renameSync(oldPath, newPath)

同步版本的rename(2).

fs.ftruncate(fd, len, callback)

截断某个文件 异步版本的ftruncate(2). 完成时的回调函数(callback)只接受一个参数:可能出现的异常信息.

fs.ftruncateSync(fd, len)

同步版本的ftruncate(2).

fs.truncate(path, len, callback)

异步版本的truncate(2). 完成时的回调函数(callback)只接受一个参数:可能出现的异常信息

fs.chmod(path, mode, [callback]) 和 fs.chmodSync(path, mode)

修改文件权限，主要说下第二个参数,实际上是：-rwxrwxrwx，三个一组，r:4、w:2、x:1、-: 0。可以 参考 http://zh.wikipedia.org/zh/Chmod

fs.stat(path, [callback]),fs.lstat(path, [callback]),fs.fstat(fd, [callback]) 和 fs.statSync(path)、fs.lstatSync(path)、fs.fstatSync(fd)

读取文件元信息，回调函数将返回两个参数(err, stats)，其中stats是fs.Stats的一个对象.者的区别在于：
第一个是返回文件的信息，参数是路径
第二个是和第一个一样，当路径是文件链接时，返回这个链接文件的信息
第三个是传递参数为fd文件描述符

fs.link(srcpath, dstpath, [callback])、fs.linkSync(srcpath, dstpath) 和 fs.symlink(linkdata, path, [callback])、fs.symlinkSync(linkdata, path)

建立文件链接，除非回调函数执行过程出现了异常，否则不会传递任何参数。link和symlink的区别是： link 创建的是hard link 所谓硬链接 symlink创建的是symbolic link 所谓符号链接 硬链接就是备份，软连接就是快捷方式

fs.readlink(path, [callback])、fs.realpath(path, [callback]) 、fs.unlink(path, [callback])和 fs.readlinkSync(path)、fs.realpathSync(path)、fs.unlinkSync(path)

异步调用readlink，回调函数返回两个参数(err,resolvedPath)，resolvedPath为解析后的文件路径。 这3个函数分别是： 1、readlink：读取链接源地址 2、realpath：根据相对地址转换为绝对地址 3、unlink：删除某一个文件链接

fs.rmdir(path, [callback])、fs.mkdir(path, mode, [callback])、fs.readdir(path, [callback]) 和 fs.rmdirSync(path)、fs.mkdirSync(path, mode)、fs.readdirSync(path)

三个命令分别是： rmdir:删除目录 mkdir:建立目录 readdir：读取目录中的内容。回调函数接受两个参数(err, files)，其中files参数是保存了目录中所有文件名的数组（'.'和'..'除外）。

fs.close(fd, [callback])、fs.closeSync(fd) 和 fs.open(path, flags, [mode], [callback])、fs.openSync(path, flags, [mode])

fs.open与 C 语言标准库中的 fopen 函数类似。它接受两个必选参数，path 为文件的路径， flags 可以是以下值。  r ：以读取模式打开文件。
 r+ ：以读写模式打开文件。
 w ：以写入模式打开文件，如果文件不存在则创建。
 w+ ：以读写模式打开文件，如果文件不存在则创建。
 a ：以追加模式打开文件，如果文件不存在则创建。
 a+ ：以读取追加模式打开文件，如果文件不存在则创建。
mode 参数用于创建文件时给文件指定权限，默认是 0666。回调函数将会传递一个文 件描述符 fd。

fs.utimes(path, atime, mtime, callback)、fs.utimesSync(path, atime, mtime) 和 fs.futimes(path, atime, mtime, callback)、fs.futimesSync(path, atime, mtime)

更改文件时间戳，2者区别在于，utimes更改此文件时间戳，如果此文件指向一个符号链接，futimes更改符号链接的时间戳。

fs.write(fd, buffer, offset, length, position, [callback]) 和 fs.writeSync(fd, buffer, offset, length, position) 和 fs.writeSync(fd, str, position, encoding='utf8')

fs.write将buffer缓冲器内容写入fd文件描述符,
offset和length决定了将缓冲器中的哪部分写入文件。
position指明将数据写入文件从头部算起的偏移位置，若position为null，数据将从当前位置开始写入
回调函数接受两个参数(err, written)，其中written标识有多少字节的数据已经写入
第三个是基于字符串的fs.write()的同步版本，返回写入数据的字节数。
注意：写完后要关闭它

fs.read(fd, buffer, offset, length, position, [callback]) 、fs.readSync(fd, buffer, offset, length, position)、fs.readSync(fd, length, position, encoding) 和 fs.readFile(filename, [encoding], [callback])、fs.readFileSync(filename, [encoding])

前3个是读取文件描述符和BUFFER的方法，后2个是读取文件全部内容，比如输出html模版，或者css文件等。
一般来说，除非必要，否则不要使用前3个是读取文件方式读取文件，因为它要求你手动管理缓冲区 和文件指针，尤其是在你不知道文件大小的时候，这将会是一件很麻烦的事情。
fs.read回调函数接受两个参数，(err, bytesRead),bytesRead返回读取到的字节数。
fs.readFile的回调函数将传入两个参数(err, data)，其中data为文件内容，如果没有设置编码，那么将返回原始内容格式的缓冲器。

fs.writeFile(filename, data, encoding='utf8', [callback]),fs.writeFileSync(filename, data, encoding='utf8')

对应文件写功能

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

fs.watchFile监听指定文件filename的变化，回调函数listener将在每次该文件被访问时被调用.
第二个参数[options]是可选项，如果指定了options参数，它应该是一个包含如下内容的对象：名为persistent的布尔值，和名为interval单位为毫秒的轮询时间间隔，默认值为{ persistent: true, interval: 0 }。 listener监听器将获得两个参数(curr, prev)，分别标识当前的状态对象和改变前的状态对象,这些状态对象为fs.Stat的实例。
fs.unwatchFile停止监听文件filename的变化。

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

观察指定路径的改变，filename 路径可以是文件或者目录。改函数返回的对象是 fs.FSWatcher。

第二个参数是可选的. 如果 options 选项被提供那么它应当是一个只包含成员persistent得对象，persistent为boolean类型。persistent指定了进程是否“只要文件被监视就继续执行”缺省值为 { persistent: true }.

监听器的回调函数得到两个参数 (event, filename)。其中 event 是 'rename'（重命名）或者 'change'（改变），而 filename 则是触发事件的文件名。（fs.watch 不是完全跨平台的，且在某些情况下不可用。）

fs.exists(path, callback) 和 fs.existsSync(path)

检查指定路径的文件或者目录是否存在。接着通过 callback 传入的参数指明存在 (true) 或者不存在 (false)。示例:

fs.Stats

fs.stat()和 fs.lstat()方法返回的对象为此类型

• stats.isFile()

• stats.isDirectory()
• stats.isBlockDevice()
• stats.isCharacterDevice()
• stats.isSymbolicLink() (only valid with fs.lstat()) stats.isSymbolicLink() （仅对fs.lstat()有效）
• stats.isFIFO()
• stats.isSocket()

对于一个普通文件使用 util.inspect(stats) 将会返回一个类似如下输出的字符串：

{ dev: 2049,
  ino: 305352,
  mode: 16877,
  nlink: 12,
  uid: 1000,
  gid: 1000,
  rdev: 0,
  size: 4096,
  blksize: 4096,
  blocks: 8,
  atime: '2009-06-29T11:11:55Z',
  mtime: '2009-06-29T11:11:40Z',
  ctime: '2009-06-29T11:11:40Z' }

fs.createReadStream(path, [options])

返回一个新的可读流对象options是包含如下默认值的对象：
{ flags: 'r', encoding: null, fd: null, mode: 0666, bufferSize: 64 * 1024 }
如果不想读取文件的全部内容，可以在options参数中设置start和end属性值以读取文件中指定范围的内容。start和end包含在范围中（闭集合），取值从0开始。这两个参数需要同时设置。

fs.createWriteStream(path, [options])

options参数是包含如下默认值的对象：
{ flags: 'w', encoding: null, mode: 0666 }

fs.appendFile(filename, data, [options], callback) 和

fs.appendFileSync(filename, data, [options])

• filename {String}

• data {String | Buffer}
• options {Object}
  • encoding {String | Null} default = 'utf8'

  • mode {Number} default = 438 (aka 0666 in Octal)
  • flag {String} default = 'a'
• callback {Function}

异步的将数据添加到一个文件的尾部，如果文件不存在，会创建一个新的文件。 data 可以是一个string，也可以是原生buffer。

事件

事件: 'open'

• fd {整形} ReadStream 所使用的文件描述符。

当文件的 ReadStream 被创建时触发。

事件: 'change'

• event {字符串} fs 改变的类型

• filename {字符串} 改变的文件名 (if relevant/available)

当正在观察的目录或文件发生变动时触发

事件: 'error'

• error {Error 对象}

当产生错误时触发