How to Inspect and Troubleshoot Active File Locks in Linux Using lslocks

In multi-user Linux environments and production server deployments, concurrent processes frequently access the same files—whether updating application logs, executing database transactions, or writing daemon PID states. To prevent data corruption, race conditions, and inconsistent writes, processes acquire file locks (such as POSIX record locks or BSD flock locks). While locking is crucial for data integrity, software bugs, frozen daemons, or crashed background threads can leave locks abandoned indefinitely.

When a file remains locked by a stale process, subsequent applications attempting to read or write will hang, report “Resource temporarily unavailable”, or fail with EAGAIN errors. While traditional diagnostics like lsof show which processes have open file descriptors, they do not explicitly reveal which processes hold active or contested locks. The lslocks utility, included natively in the util-linux package, solves this exact problem by querying the kernel’s lock registry directly. In this tutorial, we explain how to use lslocks in Linux to inspect, filter, and troubleshoot active file locks.

Understanding Linux File Lock Types

The Linux kernel supports multiple file locking mechanisms, each with distinct behaviours reflected in lslocks:

• POSIX Locks (fcntl): Byte-range record locks that allow processes to lock specific byte offsets within a file rather than the entire file. Associated with a process ID and automatically released when the process closes any descriptor to that file.
• FLOCK Locks (flock): Whole-file advisory locks commonly used by shell scripts and utilities to enforce single-instance execution.
• OFD (Open File Description) Locks: Modern Linux locks that behave like POSIX record locks but are associated with the file description rather than a single PID, allowing thread-safe locking across concurrent workers.
• Advisory vs Mandatory: Advisory locks require cooperating applications to query the lock before writing. Mandatory locks (rarely used in modern kernels) are enforced by the filesystem itself on every I/O call.

How to List All Active File Locks

Because file locking information is read directly from kernel internal state in /proc/locks, you should execute lslocks with superuser privileges to ensure all system and daemon locks are visible:

sudo lslocks

The output presents a structured table containing eight informative columns:

COMMAND          PID TYPE   SIZE MODE  M START END PATH
systemd            1 FLOCK  116B WRITE 0     0   0 /run/systemd/inhibit/1.ref
dockerd         1240 FLOCK    0B WRITE 0     0   0 /var/lib/docker/volumes/metadata.db
mysqld          1822 POSIX 12.8M WRITE 0     0   0 /var/lib/mysql/ibdata1
apache2         2410 POSIX   48B READ  0     0   0 /var/log/apache2/access.log

Interpreting lslocks Table Columns

To diagnose lock contention effectively, understand the data provided in each column:

• COMMAND: The name of the binary or executable holding the lock.
• PID: The process ID of the locking process.
• TYPE: The locking mechanism (POSIX, FLOCK, or OFD).
• SIZE: The size of the locked file on disk.
• MODE: The access privilege granted (WRITE for exclusive locks, or READ for shared locks).
• M: Mandatory lock flag (1 if mandatory, 0 if advisory).
• START & END: The byte offset range protected by the lock. A value of 0 and 0 indicates the entire file is locked.
• PATH: The absolute filesystem path to the locked inode.

Filtering Locks by Process ID (PID)

If you suspect a specific application (for example, a hung Python worker or database service with PID 1822) is locking resources, filter output using the -p flag:

sudo lslocks -p 1822

This command lists only the specific files and byte ranges currently locked by that process ID.

Exporting and Parsing Output with JSON or Raw Mode

For automated server monitoring scripts, Nagios plugins, or CI/CD pipelines, lslocks provides machine-readable output formats:

Exporting to JSON:

sudo lslocks --json

This outputs an array of JSON objects ideal for parsing with tools like jq:

sudo lslocks --json | jq '.locks[] | select(.mode=="WRITE")'

Raw (Script-Friendly) Output:

sudo lslocks --raw --noheadings

How to Resolve a Locked File Conflict

Once lslocks identifies the offending process holding an abandoned or contested lock:

1. Check the process details to confirm what it is doing:

ps -fp <PID>

2. Attempt a graceful termination of the holding process:

sudo kill -15 <PID>

3. If the process is completely hung in an uninterruptible sleep state (D state) or deadlocked on hardware I/O, force-terminate it:

sudo kill -9 <PID>

As soon as the process terminates, the Linux kernel automatically cleans up its registered file descriptors and unlocks the file in /proc/locks, allowing other waiting services to resume normal operation immediately.