{
    "mode": "man",
    "parameter": "lockfile-create",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/lockfile-create/1/json",
    "generated": "2026-05-30T06:05:58Z",
    "synopsis": "mail-lock [--use-pid] [--retry retry-count]",
    "sections": {
        "NAME": {
            "content": "lockfile-progs - command-line programs to safely lock and unlock files and mailboxes (via li‐\nblockfile).\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "mail-lock [--use-pid] [--retry retry-count]",
            "subsections": [
                {
                    "name": "mail-unlock",
                    "content": "mail-touchlock [--oneshot]\n\nlockfile-create [--use-pid] [--retry retry-count] [--lock-name] filename\nlockfile-remove [--lock-name] filename\nlockfile-touch [--oneshot] [--lock-name] filename\nlockfile-check [--use-pid] [--lock-name] filename\n"
                }
            ]
        },
        "DESCRIPTION": {
            "content": "Lockfile-progs provides a set a programs that can be used to lock and  unlock  mailboxes  and\nfiles safely (via liblockfile):\n\nmail-lock - lock the current user's mailbox\nmail-unlock - unlock the current user's mailbox\nmail-touchlock - touch the lock on the current user's mailbox\n\nlockfile-create - lock a given file\nlockfile-remove - remove the lock on a given file\nlockfile-touch - touch the lock on a given file\nlockfile-check - check the lock on a given file\n\nBy  default,  the filename argument refers to the name of the file to be locked, and the name\nof the lockfile will be filename .lock.  However, if the --lock-name argument  is  specified,\nthen filename will be taken as the name of the lockfile itself.\n\nEach  of  the  mail locking commands attempts to lock /var/spool/mail/<user>, where <user> is\nthe name associated with the effective user ID, as determined by via geteuid(2).\n\nOnce a file is locked, the lock must be touched at least once every five minutes or the  lock\nwill  be considered stale, and subsequent lock attempts will succeed.  Also see the --use-pid\noption and the lockfilecreate(3) manpage.\n\nThe lockfile-check command tests whether or not a valid lock already exists.\n\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "",
            "subsections": [
                {
                    "name": "-q --quiet",
                    "content": "Suppress any output.  Success or failure will only be indicated by the exit status.\n",
                    "flag": "-q",
                    "long": "--quiet"
                },
                {
                    "name": "-v --verbose",
                    "content": "Enable diagnostic output.\n",
                    "flag": "-v",
                    "long": "--verbose"
                },
                {
                    "name": "-l --lock-name",
                    "content": "Do not append .lock to the filename.   This  option  applies  to  lockfile-create,  lock‐‐\nfile-remove, lockfile-touch, or lockfile-check.\n",
                    "flag": "-l",
                    "long": "--lock-name"
                },
                {
                    "name": "-p --use-pid",
                    "content": "Write  the  parent  process id (PPID) to the lockfile whenever a lockfile is created, and\nuse that pid when checking a lock's validity.  See  the  lockfilecreate(3)  manpage  for\nmore information.  This option applies to lockfile-create and lockfile-check.  NOTE: this\noption will not work correctly between machines sharing a filesystem.\n",
                    "flag": "-p",
                    "long": "--use-pid"
                },
                {
                    "name": "-o --oneshot",
                    "content": "Touch the  lock  and  exit  immediately.   This  option  applies  to  lockfile-touch  and\nmail-touchlock.   When  not  provided, these commands will run forever, touching the lock\nonce every minute until killed.\n",
                    "flag": "-o",
                    "long": "--oneshot"
                },
                {
                    "name": "-r --retry",
                    "content": "Try to lock filename retry-count times before giving up.  Each attempt will be delayed  a\nbit  longer  than the last (in 5 second increments) until reaching a maximum delay of one\nminute between retries.  If retry-count is unspecified, the default is 9 which will  give\nup after 225 seconds if all 9 lock attempts fail.\n\n",
                    "flag": "-r",
                    "long": "--retry"
                }
            ]
        },
        "EXAMPLES": {
            "content": "",
            "subsections": [
                {
                    "name": "Locking a file during a lengthy process:",
                    "content": "lockfile-create /some/file\nlockfile-touch /some/file &\n# Save the PID of the lockfile-touch process\nBADGER=\"$!\"\ndo-something-important-with /some/file\nkill \"${BADGER}\"\nlockfile-remove /some/file\n\n"
                }
            ]
        },
        "EXIT STATUS": {
            "content": "0\nFor  lockfile-check  this indicates that a valid lock exists, otherwise it just indicates\nsuccessful program execution.\n",
            "subsections": [
                {
                    "name": "Not 0",
                    "content": "For lockfile-check a non-zero exit status indicates that the specified lock does not  ex‐\nist or is not valid.  For other programs it indicates that some problem was encountered.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "maillock(3)\ntouchlock(3)\nmailunlock(3)\nlockfilecreate(3)\nlockfileremove(3)\nlockfiletouch(3)\nlockfilecheck(3)\n\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Written by Rob Browning <rlb@defaultvalue.org>\n\n\n\n0.1.19                                       2021-09-03                            lockfile-progs(1)",
            "subsections": []
        }
    },
    "summary": "lockfile-progs - command-line programs to safely lock and unlock files and mailboxes (via li‐ blockfile).",
    "flags": [
        {
            "flag": "-q",
            "long": "--quiet",
            "arg": null,
            "description": "Suppress any output. Success or failure will only be indicated by the exit status."
        },
        {
            "flag": "-v",
            "long": "--verbose",
            "arg": null,
            "description": "Enable diagnostic output."
        },
        {
            "flag": "-l",
            "long": "--lock-name",
            "arg": null,
            "description": "Do not append .lock to the filename. This option applies to lockfile-create, lock‐‐ file-remove, lockfile-touch, or lockfile-check."
        },
        {
            "flag": "-p",
            "long": "--use-pid",
            "arg": null,
            "description": "Write the parent process id (PPID) to the lockfile whenever a lockfile is created, and use that pid when checking a lock's validity. See the lockfilecreate(3) manpage for more information. This option applies to lockfile-create and lockfile-check. NOTE: this option will not work correctly between machines sharing a filesystem."
        },
        {
            "flag": "-o",
            "long": "--oneshot",
            "arg": null,
            "description": "Touch the lock and exit immediately. This option applies to lockfile-touch and mail-touchlock. When not provided, these commands will run forever, touching the lock once every minute until killed."
        },
        {
            "flag": "-r",
            "long": "--retry",
            "arg": null,
            "description": "Try to lock filename retry-count times before giving up. Each attempt will be delayed a bit longer than the last (in 5 second increments) until reaching a maximum delay of one minute between retries. If retry-count is unspecified, the default is 9 which will give up after 225 seconds if all 9 lock attempts fail."
        }
    ],
    "examples": [
        "lockfile-create /some/file",
        "lockfile-touch /some/file &",
        "# Save the PID of the lockfile-touch process",
        "BADGER=\"$!\"",
        "do-something-important-with /some/file",
        "kill \"${BADGER}\"",
        "lockfile-remove /some/file"
    ],
    "see_also": [
        {
            "name": "maillock",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/maillock/3/json"
        },
        {
            "name": "touchlock",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/touchlock/3/json"
        },
        {
            "name": "mailunlock",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/mailunlock/3/json"
        },
        {
            "name": "lockfilecreate",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/lockfilecreate/3/json"
        },
        {
            "name": "lockfileremove",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/lockfileremove/3/json"
        },
        {
            "name": "lockfiletouch",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/lockfiletouch/3/json"
        },
        {
            "name": "lockfilecheck",
            "section": "3",
            "url": "https://www.chedong.com/phpMan.php/man/lockfilecheck/3/json"
        }
    ]
}