aboutsummaryrefslogtreecommitdiff
path: root/node_modules/tmp/README.md
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2016-11-16 01:59:39 +0100
committerFlorian Dold <florian.dold@gmail.com>2016-11-16 02:00:31 +0100
commitbd65bb67e25a79b019d745b7262b2008ce2adb15 (patch)
tree89e1b032103a63737f1a703e6a943832ef261704 /node_modules/tmp/README.md
parentf91466595b651721690133f58ab37f977539e95b (diff)
incrementally verify denoms
The denominations are not stored in a separate object store.
Diffstat (limited to 'node_modules/tmp/README.md')
-rw-r--r--node_modules/tmp/README.md144
1 files changed, 125 insertions, 19 deletions
diff --git a/node_modules/tmp/README.md b/node_modules/tmp/README.md
index 3a1a509e9..804bf3395 100644
--- a/node_modules/tmp/README.md
+++ b/node_modules/tmp/README.md
@@ -2,17 +2,21 @@
A simple temporary file and directory creator for [node.js.][1]
-[![Build Status](https://secure.travis-ci.org/raszi/node-tmp.png?branch=master)](http://travis-ci.org/raszi/node-tmp)
+[![Build Status](https://travis-ci.org/raszi/node-tmp.svg?branch=master)](https://travis-ci.org/raszi/node-tmp)
+[![Dependencies](https://david-dm.org/raszi/node-tmp.svg)](https://david-dm.org/raszi/node-tmp)
+[![npm version](https://badge.fury.io/js/tmp.svg)](https://badge.fury.io/js/tmp)
## About
-The main difference between bruce's [node-temp][2] is that mine more
-aggressively checks for the existence of the newly created temporary file and
-creates the new file with `O_EXCL` instead of simple `O_CREAT | O_RDRW`, so it
-is safer.
+This is a [widely used library][2] to create temporary files and directories
+in a [node.js][1] environment.
-The API is slightly different as well, Tmp does not yet provide synchronous
-calls and all the parameters are optional.
+Tmp offers both an asynchronous and a synchronous API. For all API calls, all
+the parameters are optional.
+
+Tmp uses crypto for determining random file names, or, when using templates,
+a six letter random identifier. And just in case that you do not have that much
+entropy left on your system, Tmp will fall back to pseudo random numbers.
You can set whether you want to remove the temporary file on process exit or
not, and the destination directory can also be set.
@@ -25,22 +29,48 @@ npm install tmp
## Usage
-### File creation
+### Asynchronous file creation
-Simple temporary file creation, the file will be unlinked on process exit.
+Simple temporary file creation, the file will be closed and unlinked on process exit.
```javascript
var tmp = require('tmp');
-tmp.file(function _tempFileCreated(err, path, fd) {
+tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
if (err) throw err;
console.log("File: ", path);
console.log("Filedescriptor: ", fd);
+
+ // If we don't need the file anymore we could manually call the cleanupCallback
+ // But that is not necessary if we didn't pass the keep option because the library
+ // will clean after itself.
+ cleanupCallback();
});
```
-### Directory creation
+### Synchronous file creation
+
+A synchronous version of the above.
+
+```javascript
+var tmp = require('tmp');
+
+var tmpobj = tmp.fileSync();
+console.log("File: ", tmpobj.name);
+console.log("Filedescriptor: ", tmpobj.fd);
+
+// If we don't need the file anymore we could manually call the removeCallback
+// But that is not necessary if we didn't pass the keep option because the library
+// will clean after itself.
+tmpobj.removeCallback();
+```
+
+Note that this might throw an exception if either the maximum limit of retries
+for creating a temporary name fails, or, in case that you do not have the permission
+to write to the directory where the temporary file should be created in.
+
+### Asynchronous directory creation
Simple temporary directory creation, it will be removed on process exit.
@@ -49,17 +79,37 @@ If the directory still contains items on process exit, then it won't be removed.
```javascript
var tmp = require('tmp');
-tmp.dir(function _tempDirCreated(err, path) {
+tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
if (err) throw err;
console.log("Dir: ", path);
+
+ // Manual cleanup
+ cleanupCallback();
});
```
If you want to cleanup the directory even when there are entries in it, then
you can pass the `unsafeCleanup` option when creating it.
-### Filename generation
+### Synchronous directory creation
+
+A synchronous version of the above.
+
+```javascript
+var tmp = require('tmp');
+
+var tmpobj = tmp.dirSync();
+console.log("Dir: ", tmpobj.name);
+// Manual cleanup
+tmpobj.removeCallback();
+```
+
+Note that this might throw an exception if either the maximum limit of retries
+for creating a temporary name fails, or, in case that you do not have the permission
+to write to the directory where the temporary directory should be created in.
+
+### Asynchronous filename generation
It is possible with this library to generate a unique filename in the specified
directory.
@@ -74,9 +124,20 @@ tmp.tmpName(function _tempNameGenerated(err, path) {
});
```
+### Synchronous filename generation
+
+A synchronous version of the above.
+
+```javascript
+var tmp = require('tmp');
+
+var name = tmp.tmpNameSync();
+console.log("Created temporary filename: ", name);
+```
+
## Advanced usage
-### File creation
+### Asynchronous file creation
Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
@@ -91,7 +152,19 @@ tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileC
});
```
-### Directory creation
+### Synchronous file creation
+
+A synchronous version of the above.
+
+```javascript
+var tmp = require('tmp');
+
+var tmpobj = tmp.fileSync({ mode: 0644, prefix: 'prefix-', postfix: '.txt' });
+console.log("File: ", tmpobj.name);
+console.log("Filedescriptor: ", tmpobj.fd);
+```
+
+### Asynchronous directory creation
Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
@@ -105,7 +178,18 @@ tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path)
});
```
-### mkstemps like
+### Synchronous directory creation
+
+Again, a synchronous version of the above.
+
+```javascript
+var tmp = require('tmp');
+
+var tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
+console.log("Dir: ", tmpobj.name);
+```
+
+### mkstemp like, asynchronously
Creates a new temporary directory with mode `0700` and filename like `/tmp/tmp-nk2J1u`.
@@ -119,7 +203,18 @@ tmp.dir({ template: '/tmp/tmp-XXXXXX' }, function _tempDirCreated(err, path) {
});
```
-### Filename generation
+### mkstemp like, synchronously
+
+This will behave similarly to the asynchronous version.
+
+```javascript
+var tmp = require('tmp');
+
+var tmpobj = tmp.dirSync({ template: '/tmp/tmp-XXXXXX' });
+console.log("Dir: ", tmpobj.name);
+```
+
+### Asynchronous filename generation
The `tmpName()` function accepts the `prefix`, `postfix`, `dir`, etc. parameters also:
@@ -133,6 +228,16 @@ tmp.tmpName({ template: '/tmp/tmp-XXXXXX' }, function _tempNameGenerated(err, pa
});
```
+### Synchronous filename generation
+
+The `tmpNameSync()` function works similarly to `tmpName()`.
+
+```javascript
+var tmp = require('tmp');
+var tmpname = tmp.tmpNameSync({ template: '/tmp/tmp-XXXXXX' });
+console.log("Created temporary filename: ", tmpname);
+```
+
## Graceful cleanup
One may want to cleanup the temporary files even when an uncaught exception
@@ -151,12 +256,13 @@ All options are optional :)
* `mode`: the file mode to create with, it fallbacks to `0600` on file creation and `0700` on directory creation
* `prefix`: the optional prefix, fallbacks to `tmp-` if not provided
* `postfix`: the optional postfix, fallbacks to `.tmp` on file creation
- * `template`: [`mkstemps`][3] like filename template, no default
+ * `template`: [`mkstemp`][3] like filename template, no default
* `dir`: the optional temporary directory, fallbacks to system default (guesses from environment)
* `tries`: how many times should the function try to get a unique filename before giving up, default `3`
* `keep`: signals that the temporary file or directory should not be deleted on exit, default is `false`, means delete
+ * Please keep in mind that it is recommended in this case to call the provided `cleanupCallback` function manually.
* `unsafeCleanup`: recursively removes the created temporary directory, even when it's not empty. default is `false`
[1]: http://nodejs.org/
-[2]: https://github.com/bruce/node-temp
+[2]: https://www.npmjs.com/browse/depended/tmp
[3]: http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html