forked from raszi/node-tmp
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
347 lines (282 loc) · 15.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>JSDoc: Home</title>
<script src="scripts/prettify/prettify.js"> </script>
<script src="scripts/prettify/lang-css.js"> </script>
<!--[if lt IE 9]>
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
<link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>
<body>
<div id="main">
<h1 class="page-title">Home</h1>
<h3> </h3>
<section>
<article><h1>Tmp</h1>
<p>A simple temporary file and directory creator for <a href="http://nodejs.org/">node.js.</a></p>
<p><a href="https://github.com/raszi/node-tmp/actions/workflows/node.js.yml"><img src="https://img.shields.io/github/actions/workflow/status/raszi/node-tmp/node.js.yml?branch=master" alt="Build Status"></a>
<a href="https://libraries.io/github/raszi/node-tmp"><img src="https://img.shields.io/librariesio/github/raszi/node-tmp" alt="Dependencies"></a>
<a href="https://badge.fury.io/js/tmp"><img src="https://badge.fury.io/js/tmp.svg" alt="npm version"></a>
<a href="https://raszi.github.io/node-tmp/"><img src="https://img.shields.io/badge/API-documented-brightgreen.svg" alt="API documented"></a>
<a href="https://snyk.io/test/npm/tmp"><img src="https://snyk.io/test/npm/tmp/badge.svg" alt="Known Vulnerabilities"></a></p>
<h2>About</h2>
<p>This is a <a href="https://www.npmjs.com/browse/depended/tmp">widely used library</a> to create temporary files and directories
in a <a href="http://nodejs.org/">node.js</a> environment.</p>
<p>Tmp offers both an asynchronous and a synchronous API. For all API calls, all
the parameters are optional. There also exists a promisified version of the
API, see <a href="https://github.com/benjamingr/tmp-promise">tmp-promise</a>.</p>
<p>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.</p>
<p>You can set whether you want to remove the temporary file on process exit or
not.</p>
<p>If you do not want to store your temporary directories and files in the
standard OS temporary directory, then you are free to override that as well.</p>
<h2>An Important Note on Previously Undocumented Breaking Changes</h2>
<p>All breaking changes that had been introduced, i.e.</p>
<ul>
<li>tmpdir must be located under the system defined tmpdir root.</li>
<li>Spaces being collapsed into single spaces</li>
<li>Removal of all single and double quote characters</li>
</ul>
<p>have been reverted in v0.2.2 and tmp should now behave as it did before the
introduction of these breaking changes.</p>
<p>Other breaking changes, i.e.</p>
<ul>
<li>template must be relative to tmpdir</li>
<li>name must be relative to tmpdir</li>
<li>dir option must be relative to tmpdir</li>
</ul>
<p>are still in place.</p>
<p>In order to override the system's tmpdir, you will have to use the newly
introduced tmpdir option.</p>
<h2>An Important Note on Compatibility</h2>
<p>See the <a href="./CHANGELOG.md">CHANGELOG</a> for more information.</p>
<h3>Version 0.2.2</h3>
<p>Since version 0.2.2, all support for node version <= 12 has been dropped.</p>
<h3>Version 0.1.0</h3>
<p>Since version 0.1.0, all support for node versions < 0.10.0 has been dropped.</p>
<p>Most importantly, any support for earlier versions of node-tmp was also dropped.</p>
<p>If you still require node versions < 0.10.0, then you must limit your node-tmp
dependency to versions below 0.1.0.</p>
<h3>Version 0.0.33</h3>
<p>Since version 0.0.33, all support for node versions < 0.8 has been dropped.</p>
<p>If you still require node version 0.8, then you must limit your node-tmp
dependency to version 0.0.33.</p>
<p>For node versions < 0.8 you must limit your node-tmp dependency to
versions < 0.0.33.</p>
<h2>How to install</h2>
<pre class="prettyprint source lang-bash"><code>npm install tmp
</code></pre>
<h2>Usage</h2>
<p>Please also check <a href="https://raszi.github.io/node-tmp/">API docs</a>.</p>
<h2>Graceful cleanup</h2>
<p>If graceful cleanup is set, tmp will remove all controlled temporary objects on process exit, otherwise the temporary objects will remain in place, waiting to be cleaned up on system restart or otherwise scheduled temporary object removal.</p>
<p>To enforce this, you can call the <code>setGracefulCleanup()</code> method:</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.setGracefulCleanup();
</code></pre>
<h3>Asynchronous file creation</h3>
<p>Simple temporary file creation, the file will be closed and unlinked on process exit.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
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();
});
</code></pre>
<h3>Synchronous file creation</h3>
<p>A synchronous version of the above.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const 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();
</code></pre>
<p>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.</p>
<h3>Asynchronous directory creation</h3>
<p>Simple temporary directory creation, it will be removed on process exit.</p>
<p>If the directory still contains items on process exit, then it won't be removed.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.dir(function _tempDirCreated(err, path, cleanupCallback) {
if (err) throw err;
console.log('Dir: ', path);
// Manual cleanup
cleanupCallback();
});
</code></pre>
<p>If you want to cleanup the directory even when there are entries in it, then
you can pass the <code>unsafeCleanup</code> option when creating it.</p>
<h3>Synchronous directory creation</h3>
<p>A synchronous version of the above.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const tmpobj = tmp.dirSync();
console.log('Dir: ', tmpobj.name);
// Manual cleanup
tmpobj.removeCallback();
</code></pre>
<p>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.</p>
<h3>Asynchronous filename generation</h3>
<p>It is possible with this library to generate a unique filename in the specified
directory.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.tmpName(function _tempNameGenerated(err, path) {
if (err) throw err;
console.log('Created temporary filename: ', path);
});
</code></pre>
<h3>Synchronous filename generation</h3>
<p>A synchronous version of the above.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const name = tmp.tmpNameSync();
console.log('Created temporary filename: ', name);
</code></pre>
<h2>Advanced usage</h2>
<h3>Asynchronous file creation</h3>
<p>Creates a file with mode <code>0644</code>, prefix will be <code>prefix-</code> and postfix will be <code>.txt</code>.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.file({ mode: 0o644, prefix: 'prefix-', postfix: '.txt' }, function _tempFileCreated(err, path, fd) {
if (err) throw err;
console.log('File: ', path);
console.log('Filedescriptor: ', fd);
});
</code></pre>
<h3>Synchronous file creation</h3>
<p>A synchronous version of the above.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const tmpobj = tmp.fileSync({ mode: 0o644, prefix: 'prefix-', postfix: '.txt' });
console.log('File: ', tmpobj.name);
console.log('Filedescriptor: ', tmpobj.fd);
</code></pre>
<h3>Controlling the Descriptor</h3>
<p>As a side effect of creating a unique file <code>tmp</code> gets a file descriptor that is
returned to the user as the <code>fd</code> parameter. The descriptor may be used by the
application and is closed when the <code>removeCallback</code> is invoked.</p>
<p>In some use cases the application does not need the descriptor, needs to close it
without removing the file, or needs to remove the file without closing the
descriptor. Two options control how the descriptor is managed:</p>
<ul>
<li><code>discardDescriptor</code> - if <code>true</code> causes <code>tmp</code> to close the descriptor after the file
is created. In this case the <code>fd</code> parameter is undefined.</li>
<li><code>detachDescriptor</code> - if <code>true</code> causes <code>tmp</code> to return the descriptor in the <code>fd</code>
parameter, but it is the application's responsibility to close it when it is no
longer needed.</li>
</ul>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.file({ discardDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
if (err) throw err;
// fd will be undefined, allowing application to use fs.createReadStream(path)
// without holding an unused descriptor open.
});
</code></pre>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.file({ detachDescriptor: true }, function _tempFileCreated(err, path, fd, cleanupCallback) {
if (err) throw err;
cleanupCallback();
// Application can store data through fd here; the space used will automatically
// be reclaimed by the operating system when the descriptor is closed or program
// terminates.
});
</code></pre>
<h3>Asynchronous directory creation</h3>
<p>Creates a directory with mode <code>0755</code>, prefix will be <code>myTmpDir_</code>.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.dir({ mode: 0o750, prefix: 'myTmpDir_' }, function _tempDirCreated(err, path) {
if (err) throw err;
console.log('Dir: ', path);
});
</code></pre>
<h3>Synchronous directory creation</h3>
<p>Again, a synchronous version of the above.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const tmpobj = tmp.dirSync({ mode: 0750, prefix: 'myTmpDir_' });
console.log('Dir: ', tmpobj.name);
</code></pre>
<h3>mkstemp like, asynchronously</h3>
<p>Creates a new temporary directory with mode <code>0700</code> and filename like <code>/tmp/tmp-nk2J1u</code>.</p>
<p>IMPORTANT NOTE: template no longer accepts a path. Use the dir option instead if you
require tmp to create your temporary filesystem object in a different place than the
default <code>tmp.tmpdir</code>.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
tmp.dir({ template: 'tmp-XXXXXX' }, function _tempDirCreated(err, path) {
if (err) throw err;
console.log('Dir: ', path);
});
</code></pre>
<h3>mkstemp like, synchronously</h3>
<p>This will behave similarly to the asynchronous version.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const tmpobj = tmp.dirSync({ template: 'tmp-XXXXXX' });
console.log('Dir: ', tmpobj.name);
</code></pre>
<h3>Asynchronous filename generation</h3>
<p>Using <code>tmpName()</code> you can create temporary file names asynchronously.
The function accepts all standard options, e.g. <code>prefix</code>, <code>postfix</code>, <code>dir</code>, and so on.</p>
<p>You can also leave out the options altogether and just call the function with a callback as first parameter.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const options = {};
tmp.tmpName(options, function _tempNameGenerated(err, path) {
if (err) throw err;
console.log('Created temporary filename: ', path);
});
</code></pre>
<h3>Synchronous filename generation</h3>
<p>The <code>tmpNameSync()</code> function works similarly to <code>tmpName()</code>.
Again, you can leave out the options altogether and just invoke the function without any parameters.</p>
<pre class="prettyprint source lang-javascript"><code>const tmp = require('tmp');
const options = {};
const tmpname = tmp.tmpNameSync(options);
console.log('Created temporary filename: ', tmpname);
</code></pre>
<h2>Options</h2>
<p>All options are optional :)</p>
<ul>
<li><code>name</code>: a fixed name that overrides random name generation, the name must be relative and must not contain path segments</li>
<li><code>mode</code>: the file mode to create with, falls back to <code>0o600</code> on file creation and <code>0o700</code> on directory creation</li>
<li><code>prefix</code>: the optional prefix, defaults to <code>tmp</code></li>
<li><code>postfix</code>: the optional postfix</li>
<li><code>template</code>: <a href="http://www.kernel.org/doc/man-pages/online/pages/man3/mkstemp.3.html"><code>mkstemp</code></a> like filename template, no default, must include <code>XXXXXX</code> once for random name generation, e.g.
'foo-bar-XXXXXX'.</li>
<li><code>dir</code>: the optional temporary directory that must be relative to the system's default temporary directory.
absolute paths are fine as long as they point to a location under the system's default temporary directory.
Any directories along the so specified path must exist, otherwise a ENOENT error will be thrown upon access,
as tmp will not check the availability of the path, nor will it establish the requested path for you.</li>
<li><code>tmpdir</code>: allows you to override the system's root tmp directory</li>
<li><code>tries</code>: how many times should the function try to get a unique filename before giving up, default <code>3</code></li>
<li><code>keep</code>: signals that the temporary file or directory should not be deleted on exit, default is <code>false</code>
<ul>
<li>In order to clean up, you will have to call the provided <code>cleanupCallback</code> function manually.</li>
</ul>
</li>
<li><code>unsafeCleanup</code>: recursively removes the created temporary directory, even when it's not empty. default is <code>false</code></li>
<li><code>detachDescriptor</code>: detaches the file descriptor, caller is responsible for closing the file, tmp will no longer try closing the file during garbage collection</li>
<li><code>discardDescriptor</code>: discards the file descriptor (closes file, fd is -1), tmp will no longer try closing the file during garbage collection</li>
</ul></article>
</section>
</div>
<nav>
<h2><a href="index.html">Home</a></h2><h3>Global</h3><ul><li><a href="global.html#dir">dir</a></li><li><a href="global.html#dirSync">dirSync</a></li><li><a href="global.html#file">file</a></li><li><a href="global.html#fileSync">fileSync</a></li><li><a href="global.html#setGracefulCleanup">setGracefulCleanup</a></li><li><a href="global.html#tmpName">tmpName</a></li><li><a href="global.html#tmpNameSync">tmpNameSync</a></li></ul>
</nav>
<br class="clear">
<footer>
Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.2</a> on Wed Feb 28 2024 18:30:02 GMT-0700 (Mountain Standard Time)
</footer>
<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>