IO Internal Library

Internal IO library API and implementation. More...

Files
file	__usrenv.c
	RTEMS File System Location Support.
file	clonenode.c
	Clones a Node.
file	freenode.c
	Releases all Resources of a Location.
file	libio.c
	File Descriptor Routines.
file	libiozeroiops.c
	This source file provides rtems_libio_iops and rtems_libio_number_iops for a zero file descriptor application configuration.
file	sup_fs_check_permissions.c
	RTEMS File System Permissions Check Support.
file	sup_fs_eval_path.c
	RTEMS File Sysyem Path Eval Support.
file	sup_fs_eval_path_generic.c
	RTEMS File System Eval Generic Path.
file	sup_fs_exist_in_same_instance.c
	Checks that the Locations Exist in the Same File System Instance.
file	sup_fs_location.c
	RTEMS File System Location Support.
file	sup_fs_next_token.c
	RTEMS File System Eval Eat Delimiter Path.

Data Structures
struct	rtems_filesystem_eval_path_generic_config

Macros
#define	RTEMS_FILESYSTEM_SYMLOOP_MAX   32
#define	F_DUP2FD   20
#define	rtems_libio_iop_to_descriptor(_iop)    ((_iop) - &rtems_libio_iops[0])
#define	rtems_libio_check_is_open(_iop)
#define	LIBIO_GET_IOP(_fd, _iop)
	Macro to get the iop for the specified file descriptor.
#define	LIBIO_GET_IOP_WITH_ACCESS(_fd, _iop, _access_flags, _access_error)
	Macro to get the iop for the specified file descriptor with access flags and error.
#define	rtems_libio_check_buffer(_buffer)
#define	rtems_libio_check_count(_count)
#define	rtems_filesystem_mt_entry_declare_lock_context(ctx)    rtems_interrupt_lock_context ctx
#define	rtems_filesystem_mt_entry_lock(ctx)    rtems_interrupt_lock_acquire( &rtems_filesystem_mt_entry_lock_control, &ctx )
#define	rtems_filesystem_mt_entry_unlock(ctx)    rtems_interrupt_lock_release( &rtems_filesystem_mt_entry_lock_control, &ctx )

Typedefs
typedef bool(*	rtems_filesystem_eval_path_is_directory) (rtems_filesystem_eval_path_context_t *ctx, void *arg)
	Tests if the current location is a directory.
typedef rtems_filesystem_eval_path_generic_status(*	rtems_filesystem_eval_path_eval_token) (rtems_filesystem_eval_path_context_t *ctx, void *arg, const char *token, size_t tokenlen)
	Evaluates a token.
typedef ssize_t(*	rtems_libio_iovec_adapter) (rtems_libio_t *iop, const struct iovec *iov, int iovcnt, ssize_t total)

Enumerations
enum	rtems_filesystem_eval_path_generic_status { RTEMS_FILESYSTEM_EVAL_PATH_GENERIC_CONTINUE , RTEMS_FILESYSTEM_EVAL_PATH_GENERIC_DONE , RTEMS_FILESYSTEM_EVAL_PATH_GENERIC_NO_ENTRY }

Functions
void	rtems_filesystem_location_clone (rtems_filesystem_location_info_t *clone, const rtems_filesystem_location_info_t *master)
	Clones a node.
void	rtems_filesystem_location_free (rtems_filesystem_location_info_t *loc)
	Releases all resources of a location.
void	rtems_libio_lock (void)
void	rtems_libio_unlock (void)
bool	rtems_filesystem_utime_tv_nsec_valid (struct timespec time)
	Checks the tv_nsec member of a timespec struct.
int	rtems_filesystem_utime_check_permissions (const rtems_filesystem_location_info_t *currentloc, const struct timespec times[2])
	Checks for errors and if the process has write permissions to the file.
int	rtems_filesystem_utime_update (const struct timespec times[2], struct timespec new_times[2])
	Checks times and fills new_times with the time to be written.
