{
    "mode": "man",
    "parameter": "dotlockfile",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/dotlockfile/1/json",
    "generated": "2026-06-02T20:21:56Z",
    "synopsis": "dotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile>\ndotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile> [-P] cmd args ...\ndotlockfile -u | -t",
    "sections": {
        "NAME": {
            "content": "dotlockfile - Utility to manage lockfiles\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "dotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile>\ndotlockfile -l [-r retries] [-i interval] [-p] [-q] <-m | lockfile> [-P] cmd args ...\ndotlockfile -u | -t\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "dotlockfile is a command line utility to reliably create, test and remove lockfiles.  It cre‐\nates lockfiles reliably on local and NFS filesystems, because the crucial  steps  of  testing\nfor  a  preexisting  lockfile  and  creating  it are performed atomically by a single call to\nlink(2).  Manpage lockfilecreate(3) describes the used algorithm.\n\ndotlockfile is installed with attribute SETGID mail and thus can also be used to lock and un‐\nlock mailboxes even if the mailspool directory is only writable by group mail.\n\nThe  name  dotlockfile  comes  from the way mailboxes are locked for updates on a lot of UNIX\nsystems.  A lockfile is created with the same filename as the mailbox  but  with  the  string\n\".lock\" appended.\n\nThe names dotlock and lockfile were already taken – hence the name dotlockfile :).\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "-l",
                    "content": "cording to option -r.  Retry interval can be explicitly set with option -i.  This  op‐\ntion (-l) is the default, so it can be left off.\n\nA lockfile is treated as valid,\n•  if it holds the process-id of a running process,\n•  or  if it does not hold any process-id and has been touched less than 5 minutes ago\n(timestamp is younger than 5 minutes).\n",
                    "flag": "-l"
                },
                {
                    "name": "-r retries",
                    "content": "The number of times dotlockfile retries to acquire the lock if  it  failed  the  first\ntime  before giving up.  The initial sleep after failing to acquire the lock is 5 sec‐\nonds.  After each retry the sleep interval is increased incrementally by 5 seconds  up\nto  a  maximum sleep of 60 seconds between tries unless overridden by -i.  The default\nnumber of retries is 5.  To try only once, use \"-r 0\".  To try indefinitely,  use  \"-r\n-1\".\n",
                    "flag": "-r"
                },
                {
                    "name": "-i interval",
                    "content": "Sets a consistent retry interval.\n",
                    "flag": "-i"
                },
                {
                    "name": "-u",
                    "content": "",
                    "flag": "-u"
                },
                {
                    "name": "-t",
                    "content": "filesystems.  For lockfiles on local filesystems the -p option is preferable.\n",
                    "flag": "-t"
                },
                {
                    "name": "-p",
                    "content": "ecuted) into the lockfile.  Also when testing for an existing lockfile, check the con‐\ntents for the process-id of a running process to  verify  if  the  lockfile  is  still\nvalid.  Obviously useful only for lockfiles on local filesystems.\n",
                    "flag": "-p"
                },
                {
                    "name": "-m",
                    "content": "tem mailspool directory (usually /var/mail) with the username  as  gotten  from  getp‐\nwuid()  appended.   If  the  environment  variable $MAIL is set, that is used instead.\nThen the string \".lock\" is appended to get the name of the actual lockfile.\n",
                    "flag": "-m"
                },
                {
                    "name": "-q",
                    "content": "blockfile when it spawns dotlockfile as a helper program.\n",
                    "flag": "-q"
                },
                {
                    "name": "-P",
                    "content": "the exit value of the spawned command.\n\nlockfile\nThe lockfile to be created or removed.  Must not be specified  if  the  -m  option  is\ngiven.\n\ncommand argument ...\nCreate lockfile, run the command , wait for it to exit, and remove lockfile.\n",
                    "flag": "-P"
                }
            ]
        },
        "RETURN VALUE": {
            "content": "Zero  on success, and non-zero on failure.  When locking (the default, or with the -l option)\ndotlockfile returns the same values as the library function lockfilecreate(3).  Unlocking  a\nnon-existent lockfile is not an error.\n\nUnless the -P option was supplied, when a command is executed, the return value does not cor‐\nrespond with that of the command that was run.  If locking and unlocking was successful,  the\nexit status is zero.\n",
            "subsections": []
        },
        "NOTES": {
            "content": "The  lockfile  is created exactly as named on the command line.  The extension \".lock\" is not\nautomatically appended.\n\nThis utility is a lot like the lockfile(1) utility included with procmail, and the  muttdot‐\nlock(1)  utility  included with mutt.  However the command-line arguments differ, and so does\nthe return status.  It is believed, that dotlockfile is  the  most  flexible  implementation,\nsince it automatically detects when it needs to use privileges to lock a mailbox, and does it\nsafely.\n\nThe above mentioned lockfilecreate(3) manpage is present in the liblockfile-dev package.\n",
            "subsections": []
        },
        "BUGS": {
            "content": "None known.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "lockfilecreate(3), maillock(3)\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Miquel van Smoorenburg\n\n\n\nJanuary 10, 2017                            DOTLOCKFILE(1)",
            "subsections": []
        }
    },
    "summary": "dotlockfile - Utility to manage lockfiles",
    "flags": [
        {
            "flag": "-l",
            "long": null,
            "arg": null,
            "description": "cording to option -r. Retry interval can be explicitly set with option -i. This op‐ tion (-l) is the default, so it can be left off. A lockfile is treated as valid, • if it holds the process-id of a running process, • or if it does not hold any process-id and has been touched less than 5 minutes ago (timestamp is younger than 5 minutes)."
        },
        {
            "flag": "-r",
            "long": null,
            "arg": null,
            "description": "The number of times dotlockfile retries to acquire the lock if it failed the first time before giving up. The initial sleep after failing to acquire the lock is 5 sec‐ onds. After each retry the sleep interval is increased incrementally by 5 seconds up to a maximum sleep of 60 seconds between tries unless overridden by -i. The default number of retries is 5. To try only once, use \"-r 0\". To try indefinitely, use \"-r -1\"."
        },
        {
            "flag": "-i",
            "long": null,
            "arg": null,
            "description": "Sets a consistent retry interval."
        },
        {
            "flag": "-u",
            "long": null,
            "arg": null,
            "description": ""
        },
        {
            "flag": "-t",
            "long": null,
            "arg": null,
            "description": "filesystems. For lockfiles on local filesystems the -p option is preferable."
        },
        {
            "flag": "-p",
            "long": null,
            "arg": null,
            "description": "ecuted) into the lockfile. Also when testing for an existing lockfile, check the con‐ tents for the process-id of a running process to verify if the lockfile is still valid. Obviously useful only for lockfiles on local filesystems."
        },
        {
            "flag": "-m",
            "long": null,
            "arg": null,
            "description": "tem mailspool directory (usually /var/mail) with the username as gotten from getp‐ wuid() appended. If the environment variable $MAIL is set, that is used instead. Then the string \".lock\" is appended to get the name of the actual lockfile."
        },
        {
            "flag": "-q",
            "long": null,
            "arg": null,
            "description": "blockfile when it spawns dotlockfile as a helper program."
        },
        {
            "flag": "-P",
            "long": null,
            "arg": null,
            "description": "the exit value of the spawned command. lockfile The lockfile to be created or removed. Must not be specified if the -m option is given. command argument ... Create lockfile, run the command , wait for it to exit, and remove lockfile."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "lockfilecreate",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/lockfilecreate/3/json"
        },
        {
            "name": "maillock",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/maillock/3/json"
        }
    ]
}