.config/coc/extensions/node_modules/coc-prettier/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://travis-ci.org/raszi/node-tmp.svg?branch=master)](https://travis-ci.org/raszi/node-tmp)
   6 [![Dependencies](https://david-dm.org/raszi/node-tmp.svg)](https://david-dm.org/raszi/node-tmp)
   7 [![npm version](https://badge.fury.io/js/tmp.svg)](https://badge.fury.io/js/tmp)
   8 [![API documented](https://img.shields.io/badge/API-documented-brightgreen.svg)](https://raszi.github.io/node-tmp/)
   9 [![Known Vulnerabilities](https://snyk.io/test/npm/tmp/badge.svg)](https://snyk.io/test/npm/tmp)
  10
  11 ## About
  12
  13 This is a [widely used library][2] to create temporary files and directories
  14 in a [node.js][1] environment.
  15
  16 Tmp offers both an asynchronous and a synchronous API. For all API calls, all
  17 the parameters are optional. There also exists a promisified version of the
  18 API, see (5) under references below.
  19
  20 Tmp uses crypto for determining random file names, or, when using templates,
  21 a six letter random identifier. And just in case that you do not have that much
  22 entropy left on your system, Tmp will fall back to pseudo random numbers.
  23
  24 You can set whether you want to remove the temporary file on process exit or
  25 not, and the destination directory can also be set.
  26
  27 ## How to install
  28
  29 ```bash
  30 npm install tmp
  31 ```
  32
  33 ## Usage
  34
  35 Please also check [API docs][4].
  36
  37 ### Asynchronous file creation
  38
  39 Simple temporary file creation, the file will be closed and unlinked on process exit.
  40
  41 ```javascript
  42 var tmp = require('tmp');
  43
  44 tmp.file(function _tempFileCreated(err, path, fd, cleanupCallback) {
  45   if (err) throw err;
  46
  47   console.log('File: ', path);
  48   console.log('Filedescriptor: ', fd);
  49
  50   // If we don't need the file anymore we could manually call the cleanupCallback
  51   // But that is not necessary if we didn't pass the keep option because the library
  52   // will clean after itself.
  53   cleanupCallback();
  54 });
  55 ```
  56
  57 ### Synchronous file creation
  58
  59 A synchronous version of the above.
  60
  61 ```javascript
  62 var tmp = require('tmp');
  63
  64 var tmpobj = tmp.fileSync();
  65 console.log('File: ', tmpobj.name);
  66 console.log('Filedescriptor: ', tmpobj.fd);
  67
  68 // If we don't need the file anymore we could manually call the removeCallback
  69 // But that is not necessary if we didn't pass the keep option because the library
  70 // will clean after itself.
  71 tmpobj.removeCallback();
  72 ```
  73
  74 Note that this might throw an exception if either the maximum limit of retries
  75 for creating a temporary name fails, or, in case that you do not have the permission
  76 to write to the directory where the temporary file should be created in.
  77
  78 ### Asynchronous directory creation
  79
  80 Simple temporary directory creation, it will be removed on process exit.
  81
  82 If the directory still contains items on process exit, then it won't be removed.
  83
  84 ```javascript
  85 var tmp = require('tmp');
  86
  87 tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
  88   if (err) throw err;
  89
  90   console.log('Dir: ', path);
  91
  92   // Manual cleanup
  93   cleanupCallback();
  94 });
  95 ```
  96
  97 If you want to cleanup the directory even when there are entries in it, then
  98 you can pass the `unsafeCleanup` option when creating it.
  99
 100 ### Synchronous directory creation
 101
 102 A synchronous version of the above.
 103
 104 ```javascript
 105 var tmp = require('tmp');
 106
 107 var tmpobj = tmp.dirSync();
 108 console.log('Dir: ', tmpobj.name);
 109 // Manual cleanup
 110 tmpobj.removeCallback();
 111 ```
 112
 113 Note that this might throw an exception if either the maximum limit of retries
 114 for creating a temporary name fails, or, in case that you do not have the permission
 115 to write to the directory where the temporary directory should be created in.
 116
 117 ### Asynchronous filename generation
 118
 119 It is possible with this library to generate a unique filename in the specified
 120 directory.
 121
 122 ```javascript
 123 var tmp = require('tmp');
 124
 125 tmp.tmpName(function _tempNameGenerated(err, path) {
 126     if (err) throw err;
 127
 128     console.log('Created temporary filename: ', path);
 129 });
 130 ```
 131
 132 ### Synchronous filename generation
 133
 134 A synchronous version of the above.
 135
 136 ```javascript
 137 var tmp = require('tmp');
 138
 139 var name = tmp.tmpNameSync();
 140 console.log('Created temporary filename: ', name);
 141 ```
 142
 143 ## Advanced usage
 144
 145 ### Asynchronous file creation
 146
 147 Creates a file with mode `0644`, prefix will be `prefix-` and postfix will be `.txt`.
 148
 149 ```javascript
 150 var tmp = require('tmp');
 151
 152 tmp.file({ mode: 0644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
 153   if (err) throw err;
 154
 155   console.log('File: ', path);
 156   console.log('Filedescriptor: ', fd);
 157 });
 158 ```
 159
 160 ### Synchronous file creation
 161
 162 A synchronous version of the above.
 163
 164 ```javascript
 165 var tmp = require('tmp');
 166
 167 var tmpobj = tmp.fileSync({ mode: 0644, prefix: 'prefix-', postfix: '.txt' });
 168 console.log('File: ', tmpobj.name);
 169 console.log('Filedescriptor: ', tmpobj.fd);
 170 ```
 171
 172 ### Controlling the Descriptor
 173
 174 As a side effect of creating a unique file `tmp` gets a file descriptor that is
 175 returned to the user as the `fd` parameter.  The descriptor may be used by the
 176 application and is closed when the `removeCallback` is invoked.
 177
 178 In some use cases the application does not need the descriptor, needs to close it
 179 without removing the file, or needs to remove the file without closing the
 180 descriptor.  Two options control how the descriptor is managed:
 181
 182 * `discardDescriptor` - if `true` causes `tmp` to close the descriptor after the file
 183   is created.  In this case the `fd` parameter is undefined.
 184 * `detachDescriptor` - if `true` causes `tmp` to return the descriptor in the `fd`
 185   parameter, but it is the application's responsibility to close it when it is no
 186   longer needed.
 187
 188 ```javascript
 189 var tmp = require('tmp');
 190
 191 tmp.file({ discardDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
 192   if (err) throw err;
 193   // fd will be undefined, allowing application to use fs.createReadStream(path)
 194   // without holding an unused descriptor open.
 195 });
 196 ```
 197
 198 ```javascript
 199 var tmp = require('tmp');
 200
 201 tmp.file({ detachDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
 202   if (err) throw err;
 203
 204   cleanupCallback();
 205   // Application can store data through fd here; the space used will automatically
 206   // be reclaimed by the operating system when the descriptor is closed or program
 207   // terminates.
 208 });
 209 ```
 210
 211 ### Asynchronous directory creation
 212
 213 Creates a directory with mode `0755`, prefix will be `myTmpDir_`.
 214
 215 ```javascript
 216 var tmp = require('tmp');
 217
 218 tmp.dir({ mode: 0750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
 219   if (err) throw err;
 220
 221   console.log('Dir: ', path);
 222 });
 223 ```
 224
 225 ### Synchronous directory creation
 226
 227 Again, a synchronous version of the above.
 228
 229 ```javascript
 230 var tmp = require('tmp');
 231
 232 var tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
 233 console.log('Dir: ', tmpobj.name);
 234 ```
 235
 236 ### mkstemp like, asynchronously
 237
 238 Creates a new temporary directory with mode `0700` and filename like `/tmp/tmp-nk2J1u`.
 239
 240 ```javascript
 241 var tmp = require('tmp');
 242
 243 tmp.dir({ template: '/tmp/tmp-XXXXXX' }, function _tempDirCreated(err, path) {
 244   if (err) throw err;
 245
 246   console.log('Dir: ', path);
 247 });
 248 ```
 249
 250 ### mkstemp like, synchronously
 251
 252 This will behave similarly to the asynchronous version.
 253
 254 ```javascript
 255 var tmp = require('tmp');
 256
 257 var tmpobj = tmp.dirSync({ template: '/tmp/tmp-XXXXXX' });
 258 console.log('Dir: ', tmpobj.name);
 259 ```
 260
 261 ### Asynchronous filename generation
 262
 263 The `tmpName()` function accepts the `prefix`, `postfix`, `dir`, etc. parameters also:
 264
 265 ```javascript
 266 var tmp = require('tmp');
 267
 268 tmp.tmpName({ template: '/tmp/tmp-XXXXXX' }, function _tempNameGenerated(err, path) {
 269     if (err) throw err;
 270
 271     console.log('Created temporary filename: ', path);
 272 });
 273 ```
 274
 275 ### Synchronous filename generation
 276
 277 The `tmpNameSync()` function works similarly to `tmpName()`.
 278
 279 ```javascript
 280 var tmp = require('tmp');
 281 var tmpname = tmp.tmpNameSync({ template: '/tmp/tmp-XXXXXX' });
 282 console.log('Created temporary filename: ', tmpname);
 283 ```
 284
 285 ## Graceful cleanup
 286
 287 One may want to cleanup the temporary files even when an uncaught exception
 288 occurs. To enforce this, you can call the `setGracefulCleanup()` method:
 289
 290 ```javascript
 291 var tmp = require('tmp');
 292
 293 tmp.setGracefulCleanup();
 294 ```
 295
 296 ## Options
 297
 298 All options are optional :)
 299
 300   * `mode`: the file mode to create with, it fallbacks to `0600` on file creation and `0700` on directory creation
 301   * `prefix`: the optional prefix, fallbacks to `tmp-` if not provided
 302   * `postfix`: the optional postfix, fallbacks to `.tmp` on file creation
 303   * `template`: [`mkstemp`][3] like filename template, no default
 304   * `dir`: the optional temporary directory, fallbacks to system default (guesses from environment)
 305   * `tries`: how many times should the function try to get a unique filename before giving up, default `3`
 306   * `keep`: signals that the temporary file or directory should not be deleted on exit, default is `false`, means delete
 307     * Please keep in mind that it is recommended in this case to call the provided `cleanupCallback` function manually.
 308   * `unsafeCleanup`: recursively removes the created temporary directory, even when it's not empty. default is `false`
 309
 310 [1]: http://nodejs.org/
 311 [2]: https://www.npmjs.com/browse/depended/tmp
 312 [3]: http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html
 313 [4]: https://raszi.github.io/node-tmp/
 314 [5]: https://github.com/benjamingr/tmp-promise