{ "content": [ { "type": "text", "text": "# lockfile(1) (man)\n\n**Summary:** lockfile - conditional semaphore-file creator\n\n**Synopsis:** lockfile -sleeptime | -r retries |\n-l locktimeout | -s suspend | -! | -ml | -mu | filename ...\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| — | — | — | |\n\n## Examples\n\n- `Suppose you want to make sure that access to the file \"important\" is serialised, i.e., no`\n- `more than one program or shell script should be allowed to access it. For simplicity's sake,`\n- `let's suppose that it is a shell script. In this case you could solve it like this:`\n- `...`\n- `lockfile important.lock`\n- `...`\n- `access\"important\"toyourheartscontent`\n- `...`\n- `rm -f important.lock`\n- `...`\n- `Now if all the scripts that access \"important\" follow this guideline, you will be assured`\n- `that at most one script will be executing between the `lockfile' and the `rm' commands.`\n\n## See Also\n\n- rm(1)\n- mail(1)\n- sendmail(8)\n- procmail(1)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (3 lines)\n- **DESCRIPTION** (28 lines) — 2 subsections\n - Mailbox locks (2 lines)\n - -mu (1 lines)\n- **EXAMPLES** (13 lines)\n- **ENVIRONMENT** (2 lines)\n- **FILES** (3 lines) — 1 subsections\n - /var/mail/$LOGNAME.lock (4 lines)\n- **SEE ALSO** (2 lines)\n- **DIAGNOSTICS** (21 lines)\n- **BUGS** (2 lines)\n- **WARNINGS** (5 lines)\n- **MISCELLANEOUS** (2 lines)\n- **NOTES** (19 lines)\n- **SOURCE** (3 lines)\n- **MAILINGLIST** (11 lines)\n- **AUTHORS** (8 lines)\n\n## Full Content\n\n### NAME\n\nlockfile - conditional semaphore-file creator\n\n### SYNOPSIS\n\nlockfile -sleeptime | -r retries |\n-l locktimeout | -s suspend | -! | -ml | -mu | filename ...\n\n### DESCRIPTION\n\nlockfile can be used to create one or more semaphore files. If lockfile can't create all the\nspecified files (in the specified order), it waits sleeptime (defaults to 8) seconds and re‐\ntries the last file that didn't succeed. You can specify the number of retries to do until\nfailure is returned. If the number of retries is -1 (default, i.e., -r-1) lockfile will\nretry forever.\n\nIf the number of retries expires before all files have been created, lockfile returns failure\nand removes all the files it created up till that point.\n\nUsing lockfile as the condition of a loop in a shell script can be done easily by using the\n-! flag to invert the exit status. To prevent infinite loops, failures for any reason other\nthan the lockfile already existing are not inverted to success but rather are still returned\nas failures.\n\nAll flags can be specified anywhere on the command line, they will be processed when encoun‐\ntered. The command line is simply parsed from left to right.\n\nAll files created by lockfile will be read-only, and therefore will have to be removed with\nrm -f.\n\nIf you specify a locktimeout then a lockfile will be removed by force after locktimeout sec‐\nonds have passed since the lockfile was last modified/created (most likely by some other pro‐\ngram that unexpectedly died a long time ago, and hence could not clean up any leftover lock‐\nfiles). Lockfile is clock skew immune. After a lockfile has been removed by force, a sus‐\npension of suspend seconds (defaults to 16) is taken into account, in order to prevent the\ninadvertent immediate removal of any newly created lockfile by another program (compare SUS‐‐\nPEND in procmail(1)).\n\n#### Mailbox locks\n\nIf the permissions on the system mail spool directory allow it, or if lockfile is suitably\nsetgid, it will be able to lock and unlock your system mailbox by using the options -ml and\n\n#### -mu\n\n### EXAMPLES\n\nSuppose you want to make sure that access to the file \"important\" is serialised, i.e., no\nmore than one program or shell script should be allowed to access it. For simplicity's sake,\nlet's suppose that it is a shell script. In this case you could solve it like this:\n...\nlockfile important.lock\n...\naccess\"important\"toyourheartscontent\n...\nrm -f important.lock\n...\nNow if all the scripts that access \"important\" follow this guideline, you will be assured\nthat at most one script will be executing between the `lockfile' and the `rm' commands.\n\n### ENVIRONMENT\n\nLOGNAME used as a hint to determine the invoker's loginname\n\n### FILES\n\n/etc/passwd to verify and/or correct the invoker's loginname (and to find out his\nHOME directory, if needed)\n\n#### /var/mail/$LOGNAME.lock\n\nlockfile for the system mailbox, the environment variables present in\nhere will not be taken from the environment, but will be determined by\nlooking in /etc/passwd\n\n### SEE ALSO\n\nrm(1), mail(1), sendmail(8), procmail(1)\n\n### DIAGNOSTICS\n\nFilename too long, ... Use shorter filenames.\n\nForced unlock denied on \"x\"\nNo write permission in the directory where lockfile \"x\" resides, or\nmore than one lockfile trying to force a lock at exactly the same\ntime.\n\nForcing lock on \"x\" Lockfile \"x\" is going to be removed by force because of a timeout\n(compare LOCKTIMEOUT in procmail(1)).\n\nOut of memory, ... The system is out of swap space.\n\nSignal received, ... Lockfile will remove anything it created till now and terminate.\n\nSorry, ... The retries limit has been reached.\n\nTruncating \"x\" and retrying lock\n\"x\" does not seem to be a valid filename.\n\nTry praying, ... Missing subdirectories or insufficient privileges.\n\n### BUGS\n\nDefinitely less than one.\n\n### WARNINGS\n\nThe behavior of the -! flag, while useful, is not necessarily intuitive or consistent. When\ntesting lockfile's return value, shell script writers should consider carefully whether they\nwant to use the -! flag, simply reverse the test, or do a switch on the exact exitcode. In\ngeneral, the -! flag should only be used when lockfile is the conditional of a loop.\n\n### MISCELLANEOUS\n\nLockfile is NFS-resistant and eight-bit clean.\n\n### NOTES\n\nCalling up lockfile with the -h or -? options will cause it to display a command-line help\npage. Calling it up with the -v option will cause it to display its version information.\n\nMultiple -! flags will toggle the return status.\n\nSince flags can occur anywhere on the command line, any filename starting with a '-' has to\nbe preceded by './'.\n\nThe number of retries will not be reset when any following file is being created (i.e., they\nare simply used up). It can, however, be reset by specifying -rnewretries after every file\non the command line.\n\nAlthough files with any name can be used as lockfiles, it is common practice to use the ex‐\ntension `.lock' to lock mailfolders (it is appended to the mailfolder name). In case one\ndoes not want to have to worry about too long filenames and does not have to conform to any\nother lockfilename convention, then an excellent way to generate a lockfilename corresponding\nto some already existing file is by taking the prefix `lock.' and appending the i-node number\nof the file which is to be locked.\n\n### SOURCE\n\nThis program is part of the procmail mail-processing-package (v3.23pre) available at\nhttp://www.procmail.org/ or ftp.procmail.org in pub/procmail/.\n\n### MAILINGLIST\n\nThere exists a mailinglist for questions relating to any program in the procmail package:\n\nfor submitting questions/answers.\n\nfor subscription requests.\n\nIf you would like to stay informed about new versions and official patches send a subscrip‐\ntion request to\nprocmail-announce-request@procmail.org\n(this is a readonly list).\n\n### AUTHORS\n\nStephen R. van den Berg\n\nPhilip A. Guenther\n\n\n\n\nBuGless 2001/06/23 LOCKFILE(1)\n\n" } ], "structuredContent": { "command": "lockfile", "section": "1", "mode": "man", "summary": "lockfile - conditional semaphore-file creator", "synopsis": "lockfile -sleeptime | -r retries |\n-l locktimeout | -s suspend | -! | -ml | -mu | filename ...", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "", "long": null, "arg": null, "description": "" } ], "examples": [ "Suppose you want to make sure that access to the file \"important\" is serialised, i.e., no", "more than one program or shell script should be allowed to access it. For simplicity's sake,", "let's suppose that it is a shell script. In this case you could solve it like this:", "...", "lockfile important.lock", "...", "access\"important\"toyourheartscontent", "...", "rm -f important.lock", "...", "Now if all the scripts that access \"important\" follow this guideline, you will be assured", "that at most one script will be executing between the `lockfile' and the `rm' commands." ], "see_also": [ { "name": "rm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/rm/1/json" }, { "name": "mail", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/mail/1/json" }, { "name": "sendmail", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/sendmail/8/json" }, { "name": "procmail", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/procmail/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 28, "subsections": [ { "name": "Mailbox locks", "lines": 2 }, { "name": "-mu", "lines": 1 } ] }, { "name": "EXAMPLES", "lines": 13, "subsections": [] }, { "name": "ENVIRONMENT", "lines": 2, "subsections": [] }, { "name": "FILES", "lines": 3, "subsections": [ { "name": "/var/mail/$LOGNAME.lock", "lines": 4 } ] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "DIAGNOSTICS", "lines": 21, "subsections": [] }, { "name": "BUGS", "lines": 2, "subsections": [] }, { "name": "WARNINGS", "lines": 5, "subsections": [] }, { "name": "MISCELLANEOUS", "lines": 2, "subsections": [] }, { "name": "NOTES", "lines": 19, "subsections": [] }, { "name": "SOURCE", "lines": 3, "subsections": [] }, { "name": "MAILINGLIST", "lines": 11, "subsections": [] }, { "name": "AUTHORS", "lines": 8, "subsections": [] } ] } }