dir.c File Reference

#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <stdbool.h>
#include <stdatomic.h>
#include <string.h>
#include <unistd.h>
#include <dirent.h>
#include <sys/errno.h>
#include <sys/fcntl.h>
#include <sys/dirent.h>
#include "config.h"
#include "os.h"
#include "fs.h"
#include "inode.h"
#include "tar.h"
#include "dir.h"

Go to the source code of this file.

Functions
static const char *	remove_subpath (const char *path, const char *subpath)
static bool	is_sanefd (struct tarfs_fs *fs, int fd)
static int	is_direct_child (const char *path, const char *prefix)
	Check if 'path' is direct child of 'prefix'; Prefix MUST NOT have '/' at the end.
DIR *	tard_fdopendir (void *ctx, int fd)
	Associate an open directory file descriptor with a directory stream.
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 tard_dirfd() returns the file descriptor associated with the directory stream pdir.

Function Documentation

is_direct_child()

int is_direct_child ( const char * path, const char * prefix )

static

Check if 'path' is direct child of 'prefix'; Prefix MUST NOT have '/' at the end.

Definition at line 119 of file dir.c.

References prefix, and tar_strncmp().

Referenced by tard_readdir().

is_sanefd()

bool is_sanefd ( struct tarfs_fs * fs, int fd )

static

< Max number of active opened files (per filesystem, must be < 33)

Definition at line 106 of file dir.c.

References TARFS_MAX_FDS.

Referenced by tard_fdopendir().

remove_subpath()

const char * remove_subpath ( const char * path, const char * subpath )

static

Definition at line 84 of file dir.c.

Referenced by tard_readdir().

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().

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.

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 tard_dirfd() returns the file descriptor associated with the directory stream pdir.

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

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

Definition at line 397 of file dir.c.

tard_fdopendir()

DIR * tard_fdopendir	(	void *	ctx,
		int	fd )

Associate an open directory file descriptor with a directory stream.

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().

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.

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(). Increases FS refcounter

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.

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.

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.

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().

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().

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.

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.

Definition at line 357 of file dir.c.