rtems_libio_t *	rtems_libio_allocate (void)
unsigned int	rtems_libio_fcntl_flags (int fcntl_flags)
int	rtems_libio_to_fcntl_flags (unsigned int flags)
void	rtems_libio_free (rtems_libio_t *iop)
rtems_filesystem_location_info_t *	rtems_filesystem_eval_path_start (rtems_filesystem_eval_path_context_t *ctx, const char *path, int eval_flags)
rtems_filesystem_location_info_t *	rtems_filesystem_eval_path_start_with_parent (rtems_filesystem_eval_path_context_t *ctx, const char *path, int eval_flags, rtems_filesystem_location_info_t *parentloc, int parent_eval_flags)
rtems_filesystem_location_info_t *	rtems_filesystem_eval_path_start_with_root_and_current (rtems_filesystem_eval_path_context_t *ctx, const char *path, size_t pathlen, int eval_flags, rtems_filesystem_global_location_t *const *global_root_ptr, rtems_filesystem_global_location_t *const *global_current_ptr)
void	rtems_filesystem_eval_path_continue (rtems_filesystem_eval_path_context_t *ctx)
void	rtems_filesystem_eval_path_cleanup (rtems_filesystem_eval_path_context_t *ctx)
void	rtems_filesystem_eval_path_recursive (rtems_filesystem_eval_path_context_t *ctx, const char *path, size_t pathlen)
void	rtems_filesystem_eval_path_cleanup_with_parent (rtems_filesystem_eval_path_context_t *ctx, rtems_filesystem_location_info_t *parentloc)
void	rtems_filesystem_eval_path_restart (rtems_filesystem_eval_path_context_t *ctx, rtems_filesystem_global_location_t **newstartloc_ptr)
	Requests a path evaluation restart.
void	rtems_filesystem_eval_path_generic (rtems_filesystem_eval_path_context_t *ctx, void *arg, const rtems_filesystem_eval_path_generic_config *config)
void	rtems_filesystem_initialize (void)
	Base File System Initialization.
rtems_filesystem_location_info_t *	rtems_filesystem_location_copy (rtems_filesystem_location_info_t *dst, const rtems_filesystem_location_info_t *src)
	Copies a location.
rtems_filesystem_global_location_t *	rtems_filesystem_location_transform_to_global (rtems_filesystem_location_info_t *loc)
void	rtems_filesystem_global_location_assign (rtems_filesystem_global_location_t **lhs_global_loc_ptr, rtems_filesystem_global_location_t *rhs_global_loc)
	Assigns a global file system location.
rtems_filesystem_global_location_t *	rtems_filesystem_global_location_obtain (rtems_filesystem_global_location_t *const *global_loc_ptr)
	Obtains a global file system location.
void	rtems_filesystem_global_location_release (rtems_filesystem_global_location_t *global_loc, bool deferred)
	Releases a global file system location.
void	rtems_filesystem_location_detach (rtems_filesystem_location_info_t *detach)
void	rtems_filesystem_location_copy_and_detach (rtems_filesystem_location_info_t *copy, rtems_filesystem_location_info_t *detach)
int	rtems_filesystem_mknod (const rtems_filesystem_location_info_t *parentloc, const char *name, size_t namelen, mode_t mode, dev_t dev)
int	rtems_filesystem_chdir (rtems_filesystem_location_info_t *loc)
int	rtems_filesystem_chmod (const rtems_filesystem_location_info_t *loc, mode_t mode)
int	rtems_filesystem_chown (const rtems_filesystem_location_info_t *loc, uid_t owner, gid_t group)
void	rtems_filesystem_location_remove_from_mt_entry (rtems_filesystem_location_info_t *loc)
void	rtems_filesystem_do_unmount (rtems_filesystem_mount_table_entry_t *mt_entry)
void	rtems_filesystem_eval_path_eat_delimiter (rtems_filesystem_eval_path_context_t *ctx)
void	rtems_filesystem_eval_path_next_token (rtems_filesystem_eval_path_context_t *ctx)
void	rtems_filesystem_eval_path_error (rtems_filesystem_eval_path_context_t *ctx, int eno)
int	rtems_filesystem_location_exists_in_same_instance_as (const rtems_filesystem_location_info_t *a, const rtems_filesystem_location_info_t *b)
	Checks that the locations exist in the same file system instance.
bool	rtems_filesystem_check_access (int flags, mode_t object_mode, uid_t object_uid, gid_t object_gid)
	Checks if access to an object is allowed for the current user.
bool	rtems_filesystem_eval_path_check_access (rtems_filesystem_eval_path_context_t *ctx, int eval_flags, mode_t node_mode, uid_t node_uid, gid_t node_gid)

