3 A simple temporary file and directory creator for [node.js.][1]
5 [![Build Status](https://secure.travis-ci.org/raszi/node-tmp.png?branch=master)](http://travis-ci.org/raszi/node-tmp)
9 This is a [widely used library][2] to create temporary files and directories
10 in a [node.js][1] environment.
12 Tmp offers both an asynchronous and a synchronous API. For all API calls, all
13 the parameters are optional.
15 Tmp uses crypto for determining random file names, or, when using templates,
16 a six letter random identifier. And just in case that you do not have that much
17 entropy left on your system, Tmp will fall back to pseudo random numbers.
19 You can set whether you want to remove the temporary file on process exit or
20 not, and the destination directory can also be set.
30 ### Asynchronous file creation
32 Simple temporary file creation, the file will be closed and unlinked on process exit.
35 var tmp = require('tmp');
37 tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
40 console.log("File: ", path);
41 console.log("Filedescriptor: ", fd);
43 // If we don't need the file anymore we could manually call the cleanupCallback
44 // But that is not necessary if we didn't pass the keep option because the library
45 // will clean after itself.
50 ### Synchronous file creation
52 A synchronous version of the above.
55 var tmp = require('tmp');
57 var tmpobj = tmp.fileSync();
58 console.log("File: ", tmpobj.name);
59 console.log("Filedescriptor: ", tmpobj.fd);
61 // If we don't need the file anymore we could manually call the removeCallback
62 // But that is not necessary if we didn't pass the keep option because the library
63 // will clean after itself.
64 tmpobj.removeCallback();
67 Note that this might throw an exception if either the maximum limit of retries
68 for creating a temporary name fails, or, in case that you do not have the permission
69 to write to the directory where the temporary file should be created in.
71 ### Asynchronous directory creation
73 Simple temporary directory creation, it will be removed on process exit.
75 If the directory still contains items on process exit, then it won't be removed.
78 var tmp = require('tmp');
80 tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
83 console.log("Dir: ", path);
90 If you want to cleanup the directory even when there are entries in it, then
91 you can pass the `unsafeCleanup` option when creating it.
93 ### Synchronous directory creation
95 A synchronous version of the above.
98 var tmp = require('tmp');
100 var tmpobj = tmp.dirSync();
101 console.log("Dir: ", tmpobj.name);
103 tmpobj.removeCallback();
106 Note that this might throw an exception if either the maximum limit of retries
107 for creating a temporary name fails, or, in case that you do not have the permission
108 to write to the directory where the temporary directory should be created in.
110 ### Asynchronous filename generation
112 It is possible with this library to generate a unique filename in the specified
116 var tmp = require('tmp');
118 tmp.tmpName(function _tempNameGenerated(err, path) {
121 console.log("Created temporary filename: ", path);
125 ### Synchronous filename generation
127 A synchronous version of the above.
130 var tmp = require('tmp');
132 var name = tmp.tmpNameSync();
133 console.log("Created temporary filename: ", name);
138 ### Asynchronous file creation
140 Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
143 var tmp = require('tmp');
145 tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
148 console.log("File: ", path);
149 console.log("Filedescriptor: ", fd);
153 ### Synchronous file creation
155 A synchronous version of the above.
158 var tmp = require('tmp');
160 var tmpobj = tmp.fileSync({ mode: 0644, prefix: 'prefix-', postfix: '.txt' });
161 console.log("File: ", tmpobj.name);
162 console.log("Filedescriptor: ", tmpobj.fd);
165 ### Asynchronous directory creation
167 Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
170 var tmp = require('tmp');
172 tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
175 console.log("Dir: ", path);
179 ### Synchronous directory creation
181 Again, a synchronous version of the above.
184 var tmp = require('tmp');
186 var tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
187 console.log("Dir: ", tmpobj.name);
190 ### mkstemps like, asynchronously
192 Creates a new temporary directory with mode `0700` and filename like `/tmp/tmp-nk2J1u`.
195 var tmp = require('tmp');
197 tmp.dir({ template: '/tmp/tmp-XXXXXX' }, function _tempDirCreated(err, path) {
200 console.log("Dir: ", path);
204 ### mkstemps like, synchronously
206 This will behave similarly to the asynchronous version.
209 var tmp = require('tmp');
211 var tmpobj = tmp.dirSync({ template: '/tmp/tmp-XXXXXX' });
212 console.log("Dir: ", tmpobj.name);
215 ### Asynchronous filename generation
217 The `tmpName()` function accepts the `prefix`, `postfix`, `dir`, etc. parameters also:
220 var tmp = require('tmp');
222 tmp.tmpName({ template: '/tmp/tmp-XXXXXX' }, function _tempNameGenerated(err, path) {
225 console.log("Created temporary filename: ", path);
229 ### Synchronous filename generation
231 The `tmpNameSync()` function works similarly to `tmpName()`.
234 var tmp = require('tmp');
235 var tmpname = tmp.tmpNameSync({ template: '/tmp/tmp-XXXXXX' });
236 console.log("Created temporary filename: ", tmpname);
241 One may want to cleanup the temporary files even when an uncaught exception
242 occurs. To enforce this, you can call the `setGracefulCleanup()` method:
245 var tmp = require('tmp');
247 tmp.setGracefulCleanup();
252 All options are optional :)
254 * `mode`: the file mode to create with, it fallbacks to `0600` on file creation and `0700` on directory creation
255 * `prefix`: the optional prefix, fallbacks to `tmp-` if not provided
256 * `postfix`: the optional postfix, fallbacks to `.tmp` on file creation
257 * `template`: [`mkstemps`][3] like filename template, no default
258 * `dir`: the optional temporary directory, fallbacks to system default (guesses from environment)
259 * `tries`: how many times should the function try to get a unique filename before giving up, default `3`
260 * `keep`: signals that the temporary file or directory should not be deleted on exit, default is `false`, means delete
261 * Please keep in mind that it is recommended in this case to call the provided `cleanupCallback` function manually.
262 * `unsafeCleanup`: recursively removes the created temporary directory, even when it's not empty. default is `false`
264 [1]: http://nodejs.org/
265 [2]: https://www.npmjs.com/browse/depended/tmp
266 [3]: http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html