nodejs>>fs

fs 文件系统File System
    /*文件系统模块是一个简单包装的标准 POSIX 文件 I/O 操作方法集。您可以通过调用require('fs')来获取该模块。文件系统模块中的所有方法均有异步和同步版本。
    文件系统模块中的异步方法需要一个完成时的回调函数作为最后一个传入形参。 回调函数的构成由您调用的异步方法所决定，
    通常情况下回调函数的第一个形参为返回的错误信息。 如果异步操作执行正确并返回，该错误形参则为null或者undefined。
    如果您使用的是同步版本的操作方法，则一旦出现错误，会以通常的抛出错误的形式返回错误。 你可以用try和catch等语句来拦截错误并使程序继续进行。*/

fs.readFile(filename, encoding, callback)
    filename 文件路径
    encoding 文件内容的编码,可选若为空,callback返回的内容为buffer的二进制数据
    callback 回调函数

    fs.readFileSync(path, encoding);同步函数
    filename 文件路径
    encoding 文件内容的编码,可选若为空,callback返回的内容为buffer的二进制数据
    var fs = require('fs');
    fs.readFile('a.txt', function(err, data){
        if(err){
            console.log(err);
        }else{
            console.log(data);//<Buffer 68 65 6c 6c 6f 20 66 73 20 21 0d 0a>
        }
    });
    fs.readFile('a.txt', 'utf-8', function(err, data){
        if(err){
            console.log(err);
        }else{
            console.log(data);//hello fs !
        }
    });
    //当读取文件的出错时,err就是Error对象
    var str = fs.readFileSync('a.txt');
    console.log(str);//<Buffer 68 65 6c 6c 6f 20 66 73 20 21 0d 0a>

    var str = fs.readFileSync('a.txt', 'utf-8');
    console.log(str);hello fs !
    //fs.readFileSync于fs.readFile的区别在于,前者会将获得到的内容以函数返回值的兴衰返回,如果有错误,fs会抛出异常,可以用try和catch捕捉并处理异常

fs.open(path, flags, mode, callback);
    path: 文件路径
    flags: {
        'r': 以只读模式打开文件
        'r+':以读写模式打开文件
        'w': 以写入模式打开文件,文件不存在则创建
        'w+':以读写模式打开文件,文件不存在则创建
        'a': 以追加模式打开文件,文件不存在则创建
        'a+':以追加模式打开文件,文件不存在则创建(追加模式在原有内容的基础上加入新的内容)
    }
    mode:可选,给文件制定权限,默认情况下是 0666, 有可读和可写权限
    callback: 返回一个文件描述符fd,(文件描述符的一个非负整数,表示操作系统内核为当前进程所维护的打开文件的记录表索引)
    fs.open('../views', 'r+', function(err, data){
        console.log(data);//3
    });
    fs.openSync(path, flags, [mode])同上

    fs.read(fd, buffer, offset, length, position, callback);
    从指定的文件描述符fd中读取数据并写入buffer指向的缓冲区对象.
    fd: 文件描述符
    buffer:缓冲区
    offset:开始向缓冲区 buffer 写入的偏移量
    length:是一个整形值，指定了读取的字节数
    position 是一个整形值，指定了从哪里开始读取文件，如果position为null，将会从文件当前的位置读取数据。
    回调函数给定了三个参数， (err, bytesRead, buffer)， 分别为错误，读取的字节和缓冲区。
    
    fs.readSync(fd, buffer, offset, length, position)
    fs.read 函数的同步版本。 返回bytesRead的个数
    var fs = require('fs');

    fs.open('a.txt', 'r', function(err, fd){
        if(err){
            console.log(err);
            return;
        }
        var buf = new Buffer(8);
        fs.read(fd, buf, 0, 8, null, function(err, bytesRead, buffer){
            if(err){
                console.log(err);
                return;
            }
            console.log('bytesRead: '+bytesRead);
            console.log(buffer);
        });
    });
    /*
    bytesRead: 8
    <Buffer 68 65 6c 6c 6f 20 66 73>
    */

fs.rename(oldPath, newPath, callback)
    更改oldPath的文件名为newPath,callback只有一个参数err

    fs.renameSync(oldPath, newPath)
    同步版本,无返回值

    fs.rename('a.txt', 'aa.txt', function(err){});
    fs.renameSync('aa.txt', 'a.txt');

