Documentation/filesystems/directory-locking.rst

Source file repositories/reference/linux-study-clean/Documentation/filesystems/directory-locking.rst

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/directory-locking.rst
Extension
.rst
Size
13362 bytes
Lines
287
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=================
Directory Locking
=================


Locking scheme used for directory operations is based on two
kinds of locks - per-inode (->i_rwsem) and per-filesystem
(->s_vfs_rename_mutex).

When taking the i_rwsem on multiple non-directory objects, we
always acquire the locks in order by increasing address.  We'll call
that "inode pointer" order in the following.


Primitives
==========

For our purposes all operations fall in 6 classes:

1. read access.  Locking rules:

	* lock the directory we are accessing (shared)

2. object creation.  Locking rules:

	* lock the directory we are accessing (exclusive)

3. object removal.  Locking rules:

	* lock the parent (exclusive)
	* find the victim
	* lock the victim (exclusive)

4. link creation.  Locking rules:

	* lock the parent (exclusive)
	* check that the source is not a directory
	* lock the source (exclusive; probably could be weakened to shared)

5. rename that is _not_ cross-directory.  Locking rules:

	* lock the parent (exclusive)
	* find the source and target
	* decide which of the source and target need to be locked.
	  The source needs to be locked if it's a non-directory, target - if it's
	  a non-directory or about to be removed.
	* take the locks that need to be taken (exclusive), in inode pointer order
	  if need to take both (that can happen only when both source and target
	  are non-directories - the source because it wouldn't need to be locked
	  otherwise and the target because mixing directory and non-directory is
	  allowed only with RENAME_EXCHANGE, and that won't be removing the target).

6. cross-directory rename.  The trickiest in the whole bunch.  Locking rules:

	* lock the filesystem
	* if the parents don't have a common ancestor, fail the operation.
	* lock the parents in "ancestors first" order (exclusive). If neither is an
	  ancestor of the other, lock the parent of source first.
	* find the source and target.
	* verify that the source is not a descendent of the target and
	  target is not a descendent of source; fail the operation otherwise.
	* lock the subdirectories involved (exclusive), source before target.
	* lock the non-directories involved (exclusive), in inode pointer order.

The rules above obviously guarantee that all directories that are going
to be read, modified or removed by method will be locked by the caller.


Splicing
========

Annotation

Implementation Notes