IoT.js-API-File-System.md

Platform Support

The following shows fs module APIs available for each platform.

	Linux (Ubuntu)	Raspbian (Raspberry Pi)	NuttX (STM32F4-Discovery)
fs.close	O	O	O
fs.closeSync	O	O	O
fs.exists	O	O	O
fs.existsSync	O	O	O
fs.fstat	O	O	X
fs.fstatSync	O	O	X
fs.mkdir	O	O	O
fs.mkdirSync	O	O	O
fs.open	O	O	O
fs.openSync	O	O	O
fs.read	O	O	O
fs.readSync	O	O	O
fs.readdir	O	O	X
fs.readdirSync	O	O	X
fs.readFile	O	O	O
fs.readFileSync	O	O	O
fs.rename	O	O	O
fs.renameSync	O	O	O
fs.rmdir	O	O	O
fs.rmdirSync	O	O	O
fs.stat	O	O	O
fs.statSync	O	O	O
fs.unlink	O	O	O
fs.unlinkSync	O	O	O
fs.write	O	O	O
fs.writeSync	O	O	O
fs.writeFile	O	O	O
fs.writeFileSync	O	O	O

※ On NuttX path should be passed with a form of absolute path.

File System

Class: fs.Stats

fs.Stats class is an object returned from fs.stat(),fs.fstat() and their synchronous counterparts.

stats.isDirectory()

• Returns: {boolean}

Returns true if stated file is a directory.

stats.isFile()

• Returns: {boolean}

Returns true if stated file is a file.

Example

var assert = require('assert');
var fs = require('fs');

fs.stat('test.txt', function(err, stat) {
  if (err) {
    throw err;
  }
  assert.equal(stat.isFile(), true);
  assert.equal(stat.isDirectory(), false);
});

fs.close(fd, callback)

• fd {integer} File descriptor.
• callback {Function}
  • err {Error|null}

Closes the file of fd asynchronously.

Example

var fs = require('fs');

fs.open('test.txt', 'r', function(err, fd) {
  if (err) {
    throw err;
  }
  // do something
  fs.close(fd, function(err) {
    if (err) {
      throw err;
    }
  });
});

fs.closeSync(fd)

• fd {integer} File descriptor.

Closes the file of fd synchronously.

Example

var fs = require('fs');

var fd = fs.openSync('test.txt', 'r');
// do something
fs.closeSync(fd);

fs.exists(path, callback)

• path {string} File path to be checked.
• callback {Function}
  • exists {boolean}

Checks the file specified by path exists asynchronously.

Example

var assert = require('assert');
var fs = require('fs');

fs.exists('test.txt', function(exists) {
  assert.equal(exists, true);
});

fs.existsSync(path)

• path {string} File path to be checked.
• Returns: {boolean} True if the file exists, otherwise false.

Checks the file specified by path exists synchronously.

var assert = require('assert');
var fs = require('fs');

var result = fs.existsSync('test.txt');
assert.equal(result, true);

fs.fstat(fd, callback)

• fd {integer} File descriptor to be stated.
• callback {Function}
  • err {Error|null}
  • stat {Object} An instance of fs.Stats.

Get information about a file what specified by fd into stat asynchronously.

Example

var assert = require('assert');
var fs = require('fs');

fs.open('test.txt', 'r', function(err, fd) {
  if (err) {
    throw err;
  }
  fs.fstat(fd, function(err, stat) {
    if (err) {
      throw err;
    }
    assert.equal(stat.isFile(), true);
    assert.equal(stat.isDirectory(), false);
  });
});

fs.fstatSync(fd)

• fd {integer} - File descriptor to be stated.
• Returns: {Object} An instance of fs.Stats.

Get information about a file what specified by fd synchronously.

Example

var assert = require('assert');
var fs = require('fs');

fs.open('test.txt', 'r', function(err, fd) {
  if (err) {
    throw err;
  }
  var stat = fs.fstatSync(fd);
  assert.equal(stat.isFile(), true);
  assert.equal(stat.isDirectory(), false);
});

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

• path {string} Path of the directory to be created.
• mode {string|number} Permission mode. Default: 0777
• callback {Function}
  • err {Error|null}

Creates the directory specified by path asynchronously.

Example

var fs = require('fs');

fs.mkdir('testdir', function(err) {
  if (err) {
    throw err;
  }
});

fs.mkdirSync(path[, mode])

