dir.h File Reference

Go to the source code of this file.

Functions
DIR *	tard_fdopendir (void *ctx, int fd)
	TARFS Directory API: tard_opendir(), tard_fdopendir(), tard_closedir(), tard_telldir(), tard_seekdir().
DIR *	tard_opendir (void *ctx, const char *name)
	Open a directory for reading.
int	tard_closedir (void *ctx, DIR *pdir)
	Close a directory stream.
struct dirent *	tard_readdir (void *ctx, DIR *pdir)
	Read the next directory entry.
long	tard_telldir (void *ctx, DIR *pdir)
	Return the current directory position.
void	tard_seekdir (void *ctx, DIR *pdir, long offset)
	Reposition a directory stream.
int	tard_dirfd (void *ctx, DIR *pdir)
	The function dirfd() returns the file descriptor associated with the directory stream pdir.

Function Documentation

tard_closedir()

int tard_closedir	(	void *	ctx,
		DIR *	pdir )

Close a directory stream.

Releases all resources associated with a directory stream previously returned by tard_opendir().

Parameters

ctx	TARFS filesystem context.
pdir	Directory stream.

Returns

0 on success, or -1 on failure.

Releases all resources associated with a directory stream previously returned by tard_opendir().

Definition at line 260 of file dir.c.

References log, tarf_close(), tarfs_getfs(), tarfs_os_free(), and tarfs_unref().

tard_dirfd()

int tard_dirfd	(	void *	ctx,
		DIR *	pdir )

The function dirfd() returns the file descriptor associated with the directory stream pdir.

The function tard_dirfd() returns the file descriptor associated with the directory stream pdir.

This file descriptor is the one used internally by the directory stream. As a result, it is useful only for functions which do not depend on or alter the file position, such as fstat(2) and fchdir(2). It will be automatically closed when closedir(3) is called.

Parameters

ctx	TARFS filesystem context.
pdir	Directory stream.

Returns

a file descriptor

The function dirfd() returns the file descriptor associated with the directory stream pdir.

TODO: right now we can implement posix's dirfd() on ESP32 for number of reasons: TODO: 1. there is a no-op implementation of dirfd() in ESP-IDF/newlib
TODO: 2. there is no mechanism to convert local FD to a global FD except for ugly hack with offsets

Definition at line 397 of file dir.c.

tard_fdopendir()

DIR * tard_fdopendir	(	void *	ctx,
		int	fd )

TARFS Directory API: tard_opendir(), tard_fdopendir(), tard_closedir(), tard_telldir(), tard_seekdir().

Associate an open directory file descriptor with a directory stream.

tard_fdopendir() is the only function that allocates memory for the DIR structure. tard_opendir() internally calls tard_fdopendir().

How it works: opendir() calls open(O_DIRECTORY) and positions its internal inode pointer at the requested directory. Subsequent calls to readdir() advance this pointer through the inode list (inodes are linked alphabetically via ->in_next) until the next inode no longer matches the directory prefix specified in opendir().

Note on the dirent structure:

Unlike POSIX, where d_off is an opaque implementation-defined value, TARFS stores the logical directory position in this field.

Specifically, d_off is the zero-based index of the next directory entry. The value can be saved and later passed to tard_seekdir() to resume directory traversal.

Associate an open directory file descriptor with a directory stream.

Creates a directory stream from an existing directory file descriptor. After a successful call, the file descriptor is owned by the returned directory stream and must not be closed directly. It will be closed automatically by tard_closedir().

Parameters

ctx	TARFS context.
fd	Directory file descriptor obtained by tarf_open() with O_DIRECTORY.

Returns

A pointer to a directory stream on success, or NULL on failure with errno set appropriately.

TARFS Directory API: tard_opendir(), tard_fdopendir(), tard_closedir(), tard_telldir(), tard_seekdir().

Creates a directory stream from an existing directory file descriptor. After a successful call, the file descriptor is owned by the returned directory stream and must not be closed directly. It will be closed automatically by tard_closedir().

Definition at line 166 of file dir.c.

References tarfs_fp::fp_idx, tarfs_fs::fs_fd, tarfs_fs::fs_ino, is_sanefd(), log, tar_strdup1(), tarfs_calloc(), tarfs_getfs_addref(), tarfs_os_free(), and tarfs_unref().

Referenced by fdopendir(), and tard_opendir().

tard_opendir()

DIR * tard_opendir	(	void *	ctx,
		const char *	name )

Open a directory for reading.

Opens an existing directory and returns a directory stream that can be used with tard_readdir(), tard_telldir(), tard_seekdir() and tard_closedir().

Parameters

ctx	TARFS filesystem context.
name	Path to the directory.

Returns

Pointer to a directory stream on success, or NULL on failure.

Opens an existing directory and returns a directory stream that can be used with tard_readdir(), tard_telldir(), tard_seekdir() and tard_closedir(). Increases FS refcounter

Definition at line 233 of file dir.c.

References log, name, tard_fdopendir(), tarf_close(), and tarf_open().

tard_readdir()

struct dirent * tard_readdir	(	void *	ctx,
		DIR *	pdir )

Read the next directory entry.

Returns the next direct child of the opened directory. The returned pointer remains valid until the next call to tard_readdir() on the same directory stream.

Parameters

ctx	TARFS filesystem context.
pdir	Directory stream.

Returns

Pointer to a dirent structure, or NULL if no more entries are available or an error occurred.

Returns the next direct child of the opened directory. The returned pointer remains valid until the next call to tard_readdir() on the same directory stream.

Definition at line 293 of file dir.c.

References inode_type(), is_direct_child(), log, remove_subpath(), and tar_strlen().

Referenced by tard_seekdir().

tard_seekdir()

void tard_seekdir	(	void *	ctx,
		DIR *	pdir,
		long	offset )

Reposition a directory stream.

Sets the current position within the directory stream to a value previously obtained by tard_telldir().

Parameters

ctx	TARFS filesystem context.
pdir	Directory stream.
offset	Directory position previously returned by tard_telldir().

Sets the current position within the directory stream to a value previously obtained by tard_telldir().

Definition at line 371 of file dir.c.

References log, and tard_readdir().

tard_telldir()

long tard_telldir	(	void *	ctx,
		DIR *	pdir )

Return the current directory position.

Obtains the current position within the directory stream. The returned value may later be passed to tard_seekdir() to restore the same position.

Parameters

ctx	TARFS filesystem context.
pdir	Directory stream.

Returns

Current directory position.

Obtains the current position within the directory stream. The returned value may later be passed to tard_seekdir() to restore the same position.

Definition at line 357 of file dir.c.