Variables
const uint32_t	rtems_libio_number_iops
rtems_libio_t	rtems_libio_iops []
void *	rtems_libio_iop_free_head
void **	rtems_libio_iop_free_tail
const rtems_filesystem_file_handlers_r	rtems_filesystem_null_handlers
rtems_filesystem_mount_table_entry_t	rtems_filesystem_null_mt_entry
rtems_filesystem_global_location_t	rtems_filesystem_global_location_null
	The global null location.
rtems_interrupt_lock	rtems_filesystem_mt_entry_lock_control

Detailed Description

Internal IO library API and implementation.

Macro Definition Documentation

LIBIO_GET_IOP

#define LIBIO_GET_IOP	(		_fd,
			_iop
	)

Value:

  do { \
    unsigned int _flags; \
    if ( (uint32_t) ( _fd ) >= rtems_libio_number_iops ) { \
      rtems_set_errno_and_return_minus_one( EBADF ); \
    } \
    _iop = rtems_libio_iop( _fd ); \
    _flags = rtems_libio_iop_hold( _iop ); \
    if ( ( _flags & LIBIO_FLAGS_OPEN ) == 0 ) { \
      rtems_libio_iop_drop( _iop ); \
      rtems_set_errno_and_return_minus_one( EBADF ); \
    } \
  } while ( 0 )

Macro to get the iop for the specified file descriptor.

Checks that the file descriptor is in the valid range and open.

LIBIO_GET_IOP_WITH_ACCESS

#define LIBIO_GET_IOP_WITH_ACCESS	(		_fd,
			_iop,
			_access_flags,
			_access_error
	)

Value:

  do { \
    unsigned int _flags; \
    unsigned int _mandatory; \
    if ( (uint32_t) ( _fd ) >= rtems_libio_number_iops ) { \
      rtems_set_errno_and_return_minus_one( EBADF ); \
    } \
    _iop = rtems_libio_iop( _fd ); \
    _flags = rtems_libio_iop_hold( _iop ); \
    _mandatory = LIBIO_FLAGS_OPEN | ( _access_flags ); \
    if ( ( _flags & _mandatory ) != _mandatory ) { \
      int _error; \
      rtems_libio_iop_drop( _iop ); \
      if ( ( _flags & LIBIO_FLAGS_OPEN ) == 0 ) { \
        _error = EBADF; \
      } else { \
        _error = _access_error; \
      } \
      rtems_set_errno_and_return_minus_one( _error ); \
    } \
  } while ( 0 )

Macro to get the iop for the specified file descriptor with access flags and error.

Checks that the file descriptor is in the valid range and open.

rtems_libio_check_buffer

#define rtems_libio_check_buffer

(

_buffer

)

Value:

  do {                                    \
      if ((_buffer) == 0) {               \
          errno = EINVAL;                 \
          return -1;                      \
      }                                   \
  } while (0)

rtems_libio_check_count

#define rtems_libio_check_count

(

_count

)

Value:

  do {                                  \
      if ((_count) == 0) {              \
          return 0;                     \
      }                                 \
  } while (0)

rtems_libio_check_is_open

#define rtems_libio_check_is_open

(

_iop

)

Value:

  do {                                               \
      if ((rtems_libio_iop_flags(_iop) & LIBIO_FLAGS_OPEN) == 0) { \
          errno = EBADF;                             \
          return -1;                                 \
      }                                              \
  } while (0)

Typedef Documentation

rtems_filesystem_eval_path_eval_token

typedef rtems_filesystem_eval_path_generic_status(* rtems_filesystem_eval_path_eval_token) (rtems_filesystem_eval_path_context_t *ctx, void *arg, const char *token, size_t tokenlen)

Evaluates a token.

Parameters

[in,out]	ctx	The path evaluation context.
[in,out]	arg	The handler argument.
[in]	token	The token contents.
[in]	tokenlen	The token length in characters.

Return values

status

The generic path evaluation status.

See also

rtems_filesystem_eval_path_generic().

rtems_filesystem_eval_path_is_directory

typedef bool(* rtems_filesystem_eval_path_is_directory) (rtems_filesystem_eval_path_context_t *ctx, void *arg)

Tests if the current location is a directory.

Parameters

[in,out]	ctx	The path evaluation context.
[in,out]	arg	The handler argument.

Return values

true	The current location is a directory.
false	Otherwise.

See also

