Documentation/filesystems/idmappings.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/filesystems/idmappings.rst
Extension
.rst
Size
42083 bytes
Lines
1040
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

.. SPDX-License-Identifier: GPL-2.0

Idmappings
==========

Most filesystem developers will have encountered idmappings. They are used when
reading from or writing ownership to disk, reporting ownership to userspace, or
for permission checking. This document is aimed at filesystem developers that
want to know how idmappings work.

Formal notes
------------

An idmapping is essentially a translation of a range of ids into another or the
same range of ids. The notational convention for idmappings that is widely used
in userspace is::

 u:k:r

``u`` indicates the first element in the upper idmapset ``U`` and ``k``
indicates the first element in the lower idmapset ``K``. The ``r`` parameter
indicates the range of the idmapping, i.e. how many ids are mapped. From now
on, we will always prefix ids with ``u`` or ``k`` to make it clear whether
we're talking about an id in the upper or lower idmapset.

To see what this looks like in practice, let's take the following idmapping::

 u22:k10000:r3

and write down the mappings it will generate::

 u22 -> k10000
 u23 -> k10001
 u24 -> k10002

From a mathematical viewpoint ``U`` and ``K`` are well-ordered sets and an
idmapping is an order isomorphism from ``U`` into ``K``. So ``U`` and ``K`` are
order isomorphic. In fact, ``U`` and ``K`` are always well-ordered subsets of
the set of all possible ids usable on a given system.

Looking at this mathematically briefly will help us highlight some properties
that make it easier to understand how we can translate between idmappings. For
example, we know that the inverse idmapping is an order isomorphism as well::

 k10000 -> u22
 k10001 -> u23
 k10002 -> u24

Given that we are dealing with order isomorphisms plus the fact that we're
dealing with subsets we can embed idmappings into each other, i.e. we can
sensibly translate between different idmappings. For example, assume we've been
given the three idmappings::

 1. u0:k10000:r10000
 2. u0:k20000:r10000
 3. u0:k30000:r10000

and id ``k11000`` which has been generated by the first idmapping by mapping
``u1000`` from the upper idmapset down to ``k11000`` in the lower idmapset.

Because we're dealing with order isomorphic subsets it is meaningful to ask
what id ``k11000`` corresponds to in the second or third idmapping. The
straightforward algorithm to use is to apply the inverse of the first idmapping,
mapping ``k11000`` up to ``u1000``. Afterwards, we can map ``u1000`` down using
either the second idmapping mapping or third idmapping mapping. The second
idmapping would map ``u1000`` down to ``k21000``. The third idmapping would map
``u1000`` down to ``k31000``.

If we were given the same task for the following three idmappings::

Annotation

Implementation Notes