• path {string} Path of the directory to be created.
• mode {string|number} Permission mode. Default: 0777

Creates the directory specified by path synchronously.

Example

var fs = require('fs');

fs.mkdirSync('testdir');

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

• path {string} File path to be opened.
• flags {string} Open flags.
• mode {string|number} Permission mode. Default: 0666
• callback {Function}
  • err {Error|null}
  • fd {number}

Opens file asynchronously.

flags can be:

• r Opens file for reading. Throws an exception if the file does not exist.
• rs or sr Opens file for reading in synchronous mode. Throws an exception if the file does not exist.
• r+ Opens file for reading and writing. Throws an exception if the file does not exist.
• rs+ or sr+ Opens file for reading and writing in synchronous mode. Throws an exception if the file does not exist.
• w Opens file for writing. The file is overwritten if it exists.
• wx or xw Opens file for writing. Throws an exception if it exists.
• w+ Opens file for reading and writing. The file is overwritten if it exists.
• wx+ or xw+ Opens file for reading and writing. Throws an exception if it exists.
• a Opens file for appending. The file is created if it does not exist.
• ax or xa Opens file for appending. Throws an exception if it exists.
• a+ Opens file for reading and appending. The file is created if it does not exist.
• ax+ or xa+ Opens file for reading and appending. Throws an exception if it exists.

Example

var fs = require('fs');

fs.open('test.txt', 'r', 755, function(err, fd) {
  if (err) {
    throw err;
  }
  // do something
});

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

• path {string} File path to be opened.
• flags {string} Open flags.
• mode {string|number} Permission mode. Default: 0666
• Returns: {number} File descriptor.

Opens file synchronously.

For available options of the flags see fs.open().

Example

var fs = require('fs');

var fd = fs.openSync('test.txt', 'r', 755);
// do something

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

• fd {integer} File descriptor.
• buffer {Buffer} Buffer that the data will be written to.
• offset {number} Offset of the buffer where to start writing.
• length {number} Number of bytes to read.
• position {number} Specifying where to start read data from the file, if null or undefined, read from current position.
• callback {Function}
  • err {Error|null}
  • bytesRead {number}
  • buffer {Buffer}

Reads data from the file specified by fd asynchronously.

Example

var fs = require('fs');

fs.open('test.txt', 'r', 755, function(err, fd) {
  if (err) {
    throw err;
  }
  var buffer = new Buffer(64);
  fs.read(fd, buffer, 0, buffer.length, 0, function(err, bytesRead, buffer) {
    if (err) {
      throw err;
    }
  });
});

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

• fd {integer} File descriptor.
• buffer {Buffer} Buffer that the data will be written to.
• offset {number} Offset of the buffer where to start writing.
• length {number} Number of bytes to read.
• position {number} Specifying where to start read data from the file, if null or undefined, read from current position.
• Returns: {number} Number of read bytes.

Reads data from the file specified by fd synchronously.

Example

var fs = require('fs');

var buffer = new Buffer(16);
var fd = fs.openSync('test.txt', 'r');
var bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);

fs.readdir(path, callback)

• path {string} Directory path to be checked.
• callback {Function}
  • err {Error|null}
  • files {Object}

Reads the contents of the directory specified by path asynchronously, . and .. are excluded from files.

Example

var fs = require('fs');

fs.readdir('testdir', function(err, items) {
  if (err) {
    throw err;
  }

  // prints: file1,file2,... from 'testdir'
  console.log(items);
});

fs.readdirSync(path)

• path {string} Directory path to be checked.
• Returns: {Object} Array of filenames.

Reads the contents of the directory specified by path synchronously, . and .. are excluded from filenames.

Example

var fs = require('fs');

var items = fs.readdirSync('testdir');

// prints: file1,file2,... from 'testdir'
console.log(items);

fs.readFile(path, callback)

• path {string} File path to be opened.
• callback {Function}
  • err {Error|null}
  • data {Buffer}

Reads entire file asynchronously into data.

Example

var fs = require('fs');

fs.readFile('test.txt', function(err, data) {
  if (err) {
    throw err;
  }

  // prints: the content of 'test.txt'
  console.log(data);
});

fs.readFileSync(path)

• path {string} File path to be opened.
• Returns: {Object} Contents of the file.

Reads entire file synchronously.

Example

var fs = require('fs');

var data = fs.readFileSync('test.txt');