rtems_filesystem_eval_path_generic().

Function Documentation

rtems_filesystem_check_access()

bool rtems_filesystem_check_access	(	int	flags,
		mode_t	object_mode,
		uid_t	object_uid,
		gid_t	object_gid
	)

Checks if access to an object is allowed for the current user.

If the effective UID is zero or equals the UID of the object, then the user permission flags of the object will be used. Otherwise if the effective GID is zero or equals the GID of the object or one of the supplementary group IDs is equal to the GID of the object, then the group permission flags of the object will be used. Otherwise the other permission flags of the object will be used.

Parameters

[in]	flags	The flags determining the access type. It can be RTEMS_FS_PERMS_READ, RTEMS_FS_PERMS_WRITE or RTEMS_FS_PERMS_EXEC.
[in]	object_mode	The mode of the object specifying the permission flags.
[in]	object_uid	The UID of the object.
[in]	object_gid	The GID of the object.

Return values

true	Access is allowed.
false	Otherwise.

rtems_filesystem_eval_path_restart()

void rtems_filesystem_eval_path_restart	(	rtems_filesystem_eval_path_context_t *	ctx,
		rtems_filesystem_global_location_t **	newstartloc_ptr
	)

Requests a path evaluation restart.

Sets the start and current location to the new start location. The caller must terminate its current evaluation process. The path evaluation continues in the next loop iteration within rtems_filesystem_eval_path_continue(). This avoids recursive invocations. The function obtains the new start location and clones it to set the new current location. The previous start and current locations are released.

Parameters

[in,out]	ctx	The path evaluation context.
[in,out]	newstartloc_ptr	Pointer to the new start location.

rtems_filesystem_global_location_assign()

void rtems_filesystem_global_location_assign	(	rtems_filesystem_global_location_t **	lhs_global_loc_ptr,
		rtems_filesystem_global_location_t *	rhs_global_loc
	)

Assigns a global file system location.

Parameters

[in,out]	lhs_global_loc_ptr	Pointer to the global left hand side file system location. The current left hand side location will be released.
[in]	rhs_global_loc	The global right hand side file system location.

rtems_filesystem_global_location_obtain()

rtems_filesystem_global_location_t * rtems_filesystem_global_location_obtain

(

rtems_filesystem_global_location_t *const *

global_loc_ptr

)

Obtains a global file system location.

Deferred releases will be processed in this function.

This function must be called from normal thread context and may block on a mutex. Thread dispatching is disabled to protect some critical sections.

Parameters

[in]

global_loc_ptr

Pointer to the global file system location.

Returns

A global file system location. It returns always a valid object. In case of an error, the global null location will be returned. Each operation or handler of the null location returns an error status. The errno indicates the error. The NULL pointer is never returned.

See also

rtems_filesystem_location_transform_to_global(), rtems_filesystem_global_location_obtain_null(), and rtems_filesystem_global_location_release().

rtems_filesystem_global_location_release()

void rtems_filesystem_global_location_release	(	rtems_filesystem_global_location_t *	global_loc,
		bool	deferred
	)

Releases a global file system location.

In case the reference count reaches zero, all associated resources will be released. This may include the complete unmount of the corresponding file system instance.

This function may block on a mutex. It may be called within critical sections of the operating system. In this case the release will be deferred. The next obtain call will do the actual release.

Parameters

[in]	global_loc	The global file system location. It must not be NULL.
[in]	deferred	If true, then do a deferred release, otherwise release it immediately.

See also

rtems_filesystem_global_location_obtain().

rtems_filesystem_initialize()

void rtems_filesystem_initialize

(

void

)

Base File System Initialization.

Initialize the foundation of the file system. This is specified by the structure rtems_filesystem_mount_table. The usual configuration is a single instantiation of the IMFS or miniIMFS with a single "/dev" directory in it.

rtems_filesystem_location_clone()

void rtems_filesystem_location_clone	(	rtems_filesystem_location_info_t *	clone,
		const rtems_filesystem_location_info_t *	master
	)

Clones a node.

The caller must hold the file system instance lock.

Parameters

[out]	clone	The cloned location.
[in]	master	The master location.

See also

rtems_filesystem_instance_lock().

rtems_filesystem_location_copy()

rtems_filesystem_location_info_t * rtems_filesystem_location_copy	(	rtems_filesystem_location_info_t *	dst,
		const rtems_filesystem_location_info_t *	src
	)

