fdtable.h File Reference

#include <stdarg.h>
#include <sys/types.h>
#include <zephyr/fs/fs.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/util.h>

Go to the source code of this file.

Data Structures
struct	fd_op_vtable
	File descriptor virtual method table. More...

Macros
#define	ZVFS_MODE_IFMT   0170000
#define	ZVFS_MODE_UNSPEC   0000000
#define	ZVFS_MODE_IFIFO   0010000
#define	ZVFS_MODE_IFCHR   0020000
#define	ZVFS_MODE_IMSGQ   0030000
#define	ZVFS_MODE_IFDIR   0040000
#define	ZVFS_MODE_IFSEM   0050000
#define	ZVFS_MODE_IFBLK   0060000
#define	ZVFS_MODE_IFSHM   0070000
#define	ZVFS_MODE_IFREG   0100000
#define	ZVFS_MODE_IFLNK   0120000
#define	ZVFS_MODE_IFSOCK   0140000

Enumerations
enum	{   ZFD_IOCTL_FSYNC = 0x100 , ZFD_IOCTL_LSEEK , ZFD_IOCTL_POLL_PREPARE , ZFD_IOCTL_POLL_UPDATE ,   ZFD_IOCTL_POLL_OFFLOAD , ZFD_IOCTL_SET_LOCK , ZFD_IOCTL_STAT , ZFD_IOCTL_TRUNCATE ,   ZFD_IOCTL_MMAP , ZFD_IOCTL_FIONREAD = 0x541B , ZFD_IOCTL_FIONBIO = 0x5421 }
	Request codes for fd_op_vtable.ioctl(). More...

Functions
int	zvfs_reserve_fd (void)
	Reserve file descriptor.
void	zvfs_finalize_typed_fd (int fd, void *obj, const struct fd_op_vtable *vtable, uint32_t mode)
	Finalize creation of file descriptor, with type.
static void	zvfs_finalize_fd (int fd, void *obj, const struct fd_op_vtable *vtable)
	Finalize creation of file descriptor.
int	zvfs_alloc_fd (void *obj, const struct fd_op_vtable *vtable)
	Allocate file descriptor for underlying I/O object.
void	zvfs_free_fd (int fd)
	Release reserved file descriptor.
void *	zvfs_get_fd_obj (int fd, const struct fd_op_vtable *vtable, int err)
	Get underlying object pointer from file descriptor.
void *	zvfs_get_fd_obj_and_vtable (int fd, const struct fd_op_vtable **vtable, struct k_mutex **lock)
	Get underlying object pointer and vtable pointer from file descriptor.
bool	zvfs_get_obj_lock_and_cond (void *obj, const struct fd_op_vtable *vtable, struct k_mutex **lock, struct k_condvar **cond)
	Get the mutex and condition variable associated with the given object and vtable.
static int	zvfs_fdtable_call_ioctl (const struct fd_op_vtable *vtable, void *obj, unsigned long request,...)
	Call ioctl vmethod on an object using varargs.

Macro Definition Documentation

ZVFS_MODE_IFBLK

#define ZVFS_MODE_IFBLK   0060000

ZVFS_MODE_IFCHR

#define ZVFS_MODE_IFCHR   0020000

ZVFS_MODE_IFDIR

#define ZVFS_MODE_IFDIR   0040000

ZVFS_MODE_IFIFO

#define ZVFS_MODE_IFIFO   0010000

ZVFS_MODE_IFLNK

#define ZVFS_MODE_IFLNK   0120000

ZVFS_MODE_IFMT

#define ZVFS_MODE_IFMT   0170000

ZVFS_MODE_IFREG

#define ZVFS_MODE_IFREG   0100000

ZVFS_MODE_IFSEM

#define ZVFS_MODE_IFSEM   0050000

ZVFS_MODE_IFSHM

#define ZVFS_MODE_IFSHM   0070000

ZVFS_MODE_IFSOCK

#define ZVFS_MODE_IFSOCK   0140000

ZVFS_MODE_IMSGQ

#define ZVFS_MODE_IMSGQ   0030000

ZVFS_MODE_UNSPEC

#define ZVFS_MODE_UNSPEC   0000000

Enumeration Type Documentation

anonymous enum

anonymous enum

Request codes for fd_op_vtable.ioctl().

Note that these codes are internal Zephyr numbers, for internal Zephyr operations (and subject to change without notice, not part of "stable ABI"). These are however expected to co-exist with "well-known" POSIX/Linux ioctl numbers, and not clash with them.

Enumerator
ZFD_IOCTL_FSYNC
ZFD_IOCTL_LSEEK
ZFD_IOCTL_POLL_PREPARE
ZFD_IOCTL_POLL_UPDATE
ZFD_IOCTL_POLL_OFFLOAD
ZFD_IOCTL_SET_LOCK
ZFD_IOCTL_STAT
ZFD_IOCTL_TRUNCATE
ZFD_IOCTL_MMAP
ZFD_IOCTL_FIONREAD
ZFD_IOCTL_FIONBIO

