Constants

AOP_WRITEPAGE_ACTIVATE

Informs the caller that page writeback hascompleted, that the page is still locked, andshould be considered active. The VM uses this hintto return the page to the active list -- it won’tbe a candidate for writeback again in the nearfuture. Other callers must be careful to unlockthe page if they get this return. Returned bywritepage();

AOP_TRUNCATED_PAGE

The AOP method that was handed a locked page hasunlocked it and the page might have been truncated.The caller should back up to acquiring a new page andtrying again. The aop will be taking reasonableprecautions not to livelock. If the caller held a pagereference, it should drop it before retrying. Returnedbyread_folio().

Definition:

struct address_space {    struct inode            *host;    struct xarray           i_pages;    struct rw_semaphore     invalidate_lock;    gfp_t gfp_mask;    atomic_t i_mmap_writable;#ifdef CONFIG_READ_ONLY_THP_FOR_FS;    atomic_t nr_thps;#endif;    struct rb_root_cached   i_mmap;    unsigned long           nrpages;    pgoff_t writeback_index;    const struct address_space_operations *a_ops;    unsigned long           flags;    errseq_t wb_err;    spinlock_t i_private_lock;    struct list_head        i_private_list;    struct rw_semaphore     i_mmap_rwsem;    void *                  i_private_data;};

Members

host

Owner, either the inode or the block_device.

i_pages

Cached pages.

invalidate_lock

Guards coherency between page cache contents andfile offset->disk block mappings in the filesystem during invalidates.It is also used to block modification of page cache contents throughmemory mappings.

gfp_mask

Memory allocation flags to use for allocating pages.

i_mmap_writable

Number of VM_SHARED, VM_MAYWRITE mappings.

nr_thps

Number of THPs in the pagecache (non-shmem only).

i_mmap

Tree of private and shared mappings.

nrpages

Number of page entries, protected by the i_pages lock.

writeback_index

Writeback starts here.

a_ops

Methods.

flags

Error bits and flags (AS_*).

wb_err

The most recent error which has occurred.

i_private_lock

For use by the owner of the address_space.

i_private_list

For use by the owner of the address_space.

i_mmap_rwsem

Protectsi_mmap andi_mmap_writable.

i_private_data

For use by the owner of the address_space.

Definition:

struct file_ra_state {    pgoff_t start;    unsigned int size;    unsigned int async_size;    unsigned int ra_pages;    unsigned short order;    unsigned short mmap_miss;    loff_t prev_pos;};

Members

start

Where the most recent readahead started.

size

Number of pages read in the most recent readahead.

async_size

Numer of pages that were/are not needed immediatelyand so were/are genuinely “ahead”. Start next readahead whenthe first of these pages is accessed.

ra_pages

Maximum size of a readahead request, copied from the bdi.

order

Preferred folio order used for most recent readahead.

mmap_miss

How many mmap accesses missed in the page cache.

prev_pos

The last byte in the most recent read request.

Definition:

struct file {    spinlock_t f_lock;    fmode_t f_mode;    const struct file_operations    *f_op;    struct address_space            *f_mapping;    void *private_data;    struct inode                    *f_inode;    unsigned int                    f_flags;    unsigned int                    f_iocb_flags;    const struct cred               *f_cred;    struct fown_struct              *f_owner;    union {        const struct path       f_path;        struct path             __f_path;    };    union {        struct mutex            f_pos_lock;        u64 f_pipe;    };    loff_t f_pos;#ifdef CONFIG_SECURITY;    void *f_security;#endif;    errseq_t f_wb_err;    errseq_t f_sb_err;#ifdef CONFIG_EPOLL;    struct hlist_head               *f_ep;#endif;    union {        struct callback_head    f_task_work;        struct llist_node       f_llist;        struct file_ra_state    f_ra;        freeptr_t f_freeptr;    };    file_ref_t f_ref;};

Members

f_lock

Protects f_ep, f_flags. Must not be taken from IRQ context.

f_mode

FMODE_* flags often used in hotpaths

f_op

file operations

f_mapping

Contents of a cacheable, mappable object.

private_data

filesystem or driver specific data

f_inode

cached inode

f_flags

file flags

f_iocb_flags

iocb flags

f_cred

stashed credentials of creator/opener

f_owner

file owner

{unnamed_union}

anonymous

f_path

path of the file

__f_path

writable alias forf_path;ONLY for core VFS and only beforethe file gets open

{unnamed_union}

anonymous

f_pos_lock

lock protecting file position

f_pipe

specific to pipes

f_pos

file position

f_security

LSM security context of this file

f_wb_err

writeback error

f_sb_err

per sb writeback errors

f_ep

link of all epoll hooks for this file

{unnamed_union}

anonymous

f_task_work

task work entry point

f_llist

work queue entrypoint

f_ra

file’s readahead state

f_freeptr

Pointer used by SLAB_TYPESAFE_BY_RCU file cache (don’t touch.)

f_ref

reference count

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructinode*inode

inode to map

Return

whe inode’s i_uid mapped down according toidmap.If the inode’s i_uid has no mapping INVALID_VFSUID is returned.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructiattr*attr

the new attributes ofinode

conststructinode*inode

the inode to update

Description

Check whether the $inode’s i_uid field needs to be updated taking idmappedmounts into account if the filesystem supports it.

Return

true ifinode’s i_uid field needs to be updated, false if not.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructiattr*attr

the new attributes ofinode

structinode*inode

the inode to update

Description

Safely updateinode’s i_uid field translating the vfsuid of any idmappedmount into the filesystem kuid.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructinode*inode

inode to map

Return

the inode’s i_gid mapped down according toidmap.If the inode’s i_gid has no mapping INVALID_VFSGID is returned.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructiattr*attr

the new attributes ofinode

conststructinode*inode

the inode to update

Description

Check whether the $inode’s i_gid field needs to be updated taking idmappedmounts into account if the filesystem supports it.

Return

true ifinode’s i_gid field needs to be updated, false if not.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructiattr*attr

the new attributes ofinode

structinode*inode

the inode to update

Description

Safely updateinode’s i_gid field translating the vfsgid of any idmappedmount into the filesystem kgid.

Parameters

structinode*inode

inode to initialize

structmnt_idmap*idmap

idmap of the mount the inode was found from

Description

Initialize the i_uid field ofinode. If the inode was found/created viaan idmapped mount map the caller’s fsuid according toidmap.

Parameters

structinode*inode

inode to initialize

structmnt_idmap*idmap

idmap of the mount the inode was found from

Description

Initialize the i_gid field ofinode. If the inode was found/created viaan idmapped mount map the caller’s fsgid according toidmap.

Parameters

structsuper_block*sb

the superblock we want a mapping in

structmnt_idmap*idmap

idmap of the relevant mount

Description

Check whether the caller’s fsuid and fsgid have a valid mapping in thes_user_ns of the superblocksb. If the caller is on an idmapped mount mapthe caller’s fsuid and fsgid according to theidmap first.

Return

true if fsuid and fsgid is mapped, false if not.

Parameters

structinode*inode

inode in which to set the ctime

time64_tsec

tv_sec value to set

longnsec

tv_nsec value to set

Description

Set the ctime ininode to {sec,nsec }

Parameters

conststructfile*file

the file we write to

Description

May be false positive with !CONFIG_LOCKDEP/LOCK_STATE_UNKNOWN.May be false positive with !S_ISREG, becausefile_start_write() hasno effect on !S_ISREG.

Parameters

conststructfile*file

the file we write to

Description

May be false positive with !CONFIG_LOCKDEP/LOCK_STATE_UNKNOWN.May be false positive with !S_ISREG, becausefile_start_write() hasno effect on !S_ISREG.

Definition:

struct renamedata {    struct mnt_idmap *mnt_idmap;    struct dentry *old_parent;    struct dentry *old_dentry;    struct dentry *new_parent;    struct dentry *new_dentry;    struct delegated_inode *delegated_inode;    unsigned int flags;};

Members

mnt_idmap

idmap of the mount in which the rename is happening.

old_parent

parent of source

old_dentry

source

new_parent

parent of destination

new_dentry

destination

delegated_inode

returns an inode needing a delegation break

flags

rename flags

Parameters

conststructinode*inode

inode to test for multigrain timestamps

Description

Return true if the inode uses multigrain timestamps, false otherwise.

Parameters

conststructvfsmount*mnt

the mount to check

Description

Ifmnt has an nonnop_mnt_idmap attached to it thenmnt is mapped.

Return

true if mount is mapped, false if not.

Parameters

structfile*file

the file we want to write to

Description

This is a variant ofsb_start_write() which is a noop on non-regular file.Should be matched with a call tofile_end_write().

Parameters

structfile*file

the file we wrote to

Description

Should be matched with a call tofile_start_write().

Parameters

structkiocb*iocb

the io context we want to submit the write with

Description

This is a variant ofsb_start_write() for async io submission.Should be matched with a call tokiocb_end_write().

Parameters

structkiocb*iocb

the io context we sumbitted the write with

Description

Should be matched with a call tokiocb_start_write().

Parameters

constchar*name

file name to check

size_tlen

length of file name, in bytes

Parameters

constchar*name

File path string to checkSearch for “..” surrounded by either ‘/’ or start/end of string.

Parameters

structinode*inode

inode the direct I/O happens on

Description

This is called once we’ve finished processing a direct I/O request,and is used to wake up callers waiting for direct I/O to be quiesced.

Parameters

structinode*inode

inode the direct I/O happens on

Description

This is called once we’ve finished processing a direct I/O request,and is used to wake up callers waiting for direct I/O to be quiesced.

Parameters

structinode*dir

inode of the directory where the new file will be created

conststructqstr*name

name of the new file

Description

This functions checks if the proposed filename is valid for theparent directory. That means that only valid UTF-8 filenames will beaccepted for casefold directories from filesystems created with thestrict encoding flag. That also means that any name will beaccepted for directories that doesn’t have casefold enabled, oraren’t being strict with the encoding.

Return

• True: if the filename is suitable for this directory. It can betrue if a given name is not suitable for a strict encodingdirectory, but the directory being used isn’t strict

• False if the filename isn’t suitable for this directory. This onlyhappens when a directory is casefolded and the filesystem is strictabout its encoding.

Parameters

structdentry*dentry

dentry to drop

Description

d_drop() unhashes the entry from the parent dentry hashes, so that it won’tbe found through a VFS lookup any more. Note that this is different fromdeleting the dentry - d_delete will try to mark the dentry negative ifpossible, giving a successful _negative_ lookup, while d_drop willjust make the cache lookup fail.

d_drop() is used mainly for stuff that wants to invalidate a dentry for somereason (NFS timeouts or autofs deletes).

__d_drop requires dentry->d_lock

___d_drop doesn’t mark dentry as “unhashed”(dentry->d_hash.pprev will be LIST_POISON2, not NULL).

Parameters

structinode*inode

inode to find an alias for

Description

If any aliases exist for the given inode, take and return areference for one of them. If no aliases exist, returnNULL.

Parameters

structinode*inode

inode in question

Description

If inode has a hashed alias, or is a directory and has any alias,acquire the reference to alias and return it. Otherwise return NULL.Notice that if inode is a directory there can be only one alias andit can be unhashed only if it has no children, or if it is the rootof a filesystem, or if the directory was renamed and d_revalidatewas the first vfs operation to notice.

If the inode has an IS_ROOT, DCACHE_DISCONNECTED alias, then preferany other hashed alias over that one.

Parameters

structdentry*dentry

dentry in question

structlist_head*dispose

head of shrink list

Description

If dentry has no external references, move it to shrink list.

NOTE!!! The caller is responsible for preventing eviction of the dentry byholding dentry->d_inode->i_lock or equivalent.

Parameters

structsuper_block*sb

superblock

Description

Shrink the dcache for the specified super block. This is used to freethe dcache before unmounting a file system.

Parameters

conststructpath*parent

path to check.

Description

Return true if the parent or its subdirectories containa mount point in the current namespace.

Parameters

structdentry*dentry

dentry to invalidate (aka detach, prune and drop)

Parameters

structdentry*parent

parent of entry to allocate

conststructqstr*name

qstr of the name

Description

Allocates a dentry. It returnsNULL if there is insufficient memoryavailable. On a success the dentry is returned. The name passed in iscopied and the copy passed in may be reused after this call.

Parameters

structdentry*entry

dentry to complete

structinode*inode

inode to attach to this dentry

Description

Fill in inode information in the entry.

This turns negative dentries into productive full membersof society.

NOTE! This assumes that the inode count has been incremented(or otherwise set) by the caller to indicate that it is nowin use by the dcache.

Parameters

structinode*inode

inode to allocate the dentry for

Description

Obtain a dentry for an inode resulting from NFS filehandle conversion orsimilar open by handle operations. The returned dentry may be anonymous,or may have a full name (if the inode was already in the cache).

When called on a directory inode, we must ensure that the inode only everhas one dentry. If a dentry is found, that is returned instead ofallocating a new one.

On successful return, the reference to the inode has been transferredto the dentry. In case of an error the reference on the inode is released.To make it easier to use in export operations aNULL or IS_ERR inode maybe passed in and the error will be propagated to the return value,with aNULLinode replaced by ERR_PTR(-ESTALE).

Parameters

structinode*inode

inode to allocate the dentry for

Description

Obtain an IS_ROOT dentry for the root of a filesystem.

We must ensure that directory inodes only ever have one dentry. If adentry is found, that is returned instead of allocating a new one.

On successful return, the reference to the inode has been transferredto the dentry. In case of an error the reference on the inode isreleased. ANULL or IS_ERR inode may be passed in and will be theerror will be propagate to the return value, with aNULLinodereplaced by ERR_PTR(-ESTALE).

Parameters

structdentry*dentry

the negative dentry that was passed to the parent’s lookup func

structinode*inode

the inode case-insensitive lookup has found

structqstr*name

the case-exact name to be associated with the returned dentry

Description

This is to avoid filling the dcache with case-insensitive names to thesame inode, only the actual correct case is stored in the dcache forcase-insensitive filesystems.

For a case-insensitive lookup match and if the case-exact dentryalready exists in the dcache, use it and return it.

If no entry exists with the exact case name, allocate new dentry withthe exact case, and return the spliced entry.

Parameters

conststructdentry*dentry

the negative dentry that was passed to the parent’s lookup func

conststructdentry*parent

parent dentry

conststructqstr*name

the case-exact name to be associated with the returned dentry

Return

true if names are same, or false

Parameters

conststructdentry*parent

parent dentry

conststructqstr*name

qstr of name we wish to find

Return

dentry, or NULL

Description

d_lookup searches the children of the parent dentry for the name inquestion. If the dentry is found its reference count is incremented and thedentry is returned. The caller must use dput to free the entry when it hasfinished using it.NULL is returned if the dentry does not exist.

Parameters

structdentry*dentry

The dentry to delete

Description

Turn the dentry into a negative dentry if possible, otherwiseremove it from the hash queues so it can be deleted later

Parameters

structdentry*entry

dentry to add to the hash

Description

Adds a dentry to the hash according to its name.

Parameters

structdentry*entry

dentry to add

structinode*inode

The inode to attach to this dentry

Description

This adds the entry to the hash queues and initializesinode.The entry was actually filled in earlier duringd_alloc().

Parameters

structinode*inode

the inode which may have a disconnected dentry

structdentry*dentry

a negative dentry which we want to point to the inode.

Description

If inode is a directory and has an IS_ROOT alias, then d_move that inplace of the given dentry and return it, else simply d_add the inodeto the dentry and return NULL.

If a non-IS_ROOT directory is found, the filesystem is corrupt, andwe should error out: directories can’t have multiple aliases.

This is needed in the lookup routine of any filesystem that is exportable(via knfsd) so that we can build dcache paths to directories effectively.

If a dentry was found and moved, then it is returned. Otherwise NULLis returned. This matches the expected return value of ->lookup.

Cluster filesystems may call this function with a negative, hashed dentry.In that case, we know that the inode will be a regular file, and also thiswill only occur during atomic_open. So we need to check for the dentrybeing already hashed only in the final case.

Parameters

structdentry*new_dentry

new dentry

structdentry*old_dentry

old dentry

Description

Returns true if new_dentry is a subdirectory of the parent (at any depth).Returns false otherwise.Caller must ensure that “new_dentry” is pinned before callingis_subdir()

Parameters

structdentry*dentry

dentry to get a reference to

Description

Given a live dentry, increment the reference count and return the dentry.Caller must holddentry->d_lock. Making sure that dentry is alive iscaller’s resonsibility. There are many conditions sufficient to guaranteethat; e.g. anything with non-negative refcount is alive, so’s anythinghashed, anything positive, anyone’s parent, etc.

Parameters

structdentry*dentry

dentry to get a reference to

Description

Given a dentry orNULL pointer increment the reference countif appropriate and return the dentry. A dentry will not bedestroyed when it has references. Conversely, a dentry withno references can disappear for any number of reasons, startingwith memory pressure. In other words, that primitive isused to clone an existing reference; using it on something withzero refcount is a bug.

NOTE

it will spin ifdentry->d_lock is held. From the deadlockavoidance point of view it is equivalent tospin_lock()/incrementrefcount/spin_unlock(), so calling it underdentry->d_lock isalways a bug; so’s calling it under ->d_lock on any of its descendents.

Parameters

conststructdentry*dentry

entry to check

Description

Returns true if the dentry passed is not currently hashed.

Parameters

conststructdentry*dentry

The dentry in question

Description

Returns true if the dentry represents either an absent name or a name thatdoesn’t map to an inode (ie. ->d_inode is NULL). The dentry could representa true miss, a whiteout that isn’t represented by a 0,0 chardev or afallthrough marker in an opaque directory.

Note! (1) This should be usedonly by a filesystem to examine its owndentries. It should not be used to look at some other filesystem’sdentries. (2) It should also be used in combination withd_inode() to getthe inode. (3) The dentry may have something attached to ->d_lower and thetype field of the flags may be set to something other than miss or whiteout.

Parameters

conststructdentry*dentry

The dentry in question

Description

Returns true if the dentry represents a name that maps to an inode(ie. ->d_inode is not NULL). The dentry might still represent a whiteout ifthat is represented on medium as a 0,0 chardev.

Note! (1) This should be usedonly by a filesystem to examine its owndentries. It should not be used to look at some other filesystem’sdentries. (2) It should also be used in combination withd_inode() to getthe inode.

Parameters

conststructdentry*dentry

The dentry to query

Description

This is the helper normal filesystems should use to get at their own inodesin their own dentries and ignore the layering superimposed upon them.

Parameters

conststructdentry*dentry

The dentry to query

Description

This is the helper normal filesystems should use to get at their own inodesin their own dentries and ignore the layering superimposed upon them.

Parameters

conststructdentry*upper

The upper layer

Description

This is the helper that should be used to get at the inode that will be usedif this dentry were to be opened as a file. The inode may be on the upperdentry or it may be on a lower dentry pinned by the upper.

Normal filesystems should not use this to access their own inodes.

Parameters

structdentry*dentry

the dentry to query

enumd_real_typetype

the type of real dentry (data or metadata)

Description

If dentry is on a union/overlay, then return the underlying, real dentry.Otherwise return the dentry itself.

See also:Overview of the Linux Virtual File System

Parameters

conststructdentry*dentry

The dentry to query

Description

If dentry is on a union/overlay, then return the underlying, real inode.Otherwise returnd_inode().

Parameters

structsuper_block*sb

superblock inode belongs to

structinode*inode

inode to initialise

gfp_tgfp

allocation flags

Description

These are initializations that need to be done on every inodeallocation as the fields are not initialised by slab allocation.If there are additional allocations requiredgfp is used.

Parameters

structinode*inode

inode

Description

This is a low-level filesystem helper to replace anydirect filesystem manipulation of i_nlink. In caseswhere we are attempting to track writes to thefilesystem, a decrement to zero means an imminentwrite when the file is truncated and actually unlinkedon the filesystem.

Parameters

structinode*inode

inode

Description

This is a low-level filesystem helper to replace anydirect filesystem manipulation of i_nlink. Seedrop_nlink() for why we care about i_nlink hitting zero.

Parameters

structinode*inode

inode

unsignedintnlink

new nlink (should be non-zero)

Description

This is a low-level filesystem helper to replace anydirect filesystem manipulation of i_nlink.

Parameters

structinode*inode

inode

Description

This is a low-level filesystem helper to replace anydirect filesystem manipulation of i_nlink. Currently,it is only here for parity withdec_nlink().

Parameters

structinode*inode

inode to add

Parameters

structinode*inode

unhashed inode

unsignedlonghashval

unsigned long value used to locate this object in theinode_hashtable.

Description

Add an inode to the inode hash for this superblock.

Parameters

structinode*inode

inode to unhash

Description

Remove an inode from the superblock.

Parameters

structsuper_block*sb

superblock to operate on

Description

Make sure that no inodes with zero refcount are retained. This iscalled by superblock shutdown after having SB_ACTIVE flag removed,so any inode reaching zero refcount during or after that call willbe immediately evicted.

Parameters

structsuper_block*sb

superblock

Description

Allocates a new inode for given superblock. The default gfp_maskfor allocations related to inode->i_mapping is GFP_HIGHUSER_MOVABLE.If HIGHMEM pages are unsuitable or it is known that pages allocatedfor the page cache are not reclaimable or migratable,mapping_set_gfp_mask() must be called with suitable flags on thenewly created inode’s mapping

Parameters

structinode*inode

new inode to unlock

Description

Called when the inode is fully initialised to clear the new state of theinode and wake up anyone waiting for the inode to finish initialisation.

Parameters

structinode*inode1

first inode to lock

structinode*inode2

second inode to lock

Description

Lock any non-NULL argument. Passed objects must not be directories.Zero, one or two objects may be locked by this function.

Parameters

structinode*inode1

first inode to unlock

structinode*inode2

second inode to unlock

Parameters

structinode*inode

pre-allocated inode to use for insert to cache

unsignedlonghashval

hash value (usually inode number) to get

int(*test)(structinode*,void*)

callback used for comparisons between inodes

int(*set)(structinode*,void*)

callback used to initialize a newstructinode

void*data

opaque data pointer to pass totest andset

Description

Search for the inode specified byhashval anddata in the inode cache,and if present return it with an increased reference count. This is avariant ofiget5_locked() that doesn’t allocate an inode.

If the inode is not present in the cache, insert the pre-allocated inode andreturn it locked, hashed, and with the I_NEW flag set. The file system getsto fill it in before unlocking it viaunlock_new_inode().

Note that bothtest andset are called with the inode_hash_lock held, sothey can’t sleep.

Parameters

structsuper_block*sb

super block of file system

unsignedlonghashval

hash value (usually inode number) to get

int(*test)(structinode*,void*)

callback used for comparisons between inodes

int(*set)(structinode*,void*)

callback used to initialize a newstructinode

void*data

opaque data pointer to pass totest andset

Description

Search for the inode specified byhashval anddata in the inode cache,and if present return it with an increased reference count. This is ageneralized version ofiget_locked() for file systems where the inodenumber is not sufficient for unique identification of an inode.

If the inode is not present in the cache, allocate and insert a new inodeand return it locked, hashed, and with the I_NEW flag set. The file systemgets to fill it in before unlocking it viaunlock_new_inode().

Note that bothtest andset are called with the inode_hash_lock held, sothey can’t sleep.

Parameters

structsuper_block*sb

super block of file system

unsignedlonghashval

hash value (usually inode number) to get

int(*test)(structinode*,void*)

callback used for comparisons between inodes

int(*set)(structinode*,void*)

callback used to initialize a newstructinode

void*data

opaque data pointer to pass totest andset

Description

This is equivalent to iget5_locked, except thetest callback musttolerate the inode not being stable, including being mid-teardown.

Parameters

structsuper_block*sb

super block of file system

unsignedlongino

inode number to get

Description

Search for the inode specified byino in the inode cache and if presentreturn it with an increased reference count. This is for file systemswhere the inode number is sufficient for unique identification of an inode.

If the inode is not in cache, allocate a new inode and return it locked,hashed, and with the I_NEW flag set. The file system gets to fill it inbefore unlocking it viaunlock_new_inode().

Parameters

structsuper_block*sb

superblock

ino_tmax_reserved

highest reserved inode number

Description

Obtain an inode number that is unique on the system for a givensuperblock. This is used by file systems that have no naturalpermanent inode numbering system. An inode number is returned thatis higher than the reserved limit but unique.

BUGS:With a large number of inodes live on the file system this functioncurrently becomes quite slow.

Parameters

structsuper_block*sb

super block of file system to search

unsignedlonghashval

hash value (usually inode number) to search for

int(*test)(structinode*,void*)

callback used for comparisons between inodes

void*data

opaque data pointer to pass totest

bool*isnew

return argument telling whether I_NEW was set whenthe inode was found in hash (the caller needs towait for I_NEW to clear)

Description

Search for the inode specified byhashval anddata in the inode cache.If the inode is in the cache, the inode is returned with an incrementedreference count.

Note

I_NEW is not waited upon so you have to be very careful what you dowith the returned inode. You probably should be usingilookup5() instead.

Note2:test is called with the inode_hash_lock held, so can’t sleep.

Parameters

structsuper_block*sb

super block of file system to search

unsignedlonghashval

hash value (usually inode number) to search for

int(*test)(structinode*,void*)

callback used for comparisons between inodes

void*data

opaque data pointer to pass totest

Description

Search for the inode specified byhashval anddata in the inode cache,and if the inode is in the cache, return the inode with an incrementedreference count. Waits on I_NEW before returning the inode.returned with an incremented reference count.

This is a generalized version ofilookup() for file systems where theinode number is not sufficient for unique identification of an inode.

Note

test is called with the inode_hash_lock held, so can’t sleep.

Parameters

structsuper_block*sb

super block of file system to search

unsignedlongino

inode number to search for

Description

Search for the inodeino in the inode cache, and if the inode is in thecache, the inode is returned with an incremented reference count.

Parameters

structsuper_block*sb

super block of file system to search

unsignedlonghashval

hash value (usually inode number) to search for

int(*match)(structinode*,unsignedlong,void*)

callback used for comparisons between inodes

void*data

opaque data pointer to pass tomatch

Description

Search for the inode specified byhashval anddata in the inodecache, where the helper functionmatch will return 0 if the inodedoes not match, 1 if the inode does match, and -1 if the searchshould be stopped. Thematch function must be responsible fortaking the i_lock spin_lock and checking i_state for an inode beingfreed or being initialized, and incrementing the reference countbefore returning 1. It also must not sleep, since it is called withthe inode_hash_lock spinlock held.

This is a even more generalized version ofilookup5() when thefunction must never block ---find_inode() can block in__wait_on_freeing_inode() --- or when the caller can not incrementthe reference count because the resultingiput() might cause aninode eviction. The tradeoff is that thematch funtion must bevery carefully implemented.

Parameters

structsuper_block*sb

Super block of file system to search

unsignedlonghashval

Key to hash

int(*test)(structinode*,void*)

Function to test match on an inode

void*data

Data for test function

Description

Search for the inode specified byhashval anddata in the inode cache,where the helper functiontest will return 0 if the inode does not matchand 1 if it does. Thetest function must be responsible for taking thei_lock spin_lock and checking i_state for an inode being freed or beinginitialized.

If successful, this will return the inode for which thetest functionreturned 1 and NULL otherwise.

Thetest function is not permitted to take a ref on any inode presented.It is also not permitted to sleep.

The caller must hold the RCU read lock.

Parameters

structsuper_block*sb

Super block of file system to search

unsignedlongino

The inode number to match

Description

Search for the inode specified byhashval anddata in the inode cache,where the helper functiontest will return 0 if the inode does not matchand 1 if it does. Thetest function must be responsible for taking thei_lock spin_lock and checking i_state for an inode being freed or beinginitialized.

If successful, this will return the inode for which thetest functionreturned 1 and NULL otherwise.

Thetest function is not permitted to take a ref on any inode presented.It is also not permitted to sleep.

The caller must hold the RCU read lock.

Parameters

structinode*inode

inode to put

Description

Puts an inode, dropping its usage count. If the inode use count hitszero, the inode is then freed and may also be destroyed.

Consequently,iput() can sleep.

Parameters

structinode*inode

inode to put

Parameters

structinode*inode

inode owning the block number being requested

sector_t*block

pointer containing the block to find

Description

Replaces the value in*block with the block number on the device holdingcorresponding to the requested block number in the file.That is, asked for block 4 of inode 1 the function will replace the4 in*block, with disk block relative to the disk start that holds thatblock of the file.

Returns -EINVAL in case of error, 0 otherwise. If mapping falls into ahole, returns 0 and*block is also set to 0.

Parameters

structinode*inode

inode to be updated

intflags

S_* flags that needed to be updated

Description

The update_time function is called when an inode’s timestamps need to beupdated for a read or write operation. This function handles updating theactual timestamps. It’s up to the caller to ensure that the inode is markeddirty appropriately.

In the case where any of S_MTIME, S_CTIME, or S_VERSION need to be updated,attempt to update all three of them. S_ATIME updates can be handledindependently of the rest.

Returns a set of S_* flags indicating which values changed.

Parameters

structinode*inode

inode to be updated

intflags

S_* flags that needed to be updated

Description

The update_time function is called when an inode’s timestamps need to beupdated for a read or write operation. In the case where any of S_MTIME, S_CTIME,or S_VERSION need to be updated we attempt to update all three of them. S_ATIMEupdates can be handled done independently of the rest.

Returns a S_* mask indicating which fields were updated.

Parameters

structfile*file

file to remove privileges from

Description

When file is modified by a write or truncation ensure that specialfile privileges are removed.

Return

0 on success, negative errno on failure.

Parameters

structinode*inode

inode.

Description

Return the current time truncated to the time granularity supported bythe fs, as suitable for a ctime/mtime change. If the ctime is flaggedas having been QUERIED, get a fine-grained timestamp, but don’t updatethe floor.

For a multigrain inode, this is effectively an estimate of the timestampthat a file would receive. An actual update must go throughinode_set_ctime_current().

Parameters

structfile*file

file accessed

Description

Update the mtime and ctime members of an inode and mark the inode forwriteback. Note that this function is meant exclusively for usage inthe file write path of filesystems, and filesystems may choose toexplicitly ignore updates via this function with the _NOCMTIME inodeflag, e.g. for network filesystem where these imestamps are handledby the server. This can return an error for file systems who need toallocate space in order to update an inode.

Return

0 on success, negative errno on failure.

Parameters

structfile*file

file that was modified

Description

When file has been modified ensure that specialfile privileges are removed and time settings are updated.

Context

Caller must hold the file’s inode lock.

Return

0 on success, negative errno on failure.

Parameters

structkiocb*iocb

iocb that was modified

Description

When file has been modified ensure that specialfile privileges are removed and time settings are updated.

Context

Caller must hold the file’s inode lock.

Return

0 on success, negative errno on failure.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was created from

structinode*inode

New inode

conststructinode*dir

Directory inode

umode_tmode

mode of the new inode

Description

If the inode has been created through an idmapped mount the idmap ofthe vfsmount must be passed throughidmap. This function will then takecare to map the inode according toidmap before checking permissionsand initializing i_uid and i_gid. On non-idmapped mounts or if permissionchecking is to be performed on the raw inode simply passnop_mnt_idmap.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was found from

conststructinode*inode

inode being checked

Description

Return true if current either has CAP_FOWNER in a namespace with theinode owner uid mapped, or owns the file.

If the inode has been found through an idmapped mount the idmap ofthe vfsmount must be passed throughidmap. This function will then takecare to map the inode according toidmap before checking permissions.On non-idmapped mounts or if permission checking is to be performed on theraw inode simply passnop_mnt_idmap.

Parameters

structinode*inode

inode to wait for

Description

Waits for all pending direct I/O requests to finish so that we canproceed with a truncate or equivalent operation.

Must be called under a lock that serializes taking new referencesto i_dio_count, usually by inode->i_rwsem.

Parameters

structtimespec64t

Timespec

structinode*inode

inode being updated

Description

Truncate a timespec to the granularity supported by the fscontaining the inode. Always rounds down. gran mustnot be 0 nor greater than a second (NSEC_PER_SEC, or 10^9 ns).

Parameters

structinode*inode

inode

Description

Set the inode’s ctime to the current value for the inode. Returns thecurrent value that was assigned. If this is not a multigrain inode, then weset it to the later of the coarse time and floor value.

If it is multigrain, then we first see if the coarse-grained timestamp isdistinct from what is already there. If so, then use that. Otherwise, get afine-grained timestamp.

After that, try to swap the new value into i_ctime_nsec. Accept theresulting ctime, regardless of the outcome of the swap. If it hasalready been replaced, then that timestamp is later than the earlierunacceptable one, and is thus acceptable.

Parameters

structinode*inode

inode to update

structtimespec64update

timespec64 to set the ctime

Description

Attempt to atomically update the ctime on behalf of a delegation holder.

The nfs server can call back the holder of a delegation to get updatedinode attributes, including the mtime. When updating the mtime, updatethe ctime to a value at least equal to that.

This can race with concurrent updates to the inode, in whichcase the update is skipped.

Note that this works even when multigrain timestamps are not enabled,so it is used in either case.

Parameters

structmnt_idmap*idmap

idmap of the mountinode was found from

conststructinode*inode

inode to check

vfsgid_tvfsgid

the new/current vfsgid ofinode

Description

Check whethervfsgid is in the caller’s group list or if the caller isprivileged with CAP_FSETID overinode. This can be used to determinewhether the setgid bit can be kept or must be dropped.

Return

true if the caller is sufficiently privileged, false if not.

Parameters

structmnt_idmap*idmap

idmap of the mount the inode was created from

conststructinode*dir

parent directory inode

umode_tmode

mode of the file to be created indir

Description

If themode of the new file has both the S_ISGID and S_IXGRP bitraised anddir has the S_ISGID bit raised ensure that the caller iseither in the group of the parent directory or they have CAP_FSETIDin their user namespace and are privileged over the parent directory.In all other cases, strip the S_ISGID bit frommode.

Return

the new mode to use for the file

Parameters

structinode*inode

Inode to mark bad

Description

When an inode cannot be read due to a media or remote networkfailure this function makes the inode “bad” and causes I/O operationson it to fail from this point on.

Parameters

structinode*inode

inode to test

Description

Returns true if the inode in question has been marked as bad.

Parameters

structinode*inode

The inode to discard

Description

Mark an under-construction inode as dead and release it.

Parameters

structsuper_block*s

superblock to deactivate

Description

Drops an active reference to superblock, converting it into a temporaryone if there is no other active references left. In that case wetell fs driver to shut it down and drop the temporary reference wehad just acquired.

Caller holds exclusive lock on superblock; that lock is released.

Parameters

structsuper_block*s

superblock to deactivate

Description

Variant ofdeactivate_locked_super(), except that superblock isnotlocked by caller. If we are going to drop the final active reference,lock will be acquired prior to that.

Parameters

structsuper_block*sb

superblock to retire

Description

The function marks superblock to be ignored in superblock test, whichprevents it from being reused for any new mounts. If the superblock hasa private bdi, it also unregisters it, but doesn’t reduce the refcountof the superblock to prevent potential races. The refcount is reducedbygeneric_shutdown_super(). The function can not be calledconcurrently withgeneric_shutdown_super(). It is safe to call thefunction multiple times, subsequent calls have no effect.

The marker will affect the re-use only for block-device-basedsuperblocks. Other superblocks will still get marked if this functionis used, but that will not affect their reusability.

Parameters

structsuper_block*sb

superblock to kill

Description

generic_shutdown_super() does all fs-independent work on superblockshutdown. Typical ->kill_sb() should pick all fs-specific objectsthat need destruction out of superblock, callgeneric_shutdown_super()and release aforementioned objects. Note: dentries and inodes _are_taken care of and do not need specific handling.

Upon calling this function, the filesystem may no longer alter orrearrange the set of dentries belonging to this super_block, nor may itchange the attachments of dentries to inodes.

Parameters

structfs_context*fc

Filesystem context.

int(*test)(structsuper_block*,structfs_context*)

Comparison callback

int(*set)(structsuper_block*,structfs_context*)

Setup callback

Description

Create a new superblock or find an existing one.

Thetest callback is used to find a matching existing superblock.Whether or not the requested parameters infc are taken into accountis specific to thetest callback that is used. They may even becompletely ignored.

If an extant superblock is matched, it will be returned unless:

1. the namespace the filesystem contextfc and the extantsuperblock’s namespace differ

2. the filesystem contextfc has requested that reusing an extantsuperblock is not allowed

In both cases EBUSY will be returned.

If no match is made, a new superblock will be allocated and basicinitialisation will be performed (s_type, s_fs_info and s_id will beset and theset callback will be invoked), the superblock will bepublished and it will be returned in a partially constructed statewith SB_BORN and SB_ACTIVE as yet unset.

Return

On success, an extant or newly created superblock isreturned. On failure an error pointer is returned.

Parameters

structfile_system_type*type

filesystem type superblock should belong to

int(*test)(structsuper_block*,void*)

comparison callback

int(*set)(structsuper_block*,void*)

setup callback

intflags

mount flags

void*data

argument to each of them

Parameters

structfile_system_type*type

fs type

void(*f)(structsuper_block*,void*)

function to call

void*arg

argument to pass to it

Description

Scans the superblock list and calls given function, passing itlocked superblock and given argument.

Parameters

dev_t*p

Pointer to a dev_t.

Description

Filesystems which don’t use real block devices can call this functionto allocate a virtual block device.

Context

Any context. Frequently called while holding sb_lock.

Return

0 on success, -EMFILE if there are no anonymous bdevs leftor -ENOMEM if memory allocation failed.

Parameters

structfs_context*fc

Filesystem context.

dev_tdev

device number

Description

Find or create a superblock using the provided device number thatwill be stored in fc->sget_key.

If an extant superblock is matched, then that will be returned withan elevated reference count that the caller must transfer or discard.

If no match is made, a new superblock will be allocated and basicinitialisation will be performed (s_type, s_fs_info, s_id, s_dev willbe set). The superblock will be published and it will be returned ina partially constructed state with SB_BORN and SB_ACTIVE as yetunset.

Return

an existing or newly created superblock on success, an errorpointer on failure.

Parameters

structfs_context*fc

The filesystem context holding the parameters

int(*fill_super)(structsuper_block*sb,structfs_context*fc)

Helper to initialise a new superblock

unsignedintflags

GET_TREE_BDEV_* flags

Parameters

structfs_context*fc

The filesystem context holding the parameters

int(*fill_super)(structsuper_block*,structfs_context*)

Helper to initialise a new superblock

Parameters

structfs_context*fc

The superblock configuration context.

Description

The filesystem is invoked to get or create a superblock which can then laterbe used for mounting. The filesystem places a pointer to the root to beused for mounting infc->root.

Parameters

structsuper_block*sb

the super to lock

enumfreeze_holderwho

context that wants to freeze

constvoid*freeze_owner

owner of the freeze

Description

Syncs the super to make sure the filesystem is consistent and calls the fs’sfreeze_fs. Subsequent calls to this without first thawing the fs may return-EBUSY.

who should be:*FREEZE_HOLDER_USERSPACE if userspace wants to freeze the fs;*FREEZE_HOLDER_KERNEL if the kernel wants to freeze the fs.*FREEZE_MAY_NEST whether nesting freeze and thaw requests is allowed.

Thewho argument distinguishes between the kernel and userspace trying tofreeze the filesystem. Although there cannot be multiple kernel freezes ormultiple userspace freezes in effect at any given time, the kernel anduserspace can both hold a filesystem frozen. The filesystem remains frozenuntil there are no kernel or userspace freezes in effect.

A filesystem may hold multiple devices and thus a filesystems may befrozen through the block layer via multiple block devices. In thiscase the request is marked as being allowed to nest by passingFREEZE_MAY_NEST. The filesystem remains frozen until all blockdevices are unfrozen. If multiple freezes are attempted withoutFREEZE_MAY_NEST -EBUSY will be returned.

During this function, sb->s_writers.frozen goes through these values:

SB_UNFROZEN: File system is normal, all writes progress as usual.

SB_FREEZE_WRITE: The file system is in the process of being frozen. Newwrites should be blocked, though page faults are still allowed. We wait forall writes to complete and then proceed to the next stage.

SB_FREEZE_PAGEFAULT: Freezing continues. Now also page faults are blockedbut internal fs threads can still modify the filesystem (although theyshould not dirty new pages or inodes), writeback can run etc. After waitingfor all running page faults we sync the filesystem which will clean alldirty pages and inodes (no new dirty pages or inodes can be created whensync is running).

SB_FREEZE_FS: The file system is frozen. Now all internal sources of fsmodification are blocked (e.g. XFS preallocation truncation on inodereclaim). This is usually implemented by blocking new transactions forfilesystems that have them and need this additional guard. After allinternal writers are finished we call ->freeze_fs() to finish filesystemfreezing. Then we transition to SB_FREEZE_COMPLETE state. This state ismostly auxiliary for filesystems to verify they do not modify frozen fs.

sb->s_writers.frozen is protected by sb->s_umount.

Return

If the freeze was successful zero is returned. If the freezefailed a negative error code is returned.

Parameters

structsuper_block*sb

the super to thaw

enumfreeze_holderwho

context that wants to freeze

constvoid*freeze_owner

owner of the freeze

Description

Unlocks the filesystem and marks it writeable again afterfreeze_super()if there are no remaining freezes on the filesystem.

who should be:*FREEZE_HOLDER_USERSPACE if userspace wants to thaw the fs;*FREEZE_HOLDER_KERNEL if the kernel wants to thaw the fs.*FREEZE_MAY_NEST whether nesting freeze and thaw requests is allowed

A filesystem may hold multiple devices and thus a filesystems mayhave been frozen through the block layer via multiple block devices.The filesystem remains frozen until all block devices are unfrozen.

Parameters

structfile_lock_context*flctx

file lock context

fl_owner_towner

lock owner

Description

Return values:

true:owner has at least one blockerfalse:owner has no blockers

Parameters

structfile_lock*waiter

the lock which was waiting

Description

lockd/nfsd need to disconnect the lock while working on it.

Parameters

structfile*filp

The file to apply the lock to

structfile_lock*fl

The lock to be applied

structfile_lock*conflock

Place to return a copy of the conflicting lock, if found.

Description

Add a POSIX style lock to a file.We merge adjacent & overlapping locks whenever possible.POSIX locks are sorted by owner task, then by starting address

Note that if called with an FL_EXISTS argument, the caller may determinewhether or not a lock was successfully freed by testing the returnvalue for -ENOENT.

Parameters

structinode*inode

the inode of the file to return

unsignedintflags

LEASE_BREAK_* flags

Description

break_lease (inlined for speed) has checked there already is at leastsome kind of lock (maybe a lease) on this file. Leases are broken ona call to open() ortruncate(). This function can block waiting for thelease break unless you specify LEASE_BREAK_NONBLOCK.

Parameters

structinode*inode

the inode

structtimespec64*time

pointer to a timespec which contains the last modified time

Description

This is to force NFS clients to flush their caches for files withexclusive leases. The justification is that if someone has anexclusive lease, then they could be modifying it.

Parameters

structfile*filp

file pointer

intarg

type of lease to obtain

structfile_lease**flp

input - file_lock to use, output - file_lock inserted

void**priv

private data for lm_setup (may be NULL if lm_setupdoesn’t require it)

Description

The (input) flp->fl_lmops->lm_break function is requiredbybreak_lease().

Parameters

structfile*filp

file pointer

intarg

type of lease to obtain

structfile_lease**lease

file_lock to use when adding a lease

void**priv

private info for lm_setup when adding a lease (may beNULL if lm_setup doesn’t require it)

Description

Call this to establish a lease on the file. The “lease” argument is notused for F_UNLCK requests and may be NULL. For commands that set or alteran existing lease, the(*lease)->fl_lmops->lm_break operation must beset; if not, this function will return -ENOLCK (and generate a scary-lookingstack trace).

The “priv” pointer is passed directly to the lm_setup function as-is. Itmay be NULL if the lm_setup operation doesn’t require it.

Parameters

structinode*inode

inode of the file to apply to

structfile_lock*fl

The lock to be applied

Description

Apply a POSIX or FLOCK style lock request to an inode.

Parameters

structfile*filp

The file to test lock for

structfile_lock*fl

The byte-range in the file to test; also used to hold result

Description

On entry,fl does not contain a lock, but identifies a range (fl_start, fl_end)in the file (c.flc_file), and an owner (c.flc_owner) for whom existing locksshould be ignored. c.flc_type and c.flc_flags are ignored.Both fl_lmops and fl_ops infl must be NULL.Returns -ERRNO on failure. Indicates presence of conflicting lock bysetting fl->fl_type to something other than F_UNLCK.

Ifvfs_test_lock() does find a lock and return it, the caller mustuselocks_free_lock() orlocks_release_private() on the returned lock.

Parameters

structfile*filp

The file to apply the lock to

unsignedintcmd

type of locking operation (F_SETLK, F_GETLK, etc.)

structfile_lock*fl

The lock to be applied

structfile_lock*conf

Place to return a copy of the conflicting lock, if found.

Description

A caller that doesn’t care about the conflicting lock may pass NULLas the final argument.

If the filesystem defines a private ->lock() method, thenconf willbe left unchanged; so a caller that cares should initialize it tosome acceptable default.

To avoid blocking kernel daemons, such as lockd, that need to acquire POSIXlocks, the ->lock() interface may return asynchronously, before the lock hasbeen granted or denied by the underlying filesystem, if (and only if)lm_grant is set. Additionally FOP_ASYNC_LOCK in file_operations fop_flagsneed to be set.

Callers expecting ->lock() to return asynchronously will only use F_SETLK,not F_SETLKW; they will set FL_SLEEP if (and only if) the request is for ablocking lock. When ->lock() does return asynchronously, it must returnFILE_LOCK_DEFERRED, and call ->lm_grant() when the lock request completes.If the request is for non-blocking lock the file system should returnFILE_LOCK_DEFERRED then try to get the lock and call the callback routinewith the result. If the request timed out the callback routine will return anonzero return code and the file system should release the lock. The filesystem is also responsible to keep a corresponding posix lock when itgrants a lock so the VFS can find out which locks are locally held and dothe correct lock cleanup when required.The underlying filesystem must not drop the kernel lock or call->lm_grant() before returning to the caller with a FILE_LOCK_DEFERREDreturn code.

Parameters

structfile*filp

The file to apply the unblock to

structfile_lock*fl

The lock to be unblocked