1 | # Tmp
|
2 |
|
3 | A simple temporary file and directory creator for [node.js.][1]
|
4 |
|
5 | [![Build Status](https://secure.travis-ci.org/raszi/node-tmp.png?branch=master)](http://travis-ci.org/raszi/node-tmp)
|
6 |
|
7 | ## About
|
8 |
|
9 | The main difference between bruce's [node-temp][2] is that mine more
|
10 | aggressively checks for the existence of the newly created temporary file and
|
11 | creates the new file with `O_EXCL` instead of simple `O_CREAT | O_RDRW`, so it
|
12 | is safer.
|
13 |
|
14 | The API is slightly different as well, Tmp does not yet provide synchronous
|
15 | calls and all the parameters are optional.
|
16 |
|
17 | You can set whether you want to remove the temporary file on process exit or
|
18 | not, and the destination directory can also be set.
|
19 |
|
20 | ## How to install
|
21 |
|
22 | ```bash
|
23 | npm install tmp
|
24 | ```
|
25 |
|
26 | ## Usage
|
27 |
|
28 | ### File creation
|
29 |
|
30 | Simple temporary file creation, the file will be unlinked on process exit.
|
31 |
|
32 | ```javascript
|
33 | var tmp = require('tmp');
|
34 |
|
35 | tmp.file(function _tempFileCreated(err, path, fd) {
|
36 | if (err) throw err;
|
37 |
|
38 | console.log("File: ", path);
|
39 | console.log("Filedescriptor: ", fd);
|
40 | });
|
41 | ```
|
42 |
|
43 | ### Directory creation
|
44 |
|
45 | Simple temporary directory creation, it will be removed on process exit.
|
46 |
|
47 | If the directory still contains items on process exit, then it won't be removed.
|
48 |
|
49 | ```javascript
|
50 | var tmp = require('tmp');
|
51 |
|
52 | tmp.dir(function _tempDirCreated(err, path) {
|
53 | if (err) throw err;
|
54 |
|
55 | console.log("Dir: ", path);
|
56 | });
|
57 | ```
|
58 |
|
59 | If you want to cleanup the directory even when there are entries in it, then
|
60 | you can pass the `unsafeCleanup` option when creating it.
|
61 |
|
62 | ### Filename generation
|
63 |
|
64 | It is possible with this library to generate a unique filename in the specified
|
65 | directory.
|
66 |
|
67 | ```javascript
|
68 | var tmp = require('tmp');
|
69 |
|
70 | tmp.tmpName(function _tempNameGenerated(err, path) {
|
71 | if (err) throw err;
|
72 |
|
73 | console.log("Created temporary filename: ", path);
|
74 | });
|
75 | ```
|
76 |
|
77 | ## Advanced usage
|
78 |
|
79 | ### File creation
|
80 |
|
81 | Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
|
82 |
|
83 | ```javascript
|
84 | var tmp = require('tmp');
|
85 |
|
86 | tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
|
87 | if (err) throw err;
|
88 |
|
89 | console.log("File: ", path);
|
90 | console.log("Filedescriptor: ", fd);
|
91 | });
|
92 | ```
|
93 |
|
94 | ### Directory creation
|
95 |
|
96 | Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
|
97 |
|
98 | ```javascript
|
99 | var tmp = require('tmp');
|
100 |
|
101 | tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
|
102 | if (err) throw err;
|
103 |
|
104 | console.log("Dir: ", path);
|
105 | });
|
106 | ```
|
107 |
|
108 | ### mkstemps like
|
109 |
|
110 | Creates a new temporary directory with mode `0700` and filename like `/tmp/tmp-nk2J1u`.
|
111 |
|
112 | ```javascript
|
113 | var tmp = require('tmp');
|
114 |
|
115 | tmp.dir({ template: '/tmp/tmp-XXXXXX' }, function _tempDirCreated(err, path) {
|
116 | if (err) throw err;
|
117 |
|
118 | console.log("Dir: ", path);
|
119 | });
|
120 | ```
|
121 |
|
122 | ### Filename generation
|
123 |
|
124 | The `tmpName()` function accepts the `prefix`, `postfix`, `dir`, etc. parameters also:
|
125 |
|
126 | ```javascript
|
127 | var tmp = require('tmp');
|
128 |
|
129 | tmp.tmpName({ template: '/tmp/tmp-XXXXXX' }, function _tempNameGenerated(err, path) {
|
130 | if (err) throw err;
|
131 |
|
132 | console.log("Created temporary filename: ", path);
|
133 | });
|
134 | ```
|
135 |
|
136 | ## Graceful cleanup
|
137 |
|
138 | One may want to cleanup the temporary files even when an uncaught exception
|
139 | occurs. To enforce this, you can call the `setGracefulCleanup()` method:
|
140 |
|
141 | ```javascript
|
142 | var tmp = require('tmp');
|
143 |
|
144 | tmp.setGracefulCleanup();
|
145 | ```
|
146 |
|
147 | ## Options
|
148 |
|
149 | All options are optional :)
|
150 |
|
151 | * `mode`: the file mode to create with, it fallbacks to `0600` on file creation and `0700` on directory creation
|
152 | * `prefix`: the optional prefix, fallbacks to `tmp-` if not provided
|
153 | * `postfix`: the optional postfix, fallbacks to `.tmp` on file creation
|
154 | * `template`: [`mkstemps`][3] like filename template, no default
|
155 | * `dir`: the optional temporary directory, fallbacks to system default (guesses from environment)
|
156 | * `tries`: how many times should the function try to get a unique filename before giving up, default `3`
|
157 | * `keep`: signals that the temporary file or directory should not be deleted on exit, default is `false`, means delete
|
158 | * `unsafeCleanup`: recursively removes the created temporary directory, even when it's not empty. default is `false`
|
159 |
|
160 | [1]: http://nodejs.org/
|
161 | [2]: https://github.com/bruce/node-temp
|
162 | [3]: http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html
|