Skip to content
This repository has been archived by the owner on Jul 18, 2021. It is now read-only.

Commit

Permalink
Replaced the whole documentation by the deprecation information
Browse files Browse the repository at this point in the history
  • Loading branch information
Pavel Lobodinský committed Jun 17, 2016
1 parent 447195d commit 9f0929b
Showing 1 changed file with 2 additions and 109 deletions.
111 changes: 2 additions & 109 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,114 +1,7 @@
# unix-access
This module is **DEPRECATED**.

`Node.js` module wrapping `access()` UNIX C function, which is currently missing in both V8 and Node's fs API. Both `sync` and `async` implementations are available.

`OS X` and `Linux` platforms supported.

# ! CAUTION !

This module is now **DEPRECATED**. Since `v1.0.0`, `Node.js` has an out-of-the-box implementation of both
Since `v1.0.0`, `Node.js` has an out-of-the-box implementation of both
[fs.access()](https://nodejs.org/api/fs.html#fs_fs_access_path_mode_callback) and
[fs.accessSync()](https://nodejs.org/api/fs.html#fs_fs_accesssync_path_mode).

Please use these native functions instead of this module.

# Introduction

Ever needed to find out whether your app has specific permissions to a path? Now you can check a path for `read`, `write` and `execute/search` permissions on files and directories.

# Usage

Just issue `require('unix-access')` and you can run two functions available: `sync` and `async`.

### Examples

```js
var access = require('unix-access');
var result;

// synchronous checks
result = access.sync('/var/log/your_app.log', ''); // existence of the file
result = access.sync('/var/log/your_app.log', 'rw'); // read and write permissions
result = access.sync('/var/log/your_app_dir/', 'rwx'); // full control

// asynchronous check for read and executable permissions
access.async('/bin/tar', 'rx', function(err, result) {
console.log(result);
});
```

### sync(path, permissions)

Both arguments are of `String` type. Return value is of `Boolean` type. TypeError exception is thrown in case of incorrect type of aguments.

Permissions may contain case-insensitive combination of `r`, `w`, and `x` characters. Any other characters will be stripped out.

`True` return value indicates you do have the permissions you were testing the path for, `False` means you do not.

### async(path, permissions, callback)

Works the same way as `sync` version but asychronously. Callback argument must be of `Function` type.

Two arguments will be passed over the `callback(err, result)` function. Err is of `String` type, result of `Boolean` type.

# Installation

`npm install unix-access`

# Supported platforms and requirements

### OS X

Tested on OS X Yosemite 10.10.

Requires:

* Xcode
* Python 2.7 (present in the OS by default)

### Linux

Tested on Debian Wheezy 7.0 64bit.

Requires:

* make
* g++
* Python 2.7

# Dependencies

This module only depends on `Nan` Node.js module which eliminates incompatibilities among Node.js versions.

For developers of this tool, `mocha` and `should` are additional dependencies for running unit tests.

# Technical details

Once issuing `npm install unix-access`, npm copies the module into node_modules directory and then executes `node-gyp rebuild` command to compile C++ sources. `node-gyp` is bundled within npm itself so you don't need to install it separately.

The C++ code being built by `node-gyp` is a gue between Google's V8 engine and native OS `access()` call defined in `<unistd.h>`.

Async function is really asynchronous (NOT just issuing callback in `process.nextTick()`). `uv_queue_work()` call from `libuv` manages the asynchronous execution in a separate thread pool.

For more information about UNIX `access()` function, run `man access` in your OS.

# Development

In order to develop this module, these steps are required:

* Clone the git repo by executing `git clone URL`
* Go to the newly created directory in Terminal
* Run `npm install node-gyp -g`
* Run `npm install` to download dependencies
* Run `node-gyp rebuild` to build your modified code
* Run unit tests by `npm test`

### Troubleshooting

If you want to develop this module and try to install `dev_dependencies` by executing `npm install`, you may see the error message below:

```
npm WARN cannot run in wd [email protected] node-gyp rebuild (wd=/root/unix-access-master)
```

The reason why `npm install` fails is that you run the `npm install` command as `root` user. If you really have to work under root user, use `npm install --unsafe-perm` instead.

0 comments on commit 9f0929b

Please sign in to comment.