fs-ext

fs-ext
======

[![Build Status][ci-img]][ci-url]
[![Coverage Status][cov-img]][cov-url]
[![Windows Status][ci-win-img]][ci-win-url]

Extras not included in Node's fs module.

Note:

* From v2.0.0 onwards, module doesn't override fs and constants Node.js core modules. Instead
import functions and constants directly:

``js
const {flock, constants} = require('fs-ext');
// or
const fsExt = require('fs-ext');
// fsExt.flock
// fsExt.constants
`

* From v1.0.0 onwards, fs.utime and fs.utimeSync have been removed.
Use fs.utimes and fs.utimesSync instead.

Installation
------------

Install via npm:

`sh
npm install fs-ext
`

Usage
-----

fs-ext imports all of the methods from the core 'fs' module, so you don't
need two objects.

`js
const fs = require('fs');
const {flock} = require('fs-ext');

const fd = fs.openSync('foo.txt', 'r');
flock(fd, 'ex', (err) => {
if (err) {
return console.error("Couldn't lock file");
}
// file is locked
});
`

For an advanced example checkout example.js.

API
---

$3

Asynchronous flock(2). No arguments other than a possible error are passed to
the callback. Flags can be 'sh', 'ex', 'shnb', 'exnb', 'un' and correspond
to the various LOCK_SH, LOCK_EX, LOCK_SH|LOCK_NB, etc.

NOTE (from flock() man page): flock() does not lock files over NFS. Use fcntl(2)
instead: that does work over NFS, given a sufficiently recent version of Linux
and a server which supports locking.

$3

Synchronous flock(2). Throws an exception on error.

$3

Asynchronous fcntl(2).

callback will be given two arguments (err, result).

The supported commands are:

- 'getfd' ( F_GETFD )
- 'setfd' ( F_SETFD )
- 'setlk' ( F_SETLK )
- 'getlk' ( F_GETLK )
- 'setlkw' ( F_SETLKW )

Requiring this module adds FD_CLOEXEC to the constants module, for use with F_SETFD,
and also F_RDLCK, F_WRLCK and F_UNLCK for use with F_SETLK (etc).

File locking can be used like so:

`js
const {fnctl, constants} = require('fs-ext');

fcntl(fd, 'setlkw', constants.F_WRLCK, (err) => {
if (!err) {
// Lock succeeded
}
});
``

$3

Synchronous fcntl(2). Throws an exception on error.

$3

Asynchronous lseek(2).

callback will be given two arguments (err, currFilePos).

whence can be 0 (SEEK_SET) to set the new position in bytes to offset,
1 (SEEK_CUR) to set the new position to the current position plus offset
bytes (can be negative), or 2 (SEEK_END) to set to the end of the file
plus offset bytes (usually negative or zero to seek to the end of the file).

$3

Synchronous lseek(2). Throws an exception on error. Returns current
file position.

[ci-img]: https://travis-ci.org/baudehlo/node-fs-ext.svg?branch=master
[ci-url]: https://travis-ci.org/baudehlo/node-fs-ext
[cov-img]: https://codecov.io/github/baudehlo/node-fs-ext/coverage.svg
[cov-url]: https://codecov.io/github/baudehlo/node-fs-ext?branch=master
[ci-win-img]: https://ci.appveyor.com/api/projects/status/pqbnutckk0n46uc8?svg=true
[ci-win-url]: https://ci.appveyor.com/project/baudehlo/node-fs-ext/branch/master