flock
File locks from the shell — keep two copies of a script or cron job from running at the same time
flock takes a lock on a file (the flock(2) system call) and runs a command while holding the lock. If another process already holds the lock, flock waits or gives up right away. The main use is protection against concurrent runs: a cron job that hasn't finished by the next run, a deploy script, a queue worker. The lock is released automatically when the owning process exits, even if it crashes — unlike "pid files", which stay behind after a crash. The tool is part of util-linux.
Syntax
flock [options] file command [args…] # lock the file for the duration of the command
flock [options] file -c 'command string' # command via sh -c
flock [options] fd_number # lock an already open descriptor
The lock file is created if it doesn't exist (the directory must exist). The file contents don't matter — the lock is tied to the file itself, not to the data.
Options
| Option | What it does |
|---|---|
-x, --exclusive | exclusive lock — only one owner (default) |
-s, --shared | shared lock — several "readers" at once, but not together with -x |
-n, --nonblock | don't wait: if busy, exit immediately with code 1 |
-w sec, --timeout | wait no longer than N seconds (fractions allowed), then exit with code 1 |
-E code | exit code for a busy lock or timeout instead of 1 |
-u, --unlock | release the lock on a descriptor (usually unnecessary — released on close) |
-o, --close | close the lock descriptor before running the command: its children won't inherit the lock |
-c 'commands' | run the string via sh -c |
-F, --no-fork | don't fork a child process, replace flock with the command |
--verbose | report how long it waited for the lock and what it runs |
Exit codes
| Code | When |
|---|---|
| the command's code | lock acquired, the command ran |
1 | lock is busy (-n) or the timeout expired (-w); or your own value from -E |
66 | the lock file couldn't be opened (e.g. the directory doesn't exist) |
Two ways to use it
| Form | Example | When |
|---|---|---|
| wrapper around a command | flock -n /run/job.lock /opt/job.sh | in a crontab, when you don't want to change the script |
| descriptor inside a script | exec 9>/run/job.lock; flock -n 9 || exit 1 | the script protects itself; the lock lives until the script ends |
Examples
# cron: run every minute, but don't let runs overlap
# * * * * * flock -n /run/backup.lock /opt/backup.sh
# wait for the lock no longer than 30 seconds
flock -w 30 /run/deploy.lock ./deploy.sh || echo "deploy already in progress" >&2
# tell "busy" apart from a failure of the command itself
flock -n -E 75 /run/job.lock ./job.sh
[ $? -eq 75 ] && echo "already running"
# a script that protects itself: the lock is held for the whole run
cat > /tmp/job.sh <<'EOF'
#!/bin/bash
exec 9>/tmp/job.lock
if ! flock -n 9; then
echo "another copy is already running" >&2
exit 1
fi
echo "working, PID $$"
sleep 5
EOF
chmod +x /tmp/job.sh
/tmp/job.sh & sleep 0.5; /tmp/job.sh # the second copy exits immediately
# protect only part of a script: a block in a subshell
(
flock -w 10 9 || exit 1
echo "write to a shared file" >> /tmp/shared.log
) 9>/tmp/shared.lock
# shared lock for readers, exclusive for the writer
flock -s /tmp/data.lock cat /tmp/data.txt
flock -x /tmp/data.lock sh -c 'date > /tmp/data.txt'
# several commands under one lock
flock /tmp/a.lock -c 'echo start; sleep 1; echo end'
Pitfalls
- Argument order with
-c. File first, then-c:flock file -c '…'. Writingflock -c '…' filefails withinvalid option -- 'c'. - Background children inherit the lock. If a script with
exec 9>filestarts something in the background (service &) and exits, descriptor 9 stays with the child and the lock is not released. Close the descriptor for background processes:command 9>&- &; in the wrapper form use-o. - Don't delete the lock file. If you delete the file while a process holds it, the next run creates a new file with a different inode and happily takes "its own" lock — the protection is gone. Just leave the file alone.
exec 9>filetruncates the file. If the lock file stores something, open it for appending or reading:exec 9>>fileorexec 9<file.- Locks are advisory. They only work if all participants use
flockon the same file. A plaincatorecho >doesn't check the lock. - Without
-nor-w,flockwaits forever. In cron this means hung jobs pile up. For cron you almost always want-n. - Choose where the file lives.
/tmpis cleared on reboot and is accessible to all users — someone else's process could take your lock. For system jobs/run/or/var/lock/is a good fit.
See also
cron · background · redirection · timeout · exit-codes