www.aleph1.co.uk Git - yaffs-website/blob - node_modules/tmp/README.md

   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 This is a [widely used library][2] to create temporary files and directories
  10 in a [node.js][1] environment.
  11
  12 Tmp offers both an asynchronous and a synchronous API. For all API calls, all
  13 the parameters are optional.
  14
  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.
  18
  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.
  21
  22 ## How to install
  23
  24 ```bash
  25 npm install tmp
  26 ```
  27
  28 ## Usage
  29
  30 ### Asynchronous file creation
  31
  32 Simple temporary file creation, the file will be closed and unlinked on process exit.
  33
  34 ```javascript
  35 var tmp = require('tmp');
  36
  37 tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
  38   if (err) throw err;
  39
  40   console.log("File: ", path);
  41   console.log("Filedescriptor: ", fd);
  42
  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.
  46   cleanupCallback();
  47 });
  48 ```
  49
  50 ### Synchronous file creation
  51
  52 A synchronous version of the above.
  53
  54 ```javascript
  55 var tmp = require('tmp');
  56
  57 var tmpobj = tmp.fileSync();
  58 console.log("File: ", tmpobj.name);
  59 console.log("Filedescriptor: ", tmpobj.fd);
  60
  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();
  65 ```
  66
  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.
  70
  71 ### Asynchronous directory creation
  72
  73 Simple temporary directory creation, it will be removed on process exit.
  74
  75 If the directory still contains items on process exit, then it won't be removed.
  76
  77 ```javascript
  78 var tmp = require('tmp');
  79
  80 tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
  81   if (err) throw err;
  82
  83   console.log("Dir: ", path);
  84
  85   // Manual cleanup
  86   cleanupCallback();
  87 });
  88 ```
  89
  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.
  92
  93 ### Synchronous directory creation
  94
  95 A synchronous version of the above.
  96
  97 ```javascript
  98 var tmp = require('tmp');
  99
 100 var tmpobj = tmp.dirSync();
 101 console.log("Dir: ", tmpobj.name);
 102 // Manual cleanup
 103 tmpobj.removeCallback();
 104 ```
 105
 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.
 109
 110 ### Asynchronous filename generation
 111
 112 It is possible with this library to generate a unique filename in the specified
 113 directory.
 114
 115 ```javascript
 116 var tmp = require('tmp');
 117
 118 tmp.tmpName(function _tempNameGenerated(err, path) {
 119     if (err) throw err;
 120
 121     console.log("Created temporary filename: ", path);
 122 });
 123 ```
 124
 125 ### Synchronous filename generation
 126
 127 A synchronous version of the above.
 128
 129 ```javascript
 130 var tmp = require('tmp');
 131
 132 var name = tmp.tmpNameSync();
 133 console.log("Created temporary filename: ", name);
 134 ```
 135
 136 ## Advanced usage
 137
 138 ### Asynchronous file creation
 139
 140 Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
 141
 142 ```javascript
 143 var tmp = require('tmp');
 144
 145 tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
 146   if (err) throw err;
 147
 148   console.log("File: ", path);
 149   console.log("Filedescriptor: ", fd);
 150 });
 151 ```
 152
 153 ### Synchronous file creation
 154
 155 A synchronous version of the above.
 156
 157 ```javascript
 158 var tmp = require('tmp');
 159
 160 var tmpobj = tmp.fileSync({ mode: 0644, prefix: 'prefix-', postfix: '.txt' });
 161 console.log("File: ", tmpobj.name);
 162 console.log("Filedescriptor: ", tmpobj.fd);
 163 ```
 164
 165 ### Asynchronous directory creation
 166
 167 Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
 168
 169 ```javascript
 170 var tmp = require('tmp');
 171
 172 tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
 173   if (err) throw err;
 174
 175   console.log("Dir: ", path);
 176 });
 177 ```
 178
 179 ### Synchronous directory creation
 180
 181 Again, a synchronous version of the above.
 182
 183 ```javascript
 184 var tmp = require('tmp');
 185
 186 var tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
 187 console.log("Dir: ", tmpobj.name);
 188 ```
 189
 190 ### mkstemps like, asynchronously
 191
 192 Creates a new temporary directory with mode `0700` and filename like `/tmp/tmp-nk2J1u`.
 193
 194 ```javascript
 195 var tmp = require('tmp');
 196
 197 tmp.dir({ template: '/tmp/tmp-XXXXXX' }, function _tempDirCreated(err, path) {
 198   if (err) throw err;
 199
 200   console.log("Dir: ", path);
 201 });
 202 ```
 203
 204 ### mkstemps like, synchronously
 205
 206 This will behave similarly to the asynchronous version.
 207
 208 ```javascript
 209 var tmp = require('tmp');
 210
 211 var tmpobj = tmp.dirSync({ template: '/tmp/tmp-XXXXXX' });
 212 console.log("Dir: ", tmpobj.name);
 213 ```
 214
 215 ### Asynchronous filename generation
 216
 217 The `tmpName()` function accepts the `prefix`, `postfix`, `dir`, etc. parameters also:
 218
 219 ```javascript
 220 var tmp = require('tmp');
 221
 222 tmp.tmpName({ template: '/tmp/tmp-XXXXXX' }, function _tempNameGenerated(err, path) {
 223     if (err) throw err;
 224
 225     console.log("Created temporary filename: ", path);
 226 });
 227 ```
 228
 229 ### Synchronous filename generation
 230
 231 The `tmpNameSync()` function works similarly to `tmpName()`.
 232
 233 ```javascript
 234 var tmp = require('tmp');
 235 var tmpname = tmp.tmpNameSync({ template: '/tmp/tmp-XXXXXX' });
 236 console.log("Created temporary filename: ", tmpname);
 237 ```
 238
 239 ## Graceful cleanup
 240
 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:
 243
 244 ```javascript
 245 var tmp = require('tmp');
 246
 247 tmp.setGracefulCleanup();
 248 ```
 249
 250 ## Options
 251
 252 All options are optional :)
 253
 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`
 263
 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