fs.ftruncate(fd, len, callback)
    根据文件描述符fd来更改文件的大小为len,如果文件内容的长度>len,删除多余的,若<,用0来补到文件最后,callback只有err

    fs.ftruncateSync(fd, len)
    同步函数,无返回值

    fs.truncate(path, len, callback);
    更改path路径的文件大小为len,如果文件内容的长度>len,删除多余的,若<,用0来补到文件最后,callback只有err

    fs.truncateSync(fd, len)
    同步函数,无返回值
    //a.txt: hello world
    fs.truncate('a.txt', 1, function(err){
        if(err){
            console.log(err);
            return;
        }
    });
    //a.txt: h  

fs.chownSync(path, uid, gid)
    更改所有权(path)
    fs.fchown(fd, uid, gid, callback)
    更改所有权(fd)
    fs.fchownSync(fd, uid, gid)
    更改所有权(同步函数)
    fs.lchown(path, uid, gid, callback)
    更改文件所有权(不解析符号链接)   
    fs.lchownSync(path, uid, gid)
    更改文件所有权(不解析符号链接 同步函数) 

    fs.chmod(path, mode, callback)
    更改权限(path)
    fs.chmodSync(path, mode)
    更改权限(同步函数)
    fs.fchmod(fd, mode, callback)
    更改权限(fd)
    fs.fchmodSync(fd, mode)
    更改权限(fd 同步函数)
    fs.lchmod(path, mode, callback)
    更改权限(不解析符号链接)
    fs.lchmodSync(path, mode)
    更改权限(不解析符号链接 同步函数) 

fs.stat(path, callback(err, stats))
    获取文件的状态
    fs.stat('../api', function(err, stats){
        if(err){
            console.log(err);
            return ;
        }
        console.log(stats);
    })
    /*
    { dev: 0,
      mode: 16822,
      nlink: 1,
      uid: 0,
      gid: 0,
      rdev: 0,
      ino: 0,
      size: 0,
      atime: Wed Oct 15 2014 16:29:10 GMT+0800 (中国标准时间),
      mtime: Wed Oct 15 2014 16:29:10 GMT+0800 (中国标准时间),
      ctime: Sat Oct 04 2014 16:05:10 GMT+0800 (中国标准时间) }
    */

    fs.statSync(path);
    获取文件的状态(同步函数)

    fs.lstat(path, callback)
    获取文件的状态(不解析符号链接)

    fs.fstat(fd, callback)
    获取文件的状态(fd)

    fs.lstatSync(path)
    获取文件的状态(不解析符号链接 同步函数)

    fs.fstatSync(fd)
    获取文件的状态(fd 同步函数)

fs.link(srcpath, dstpath, callback(err));
    //创建一个关于srcpath的硬链接,命名为dstpath,dstpath就指srcpatj
    //link 创建的是hard link 所谓硬链接 symlink创建的是symbolic link 所谓符号链接 硬链接就是备份，软连接就是快捷方式
    fs.link('a.txt', 'current', function(err) {
        if(err) {
            console.log(err);
            return ;
        }
        fs.readFile('current', 'utf8', function(err, data) {
            // 会发现a.txt所在目录多了一个current文件,这个文件就是a.txt的备份
            var currentLog = data;
            console.log(data);
        });
    });

    fs.linkSync(srcpath, dstpath)
    上面的同步函数

    fs.symlink(srcpath, dstpath, [type], callback)
    //创建一个符号链接dstpath,包含srcpath
    fs.symlink('a.txt', 'current', function(err) {
        if(err) {
            console.log(err);
            return ;
        }
        fs.readFile('current', 'utf8', function(err, data) {
            // data is the contents of a.txt
            var currentLog = data;
            console.log(data);
        });
    });
    fs.symlinkSync(srcpath, dstpath, [type])

    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.mkdir('aa.js', function(err, files){//会在当前目录下创建一个文件夹aa.js,注意这里创建的是文件夹
        console.log(files);

        fs.rmdir('aa.js', function(err, files){//删除当前目录的aa.js文件夹
            console.log(files);

            fs.readdir('../', function(err, files){//读取当前目录的文件夹和文件
                console.log(files);
            });
        });

    });