Copies a location.

A bitwise copy is performed. The destination location will be added to the corresponding mount entry.

Parameters

[out]	dst	The destination location.
[in]	src	The source location.

Return values

dst	The destination location.

See also

rtems_filesystem_location_clone().

rtems_filesystem_location_exists_in_same_instance_as()

int rtems_filesystem_location_exists_in_same_instance_as	(	const rtems_filesystem_location_info_t *	a,
		const rtems_filesystem_location_info_t *	b
	)

Checks that the locations exist in the same file system instance.

Return values

0	The locations exist and are in the same file system instance.
-1	An error occurred. The errno indicates the error.

rtems_filesystem_location_free()

void rtems_filesystem_location_free

(

rtems_filesystem_location_info_t *

loc

)

Releases all resources of a location.

This function may block on a mutex and may complete an unmount process.

Parameters

[in]

loc

The location to free.

Note

The file system root location is released by the file system instance destruction handler (see rtems_filesystem_fsunmount_me_t).

See also

rtems_filesystem_freenode_t.

rtems_filesystem_utime_check_permissions()

int rtems_filesystem_utime_check_permissions	(	const rtems_filesystem_location_info_t *	currentloc,
		const struct timespec	times[2]
	)

Checks for errors and if the process has write permissions to the file.

This function is only used with utimensat() and futimens().It checks for EACCES and EPERM errors depending on what values are in times and if the process has write permissions to the file.

Parameters

[in]	currentloc	The current location to a file
[in]	times	The timespecs used to check for errors. The timespec at index 0 is the access time, and the timespec at index 1 is the modification time.

Return values

0	An error was not found.
-1	An error was found.

rtems_filesystem_utime_tv_nsec_valid()

bool rtems_filesystem_utime_tv_nsec_valid

(

struct timespec

time

)

Checks the tv_nsec member of a timespec struct.

This function is used with utimensat() and futimens() only. This ensures that the value in the tv_nsec member is equal to either UTIME_NOW, UTIME_OMIT, or a value greater-than or equal to zero and less than a billion.

Parameters

[in]

time

The timespec struct to be validated

Return values

true	The tv_nsec member is a valid value.
false	The tv_nsec member is not a valid value.

rtems_filesystem_utime_update()

int rtems_filesystem_utime_update	(	const struct timespec	times[2],
		struct timespec	new_times[2]
	)

Checks times and fills new_times with the time to be written.

This function is only used with utimensat() and futimens(). times contains the constant values passed into utimensat/futimens. new_times contains the values that will be written to the file. These values depend on times. If times is NULL, or either of its elements' tv_nsec members are UTIME_NOW, the current elapsed time in nanoseconds will be saved in the corresponding location in new_times.

For each of the arguments, the timespec at index 0 is the access time, and the timespec at index 1 is the modification time.

Parameters

[in]	times	The timespecs to be checked
[out]	new_times	The timespecs containing the time to be written

Return values

0	times is valid.
-1	times is not valid.

rtems_libio_allocate()

rtems_libio_t * rtems_libio_allocate

(

void

)

This routine searches the IOP Table for an unused entry. If it finds one, it returns it. Otherwise, it returns NULL.

rtems_libio_fcntl_flags()

unsigned int rtems_libio_fcntl_flags

(

int

fcntl_flags

)

Convert UNIX fnctl(2) flags to ones that RTEMS drivers understand

rtems_libio_free()

void rtems_libio_free

(

rtems_libio_t *

iop

)

This routine frees the resources associated with an IOP (file descriptor) and clears the slot in the IOP Table.

rtems_libio_to_fcntl_flags()

int rtems_libio_to_fcntl_flags

(

unsigned int

flags

)

Convert RTEMS internal flags to UNIX fnctl(2) flags

Variable Documentation

rtems_filesystem_global_location_null

rtems_filesystem_global_location_t rtems_filesystem_global_location_null

extern

The global null location.

Every operation and the open and fstat handlers of this location returns an error status. The errno is not touched by these operations and handlers. The purpose of this location is to deliver the error return status for a previous error condition which must set the errno accordingly.

The usage of this null location instead of the NULL pointer eliminates a lot of branches.

The user environment root and current directory are statically initialized with the null location. Due to that all file system services are in a defined state even if no root file system was mounted.