Directory entry. More...

Collaboration diagram for Dentry:

Detailed Description

Directory entry.

A dentry represents the actual name in the filesystem hierarchy. It can be either positive, meaning it has an associated vnode, or negative, meaning it does not have an associated vnode.

Mountpoints and Root Dentries

The difference between a mountpoint dentry and a root dentry can be a bit confusing, so here is a quick explanation. When a filesystem is mounted the dentry that it gets mounted to becomes a mountpoint, any data that was there before becomes hidden and when we traverse to that dentry we "jump" to the root dentry of the mounted filesystem. The root dentry of the mounted filesystem is simply the root directory of that filesystem.

This means that the mountpoint does not "become" the root of the mounted filesystem, it simply points to it.

Finally, note that just because a dentry is a mountpoint does not mean that it can be traversed by the current process, a process can only traverse a mountpoint if it is visible in its namespace, if its not visible the dentry acts exactly like a normal dentry.

Data Structures
struct	dir_ctx_t
	Directory context used to iterate over directory entries. More...

struct	dentry_ops_t
	Dentry operations structure. More...

struct	dentry_t
	Directory entry structure. More...

Macros
#define	DENTRY_IS_ROOT(dentry) ((dentry)->parent == (dentry))
	Macro to check if a dentry is the root entry in its filesystem.

#define	DENTRY_IS_POSITIVE(dentry) ((dentry)->vnode != NULL)
	Check if a dentry is positive.

#define	DENTRY_IS_REGULAR(dentry) (DENTRY_IS_POSITIVE(dentry) && (dentry)->vnode->type == VREG)
	Check if the vnode associated with a dentry is a regular file.

#define	DENTRY_IS_DIR(dentry) (DENTRY_IS_POSITIVE(dentry) && (dentry)->vnode->type == VDIR)
	Check if the vnode associated with a dentry is a directory.

#define	DENTRY_IS_SYMLINK(dentry) (DENTRY_IS_POSITIVE(dentry) && (dentry)->vnode->type == VSYMLINK)
	Check if the vnode associated with a dentry is a symbolic link.

#define	DENTRY_DOTS_AMOUNT 2
	The amount of special entries "." and ".." that `dentry_iterate_dots()` emits.

Typedefs
typedef uint64_t	dentry_id_t
	Dentry ID type.

Functions
dentry_t *	dentry_new (superblock_t superblock, dentry_t parent, const char *name)
	Create a new dentry.

void	dentry_remove (dentry_t *dentry)
	Remove a dentry from the dentry cache.

dentry_t *	dentry_rcu_get (const dentry_t parent, const char name, size_t length)
	Get a dentry from the dentry cache in an RCU read-side critical section without traversing mountpoints.

dentry_t *	dentry_lookup (dentry_t parent, const char name, size_t length)
	Lookup a dentry for the given name without traversing mountpoints.

void	dentry_make_positive (dentry_t dentry, vnode_t vnode)
	Make a dentry positive by associating it with an vnode.

bool	dentry_iterate_dots (dentry_t dentry, dir_ctx_t ctx)
	Helper function to iterate over the special entries "." and "..".

uint64_t	dentry_generic_iterate (dentry_t dentry, dir_ctx_t ctx)
	Helper function for a basic iterate.

Macro Definition Documentation

◆ DENTRY_IS_ROOT

#define DENTRY_IS_ROOT ( dentry ) ((dentry)->parent == (dentry))

Macro to check if a dentry is the root entry in its filesystem.

A dentry is considered the root if its parent is itself.

Parameters

dentry The dentry to check.

Returns: true if the dentry is the root, false otherwise.

Definition at line 59 of file dentry.h.

◆ DENTRY_IS_POSITIVE

#define DENTRY_IS_POSITIVE ( dentry ) ((dentry)->vnode != NULL)

Check if a dentry is positive.

Parameters

dentry The dentry to check.

Returns: true if the dentry is positive, false if it is negative.

Definition at line 67 of file dentry.h.

◆ DENTRY_IS_REGULAR

#define DENTRY_IS_REGULAR ( dentry ) (DENTRY_IS_POSITIVE(dentry) && (dentry)->vnode->type == VREG)

Check if the vnode associated with a dentry is a regular file.

Parameters

dentry The dentry to check.

Returns: true if the dentry is a regular file, false otherwise or if the dentry is negative.

Definition at line 75 of file dentry.h.

◆ DENTRY_IS_DIR

#define DENTRY_IS_DIR ( dentry ) (DENTRY_IS_POSITIVE(dentry) && (dentry)->vnode->type == VDIR)

Check if the vnode associated with a dentry is a directory.

Parameters

dentry The dentry to check.

Returns: true if the dentry is a directory, false otherwise or if the dentry is negative.

Definition at line 83 of file dentry.h.