fs.close(fd, callback)
    //关闭文件描述符为fd的文件
    fs.closeSync(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.writeFile(filename, data, [options], callback)
    //向文件写入data
    filename {String}
    data {String | Buffer}
    options {
        encoding {String | Null} default = 'utf8'
        mode {Number} default = 438 (aka 0666 in Octal)
        flag {String} default = 'w'
    }
    callback {Function}
    fs.writeFile('message.txt', 'Hello Node', function (err) {
      if (err) throw err;
      console.log('It\'s saved!'); //文件被保存
    });
    fs.writeFileSync(filename, data, [options])

    fs.appendFile(filename, data, [options], callback)
    //向问价你尾部添加data
    filename {String}
    data {String | Buffer}
    options {
        encoding {String | Null} default = 'utf8'
        mode {Number} default = 438 (aka 0666 in Octal)
        flag {String} default = 'w'
    }
    callback {Function}
    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, [options])

    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 路径可以是文件或者目录。
    //第二个参数是可选的. 如果 options 选项被提供那么它应当是一个只包含成员persistent得对象， 
    //persistent为boolean类型。persistent指定了进程是否“只要文件被监视就继续执行”缺省值为 { persistent: true }.
    //监听器的回调函数得到两个参数 (event, filename)。其中 event 是 'rename'（重命名）或者 'change'（改变），而 filename 则是触发事件的文件名。
    //fs.watch 不是完全跨平台的，且在某些情况下不可用,此功能依赖于操作系统底层提供的方法来监视文件系统的变化
    /*在 Linux 操作系统上，使用 inotify。
    在 BSD 操作系统上 (包括 OS X)，使用 kqueue。
    在 SunOS 操作系统上 (包括 Solaris 和 SmartOS)，使用 event ports。
    在 Windows 操作系统上，该特性依赖于 ReadDirectoryChangesW。*/
    /*如果系统底层函数出于某些原因不可用，那么 fs.watch 也就无法工作。例如，监视网络文件系统(如 NFS, SMB 等)的文件或者目录，就时常不能稳定的工作，有时甚至完全不起作用。*/
    //你仍然可以调用使用了文件状态调查的 fs.watchFile，但是会比较慢而且比较不可靠。
    /*在回调函数中提供的 filename 参数不是在每一个操作系统中都被支持（当下仅在Linux和Windows上支持）。 即便是在支持的系统中，filename也不能保证在每一次回调都被提供。
    因此，不要假设filename参数总会会在 回调函数中提供，在回调函数中添加检测filename是否为null的if判断语句。*/
    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)
    fs.existsSync(path)
    //检查指定路径的文件或者目录是否存在。接着通过 callback 传入的参数指明存在 (true) 或者不存在 (false)。
    fs.exists('/etc/passwd', function (exists) {
        util.debug(exists ? "存在" : "不存在!");
    });

Class: fs.Stats
    fs.stat()和 fs.lstat()方法返回的对象为此类型
    stats.isFile()
    stats.isDirectory()
    stats.isBlockDevice()
    stats.isCharacterDevice()
    stats.isSymbolicLink() (仅在与 fs.lstat()一起使用时合法)
    stats.isFIFO()
    stats.isSocket()
    { 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 }

Class: fs.ReadStream
    ReadStream 是一个可读的流(Readable Stream).
 
    事件: 'open'
    fd {整形} ReadStream 所使用的文件描述符。
    当文件的 ReadStream 被创建时触发。

    fs.createWriteStream(path, [options])
    返回一个新的 WriteStream 对象 (详见 Writable Stream).
    options 是一个包含下列缺省值的对象：
    { flags: 'w',encoding: null,mode: 0666 }
    options 也可以包含一个 start 选项用于指定在文件中开始写入数据的位置。 修改而不替换文件需要 flags 的模式指定为 r+ 而不是默值的 w.

    Class: fs.WriteStream
    WriteStream 是一个可写的流(Writable Stream).
    事件: 'open'
    fd {整形} WriteStream 所使用的文件描述符。
    当 WriteStream 创建时触发。

    file.bytesWritten
    已写的字节数。不包含仍在队列中准备写入的数据。

    Class: fs.FSWatcher
    fs.watch() 返回的对象类型。
    watcher.close()
    停止观察 fs.FSWatcher 对象中的更改。
    事件: 'change'
    event {字符串} fs 改变的类型
    filename {字符串} 改变的文件名 (if relevant/available)
    当正在观察的目录或文件发生变动时触发。更多细节，详见 fs.watch。
    事件: 'error'
    error {Error 对象}
    当产生错误时触发

asd