Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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
objpointer to I/O object structure
vtablepointer 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
vtablevtable containing ioctl function pointer
objObject to call ioctl on
requestioctl 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
fdFile descriptor previously returned by zvfs_reserve_fd()
objpointer to I/O object structure
vtablepointer 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
fdFile descriptor previously returned by zvfs_reserve_fd()
objpointer to I/O object structure
vtablepointer to I/O operation implementations for the object
modeFile 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
fdFile 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
fdFile descriptor previously returned by zvfs_reserve_fd()
vtableExpected object vtable or NULL
errerrno 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
fdFile descriptor previously returned by zvfs_reserve_fd()
vtableA pointer to a pointer variable to store the vtable
lockAn 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
objObject previously returned by a call to e.g. zvfs_get_fd_obj.
vtableA pointer the vtable associated with obj.
lockAn 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.
condAn 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)