◆ DENTRY_IS_SYMLINK

#define DENTRY_IS_SYMLINK ( dentry ) (DENTRY_IS_POSITIVE(dentry) && (dentry)->vnode->type == VSYMLINK)

Check if the vnode associated with a dentry is a symbolic link.

Parameters

dentry The dentry to check.

Returns: true if the dentry is a symbolic link, false otherwise or if the dentry is negative.

Definition at line 91 of file dentry.h.

◆ DENTRY_DOTS_AMOUNT

#define DENTRY_DOTS_AMOUNT 2

The amount of special entries "." and ".." that dentry_iterate_dots() emits.

Definition at line 239 of file dentry.h.

Typedef Documentation

◆ dentry_id_t

typedef uint64_t dentry_id_t

Dentry ID type.

Definition at line 49 of file dentry.h.

Function Documentation

◆ dentry_new()

dentry_t * dentry_new	(	superblock_t *	superblock,
		dentry_t *	parent,
		const char *	name
	)

Create a new dentry.

Will not add the dentry to its parent's list of children but it will appear in the dentry cache as a negative dentry until dentry_make_positive() is called making it positive. This is needed to solve some race conditions when creating new files. While the dentry is negative it is not possible to create another dentry of the same name in the same parent, and any lookup to the dentry will fail until it is made positive.

There is no dentry_free() instead use UNREF().

Parameters

superblock	The superblock the dentry belongs to.
parent	The parent dentry, can be `NULL`.
name	The name of the dentry, can be `NULL` if `parent` is also `NULL`.

Returns: On success, the new dentry. On failure, returns NULL and errno is set.

Definition at line 134 of file dentry.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dentry_remove()

void dentry_remove ( dentry_t * dentry )

Remove a dentry from the dentry cache.

Note: Will not free the dentry, use UNREF() for that.

Parameters

dentry The dentry to remove.

Definition at line 178 of file dentry.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dentry_rcu_get()

dentry_t * dentry_rcu_get	(	const dentry_t *	parent,
		const char *	name,
		size_t	length
	)

Get a dentry from the dentry cache in an RCU read-side critical section without traversing mountpoints.

Will only check the dentry cache and return a dentry if it exists there, will not call the filesystem's lookup function.

Warning: Will NOT return a reference to the dentry, the caller must ensure that this function is called in a RCU read critical section.

Parameters

parent	The parent path.
name	The name of the dentry.
length	The length of the name.

Returns: On success, the dentry, might be negative. On failure, returns NULL and errno is set.

Definition at line 188 of file dentry.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dentry_lookup()

dentry_t * dentry_lookup	(	dentry_t *	parent,
		const char *	name,
		size_t	length
	)

Lookup a dentry for the given name without traversing mountpoints.

If the dentry is not found in the dentry cache, the filesystem's lookup function will be called to try to find it.

Parameters

parent	The parent dentry.
name	The name of the dentry.
length	The length of the name.

Returns: On success, a reference to the dentry, might be negative. On failure, returns NULL and errno is set.

Definition at line 229 of file dentry.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dentry_make_positive()

void dentry_make_positive	(	dentry_t *	dentry,
		vnode_t *	vnode
	)

Make a dentry positive by associating it with an vnode.

This function is expected to be protected by the parent vnode's mutex.

Parameters

dentry	The dentry to make positive, or `NULL` for no-op.
vnode	The vnode to associate with the dentry, or `NULL` for no-op.

Definition at line 289 of file dentry.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ dentry_iterate_dots()

bool dentry_iterate_dots	(	dentry_t *	dentry,
		dir_ctx_t *	ctx
	)

Helper function to iterate over the special entries "." and "..".

Intended to be used in filesystem iterate implementations.

Parameters

dentry	The directory dentry to iterate over.
ctx	The directory context to use for iteration.

Returns: true if the iteration should continue, false if it should stop.

Definition at line 304 of file dentry.c.

Here is the caller graph for this function:

◆ dentry_generic_iterate()

uint64_t dentry_generic_iterate	(	dentry_t *	dentry,
		dir_ctx_t *	ctx
	)

Helper function for a basic iterate.

Definition at line 325 of file dentry.c.

Here is the call graph for this function:

Detailed Description

Mountpoints and Root Dentries

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ DENTRY_IS_ROOT

◆ DENTRY_IS_POSITIVE

◆ DENTRY_IS_REGULAR

◆ DENTRY_IS_DIR

◆ DENTRY_IS_SYMLINK

◆ DENTRY_DOTS_AMOUNT

Typedef Documentation

◆ dentry_id_t

Function Documentation

◆ dentry_new()

◆ dentry_remove()

◆ dentry_rcu_get()

◆ dentry_lookup()

◆ dentry_make_positive()

◆ dentry_iterate_dots()

◆ dentry_generic_iterate()