{"_id":"fsctl","_rev":"237563","name":"fsctl","description":"Native utilities for file manipulation, including locking and hole punching","dist-tags":{"latest":"2.0.0"},"maintainers":[{"name":"mafintosh","email":""}],"time":{"modified":"2023-03-24T16:39:55.000Z","created":"2021-02-26T15:49:55.316Z","2.0.0":"2022-05-17T12:50:56.837Z","1.0.0":"2021-02-26T16:19:46.253Z","0.0.0":"2021-02-26T15:49:55.316Z"},"users":{},"author":{"name":"Mathias Buus","url":"@mafintosh"},"repository":{"type":"git","url":"git+https://github.com/mafintosh/fsctl.git"},"versions":{"2.0.0":{"name":"fsctl","version":"2.0.0","description":"Native utilities for file manipulation, including locking and hole punching","main":"index.js","dependencies":{"napi-macros":"^2.0.0","node-gyp-build":"^4.2.3"},"devDependencies":{"brittle":"^2.3.1","minimist":"^1.2.6","nanobench":"^2.1.1","prebuildify":"^4.1.2","pretty-bytes":"^6.0.0","standard":"^17.0.0","tempy":"^3.0.0"},"scripts":{"test":"standard && brittle test/*.mjs","prebuild":"prebuildify --napi","install":"node-gyp-build"},"repository":{"type":"git","url":"git+https://github.com/mafintosh/fsctl.git"},"author":{"name":"Mathias Buus","url":"@mafintosh"},"license":"MIT","bugs":{"url":"https://github.com/mafintosh/fsctl/issues"},"homepage":"https://github.com/mafintosh/fsctl","gitHead":"6ba80620576d261427f8641c32f8d4d59bfe349a","_id":"fsctl@2.0.0","_nodeVersion":"16.15.0","_npmVersion":"8.5.5","dist":{"shasum":"6a25029aecd1a8bb287afbf9b3cc0029f173cede","size":81924,"noattachment":false,"key":"/fsctl/-/fsctl-2.0.0.tgz","tarball":"http://name.csiicloud.com:7001/fsctl/download/fsctl-2.0.0.tgz"},"_npmUser":{"name":"mafintosh","email":"mathiasbuus@gmail.com"},"directories":{},"maintainers":[{"name":"mafintosh","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/fsctl_2.0.0_1652791856668_0.5245928296757589"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-05-17T14:43:55.965Z","hasInstallScript":true,"publish_time":1652791856837,"_cnpm_publish_time":1652791856837},"1.0.0":{"name":"fsctl","version":"1.0.0","description":"Series of small native fd utils for manipulating file attributes and more","main":"index.js","dependencies":{"napi-macros":"^2.0.0","node-gyp-build":"^4.2.3"},"devDependencies":{"prebuildify":"^4.1.2","tape":"^4.9.2"},"scripts":{"test":"tape test.js","prebuild":"prebuildify --napi","prebuild-ia32":"prebuildify --napi --arch=ia32","install":"node-gyp-build"},"repository":{"type":"git","url":"git+https://github.com/mafintosh/fsctl.git"},"author":{"name":"Mathias Buus","url":"@mafintosh"},"license":"MIT","bugs":{"url":"https://github.com/mafintosh/fsctl/issues"},"homepage":"https://github.com/mafintosh/fsctl","gitHead":"381cc5d26f081c3ae582933459929753f3a8fe79","_id":"fsctl@1.0.0","_nodeVersion":"15.7.0","_npmVersion":"6.14.11","dist":{"shasum":"6c1fdd9f11bddba23d1ff6f3bf29881b10bd5dd8","size":353867,"noattachment":false,"key":"/fsctl/-/fsctl-1.0.0.tgz","tarball":"http://name.csiicloud.com:7001/fsctl/download/fsctl-1.0.0.tgz"},"_npmUser":{"name":"mafintosh","email":"mathiasbuus@gmail.com"},"directories":{},"maintainers":[{"name":"mafintosh","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/fsctl_1.0.0_1614356386039_0.5239934552360832"},"_hasShrinkwrap":false,"publish_time":1614356386253,"_cnpm_publish_time":1614356386253,"_cnpmcore_publish_time":"2021-12-17T00:25:21.082Z","hasInstallScript":true},"0.0.0":{"name":"fsctl","version":"0.0.0","description":"WIP - nothing to see here","main":"index.js","dependencies":{},"devDependencies":{},"repository":{"type":"git","url":"git+https://github.com/mafintosh/fsctl.git"},"author":{"name":"Mathias Buus","url":"@mafintosh"},"license":"MIT","bugs":{"url":"https://github.com/mafintosh/fsctl/issues"},"homepage":"https://github.com/mafintosh/fsctl","_id":"fsctl@0.0.0","_nodeVersion":"15.7.0","_npmVersion":"6.14.11","dist":{"shasum":"323e0a87ba74377300cca276438a359c26784463","size":1344,"noattachment":false,"key":"/fsctl/-/fsctl-0.0.0.tgz","tarball":"http://name.csiicloud.com:7001/fsctl/download/fsctl-0.0.0.tgz"},"_npmUser":{"name":"mafintosh","email":"mathiasbuus@gmail.com"},"directories":{},"maintainers":[{"name":"mafintosh","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/fsctl_0.0.0_1614354594953_0.9822255345832025"},"_hasShrinkwrap":false,"publish_time":1614354595316,"_cnpm_publish_time":1614354595316,"_cnpmcore_publish_time":"2021-12-17T00:25:21.321Z"}},"readme":"# fsctl\n\nNative utilities for file manipulation, including locking and hole punching.\n\n```\nnpm install fsctl\n```\n\n## Usage\n\nWrite to a file using an exclusive lock:\n\n``` js\nconst { open } = require('fs/promises')\nconst { lock, unlock } = require('fsctl')\n\nconst file = await open('file.txt', 'a+')\n\nawait lock(file.fd, { exclusive: true })\n\ntry {\n  await file.write('hello world')\n} finally {\n  unlock(file.fd)\n}\n```\n\n## API\n\n#### `await fsctl.lock(fd[, offset[, length]][, options])`\n\nRequest a process level lock on a file, resolving when the lock is granted. If another process holds the lock, the lock will not be granted until the other process either exits or releases the lock.\n\nTo lock only a portion of the file, `offset` and `length` may be passed. A `length` of `0` will request a lock from `offset` to the end of the file.\n\nNote that the lock is only advisory and there is nothing stopping another process from accessing the file by simply ignoring the lock.\n\nOptions include:\n\n```js\n{\n  // If `true`, request an exclusive lock, i.e. a write lock, on the file. By\n  // default, a shared lock, i.e. a read lock, is requested.\n  // Be aware that an exclusive lock can only be granted to files that are\n  // writable! A request for an exclusive lock on a read-only file is ignored \n  // and treated as a request for a shared lock.\n  exclusive: false\n}\n```\n\n#### `const granted = fsctl.tryLock(fd[, offset[, length]][, options])`\n\nRequest a process level lock on a file, returning `true` if the lock was granted or `false` if another process currently holds the lock.\n\nOptions are the same as `fsctl.lock()`.\n\n#### `fsctl.unlock(fd[, offset[, length]])`\n\nRelease a process level lock on a file.\n\n#### `await fsctl.punchHole(fd, offset, length)`\n\nPunch a hole in a file at `offset` for `length` bytes. On file systems that support sparse files, holes will take up no physical space.\n\nOn Windows, the file must first be marked sparse using `fsctl.sparse(fd)`. Otherwise, zeros will be explicitly written to the hole.\n\nOn macOS, the hole must be aligned to block boundaries as the call will otherwise fail.\n\n#### `await fsctl.sparse(fd)`\n\nMark a file as sparse. On Windows, this operation is required before holes can be punched in the file. On other systems, this operation has no effect.\n\n## License\n\nMIT\n","_attachments":{},"homepage":"https://github.com/mafintosh/fsctl","bugs":{"url":"https://github.com/mafintosh/fsctl/issues"},"license":"MIT"}