fs.rename(oldPath, newPath, callback)

• oldPath {string} Old file path.
• newPath {string} New file path.
• callback {Function}
  • err {Error|null}

Renames oldPath to newPath asynchronously.

Example

var fs = require('fs');

fs.rename('test.txt', 'test.txt.async', function(err) {
  if (err) {
    throw err;
  }
});

fs.renameSync(oldPath, newPath)

• oldPath {string} Old file path.
• newPath {string} New file path.

Renames oldPath to newPath synchronously.

Example

var fs = require('fs');

fs.renameSync('test.txt', 'test.txt.sync');

fs.rmdir(path, callback)

• path {string} Directory path to be removed.
• callback {Function}
  • err {Error|null}

Removes the directory specified by path asynchronously.

Example

var fs = require('fs');

fs.rmdir('testdir', function() {
  // do something
});

fs.rmdirSync(path)

• path {string} Directory path to be removed.

Removes the directory specified by path synchronously.

var fs = require('fs');

fs.rmdirSync('testdir');

fs.stat(path, callback)

• path {string} File path to be stated.
• callback {Function}
  • err {Error|null}
  • stat {Object}

Get information about a file into stat asynchronously.

Example

var assert = require('assert');
var fs = require('fs');

fs.stat('test.txt', function(err, stat) {
  if (err) {
    throw err;
  }
  assert.equal(stat.isFile(), true);
  assert.equal(stat.isDirectory(), false);
});

fs.statSync(path)

• path {string} File path to be stated.
• Returns: {Object} An instance of fs.Stats.

Get information about a file synchronously.

Example

var assert = require('assert');
var fs = require('fs');

var stat = fs.statSync('test.txt');
assert.equal(stat.isFile(), true);
assert.equal(stat.isDirectory(), false);

fs.unlink(path, callback)

• path {string} File path to be removed.
• callback {Function}
  • err {Error|null}

Removes the file specified by path asynchronously.

Example

var fs = require('fs');

fs.unlink('test.txt', function(err) {
  if (err) {
    throw err;
  }
});

fs.unlinkSync(path)

• path {string} File path to be removed.

Removes the file specified by path synchronously.

Example

var fs = require('fs');

fs.unlinkSync('test.txt');

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

• fd {integer} File descriptor.
• buffer {Buffer} Buffer that the data will be written from.
• offset {number} Offset of the buffer where from start reading.
• length {number} Number of bytes to write.
• position {number} Specifying where to start write data to the file, if null or undefined, write at the current position.
• callback {Function}
  • err {Error|null}
  • bytesWrite {integer}
  • buffer {Object}

Writes buffer to the file specified by fd asynchronously.

Example

var fs = require('fs');

var file = 'test.txt'
var data = new Buffer('IoT.js');

fs.open(file, 'w', function(err, fd) {
  if (err) {
    throw err;
  }

  fs.write(fd, data, 0, data.length, function(err, bytesWrite, buffer) {
    if (err) {
      throw err;
    }

    // prints: 6
    console.log(bytesWrite);

    // prints: IoT.js
    console.log(buffer);
  });
});

fs.writeSync(fd, buffer, offset, length[, position])

• fd {integer} File descriptor.
• buffer {Buffer} Buffer that the data will be written from.
• offset {number} Offset of the buffer where from start reading.
• length {number} Number of bytes to write.
• position {number} Specifying where to start write data to the file, if null or undefined, write at the current position.
• Returns: {number} Number of bytes written.

Writes buffer to the file specified by fd synchronously.

var fs = require('fs');

var file = 'test.txt'
var data = new Buffer('IoT.js');

var fd = fs.openSync(file, 'w');
var bytes = fs.writeSync(fd, data, 0, data.length);

//prints: 6
console.log(bytes);

fs.writeFile(path, data, callback)

• path {string} File path that the data will be written.
• data {string|Buffer} String or buffer that contains data.
• callback {Function}
  • err {Error|null}

Writes entire data to the file specified by path asynchronously.

Example

var fs = require('fs');

fs.writeFile('test.txt', 'IoT.js', function(err) {
  if (err) {
    throw err;
  }
});

fs.writeFileSync(path, data)

• path {string} File path that the data will be written.
• data {string|Buffer} String or buffer that contains data.

Writes entire data to the file specified by path synchronously.

Example

var fs = require('fs');

fs.writeFileSync('test.txt', 'IoT.js');