Function Documentation

zvfs_alloc_fd()

int zvfs_alloc_fd	(	void *	obj,
		const struct fd_op_vtable *	vtable )

Allocate file descriptor for underlying I/O object.

This function combines operations of zvfs_reserve_fd() and zvfs_finalize_fd() in one step, and provided for convenience.

Parameters

obj	pointer to I/O object structure
vtable	pointer to I/O operation implementations for the object

Returns

Allocated file descriptor, or -1 in case of error (errno is set)

zvfs_fdtable_call_ioctl()

static int zvfs_fdtable_call_ioctl ( const struct fd_op_vtable * vtable, void * obj, unsigned long request, ... )

inlinestatic

Call ioctl vmethod on an object using varargs.

We need this helper function because ioctl vmethod is declared to take va_list and the only portable way to construct va_list is from function's ... parameters.

Parameters

vtable	vtable containing ioctl function pointer
obj	Object to call ioctl on
request	ioctl request number
...	Variadic arguments to ioctl

zvfs_finalize_fd()

static void zvfs_finalize_fd ( int fd, void * obj, const struct fd_op_vtable * vtable )

inlinestatic

Finalize creation of file descriptor.

This function should be called exactly once after zvfs_reserve_fd(), and should not be called in any other case.

Parameters

fd	File descriptor previously returned by zvfs_reserve_fd()
obj	pointer to I/O object structure
vtable	pointer to I/O operation implementations for the object

zvfs_finalize_typed_fd()

void zvfs_finalize_typed_fd	(	int	fd,
		void *	obj,
		const struct fd_op_vtable *	vtable,
		uint32_t	mode )

Finalize creation of file descriptor, with type.

This function should be called exactly once after zvfs_reserve_fd(), and should not be called in any other case.

The difference between this function and zvfs_finalize_fd is that the latter does not relay type information of the created file descriptor.

Values permitted for mode are one of ZVFS_MODE_...

Parameters

fd	File descriptor previously returned by zvfs_reserve_fd()
obj	pointer to I/O object structure
vtable	pointer to I/O operation implementations for the object
mode	File type as specified above.

zvfs_free_fd()

void zvfs_free_fd

(

int

fd

)

Release reserved file descriptor.

This function may be called once after zvfs_reserve_fd(), and should not be called in any other case.

Parameters

fd	File descriptor previously returned by zvfs_reserve_fd()

zvfs_get_fd_obj()

void * zvfs_get_fd_obj	(	int	fd,
		const struct fd_op_vtable *	vtable,
		int	err )

Get underlying object pointer from file descriptor.

This function is useful for functions other than read/write/ioctl to look up underlying I/O object by fd, optionally checking its type (using vtable reference). If fd refers to invalid entry, NULL will be returned with errno set to EBADF. If fd is valid, but vtable param is not NULL and doesn't match object's vtable, NULL is returned and errno set to err param.

Parameters

fd	File descriptor previously returned by zvfs_reserve_fd()
vtable	Expected object vtable or NULL
err	errno value to set if object vtable doesn't match

Returns

Object pointer or NULL, with errno set

zvfs_get_fd_obj_and_vtable()

void * zvfs_get_fd_obj_and_vtable	(	int	fd,
		const struct fd_op_vtable **	vtable,
		struct k_mutex **	lock )

Get underlying object pointer and vtable pointer from file descriptor.

Parameters

fd	File descriptor previously returned by zvfs_reserve_fd()
vtable	A pointer to a pointer variable to store the vtable
lock	An optional pointer to a pointer variable to store the mutex preventing concurrent descriptor access. The lock is not taken, it is just returned for the caller to use if necessary. Pass NULL if the lock is not needed by the caller.

Returns

Object pointer or NULL, with errno set

zvfs_get_obj_lock_and_cond()

bool zvfs_get_obj_lock_and_cond	(	void *	obj,
		const struct fd_op_vtable *	vtable,
		struct k_mutex **	lock,
		struct k_condvar **	cond )

Get the mutex and condition variable associated with the given object and vtable.

Parameters

obj	Object previously returned by a call to e.g. zvfs_get_fd_obj.
vtable	A pointer the vtable associated with obj.
lock	An optional pointer to a pointer variable to store the mutex preventing concurrent descriptor access. The lock is not taken, it is just returned for the caller to use if necessary. Pass NULL if the lock is not needed by the caller.
cond	An optional pointer to a pointer variable to store the condition variable to notify waiting threads in the case of concurrent descriptor access. Pass NULL if the condition variable is not needed by the caller.

Returns

true on success, false otherwise.

zvfs_reserve_fd()

int zvfs_reserve_fd

(

void

)

Reserve file descriptor.

This function allows to reserve a space for file descriptor entry in the underlying table, and thus allows caller to fail fast if no free descriptor is available. If this function succeeds, zvfs_finalize_fd() or zvfs_free_fd() must be called mandatorily.

Returns

Allocated file descriptor, or -1 in case of error (errno is set)