fdtable.h File Reference

#include <stdarg.h>
#include <time.h>
#include <sys/types.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/util.h>
#include <zephyr/syscalls/fdtable.h>

Go to the source code of this file.

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

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
#define	ZVFS_POLLIN   BIT(0)
#define	ZVFS_POLLPRI   BIT(1)
#define	ZVFS_POLLOUT   BIT(2)
#define	ZVFS_POLLERR   BIT(3)
#define	ZVFS_POLLHUP   BIT(4)
#define	ZVFS_POLLNVAL   BIT(5)
#define	ZVFS_FD_SETSIZE   (sizeof(((struct zvfs_fd_set *)0)->bitset) * 8)
	Number of file descriptors which can be added zvfs_fd_set.

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.
int	zvfs_poll (struct zvfs_pollfd *fds, int nfds, int poll_timeout)
void	ZVFS_FD_CLR (int fd, struct zvfs_fd_set *fdset)
int	ZVFS_FD_ISSET (int fd, struct zvfs_fd_set *fdset)
void	ZVFS_FD_SET (int fd, struct zvfs_fd_set *fdset)
void	ZVFS_FD_ZERO (struct zvfs_fd_set *fdset)
int	zvfs_select (int nfds, struct zvfs_fd_set *ZRESTRICT readfds, struct zvfs_fd_set *ZRESTRICT writefds, struct zvfs_fd_set *ZRESTRICT errorfds, const struct timespec *ZRESTRICT timeout, const void *ZRESTRICT sigmask)

Macro Definition Documentation

ZVFS_FD_SETSIZE

#define ZVFS_FD_SETSIZE   (sizeof(((struct zvfs_fd_set *)0)->bitset) * 8)

Number of file descriptors which can be added zvfs_fd_set.

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

ZVFS_POLLERR

#define ZVFS_POLLERR   BIT(3)

ZVFS_POLLHUP

#define ZVFS_POLLHUP   BIT(4)

ZVFS_POLLIN

#define ZVFS_POLLIN   BIT(0)

ZVFS_POLLNVAL

#define ZVFS_POLLNVAL   BIT(5)

ZVFS_POLLOUT

#define ZVFS_POLLOUT   BIT(2)

ZVFS_POLLPRI

#define ZVFS_POLLPRI   BIT(1)

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

void ZVFS_FD_CLR	(	int	fd,
		struct zvfs_fd_set *	fdset )

ZVFS_FD_ISSET()

int ZVFS_FD_ISSET	(	int	fd,
		struct zvfs_fd_set *	fdset )

ZVFS_FD_SET()

void ZVFS_FD_SET	(	int	fd,
		struct zvfs_fd_set *	fdset )

ZVFS_FD_ZERO()

void ZVFS_FD_ZERO

(

struct zvfs_fd_set *

fdset

)

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

int zvfs_poll	(	struct zvfs_pollfd *	fds,
		int	nfds,
		int	poll_timeout )

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)

zvfs_select()

int zvfs_select	(	int	nfds,
		struct zvfs_fd_set *ZRESTRICT	readfds,
		struct zvfs_fd_set *ZRESTRICT	writefds,
		struct zvfs_fd_set *ZRESTRICT	errorfds,
		const struct timespec *ZRESTRICT	timeout,
		const void *ZRESTRICT	sigmask )