libio_.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-2-Clause */
 
/*
 * COPYRIGHT (C) 1989, 2021 On-Line Applications Research Corporation (OAR).
 *
 * Modifications to support reference counting in the file system are
 * Copyright (c) 2012 embedded brains GmbH & Co. KG
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
 
#ifndef _RTEMS_RTEMS_LIBIO__H
#define _RTEMS_RTEMS_LIBIO__H
 
#include <sys/uio.h>
#include <errno.h>
#include <limits.h>
#include <pthread.h>
 
#include <rtems.h>
#include <rtems/libio.h>
#include <rtems/seterr.h>
#include <rtems/score/assert.h>
#include <rtems/score/timespec.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define RTEMS_FILESYSTEM_SYMLOOP_MAX 32
 
/*
 * Not defined in newlib so provide here. Users should use dup2 and
 * not this non-portable fcntl command. Provided here to allow the
 * RTEMS implementation to work.
 */
#define F_DUP2FD 20
 
/*
 *  File descriptor Table Information
 */
 
extern const uint32_t rtems_libio_number_iops;
extern rtems_libio_t rtems_libio_iops[];
extern void *rtems_libio_iop_free_head;
extern void **rtems_libio_iop_free_tail;
 
extern const rtems_filesystem_file_handlers_r rtems_filesystem_null_handlers;
 
extern rtems_filesystem_mount_table_entry_t rtems_filesystem_null_mt_entry;
 
extern rtems_filesystem_global_location_t rtems_filesystem_global_location_null;
 
static inline unsigned int rtems_libio_iop_flags_set(
  rtems_libio_t *iop,
  unsigned int   set
)
{
  return _Atomic_Fetch_or_uint( &iop->flags, set, ATOMIC_ORDER_RELAXED );
}
 
static inline unsigned int rtems_libio_iop_flags_clear(
  rtems_libio_t *iop,
  unsigned int   clear
)
{
  return _Atomic_Fetch_and_uint( &iop->flags, ~clear, ATOMIC_ORDER_RELAXED );
}
 
static inline rtems_libio_t *rtems_libio_iop( int fd )
{
  return &rtems_libio_iops[ fd ];
}
 
static inline unsigned int rtems_libio_iop_hold( rtems_libio_t *iop )
{
  return _Atomic_Fetch_add_uint(
    &iop->flags,
    LIBIO_FLAGS_REFERENCE_INC,
    ATOMIC_ORDER_ACQUIRE
  );
}
 
static inline void rtems_libio_iop_drop( rtems_libio_t *iop )
{
#if defined(RTEMS_DEBUG)
  unsigned int flags;
  bool         success;
 
  flags = _Atomic_Load_uint( &iop->flags, ATOMIC_ORDER_RELAXED );
 
  do {
    unsigned int desired;
 
    _Assert( flags >= LIBIO_FLAGS_REFERENCE_INC );
 
    desired = flags - LIBIO_FLAGS_REFERENCE_INC;
    success = _Atomic_Compare_exchange_uint(
      &iop->flags,
      &flags,
      desired,
      ATOMIC_ORDER_RELEASE,
      ATOMIC_ORDER_RELAXED
    );
  } while ( !success );
#else
  _Atomic_Fetch_sub_uint(
    &iop->flags,
    LIBIO_FLAGS_REFERENCE_INC,
    ATOMIC_ORDER_RELEASE
  );
#endif
}
 
/*
 *  rtems_libio_iop_to_descriptor
 *
 *  Macro to convert an internal file descriptor pointer (iop) into
 *  the integer file descriptor used by the "section 2" system calls.
 */
 
#define rtems_libio_iop_to_descriptor(_iop) \
  ((_iop) - &rtems_libio_iops[0])
 
/*
 *  rtems_libio_check_is_open
 *
 *  Macro to check if a file descriptor is actually open.
 */
 
#define rtems_libio_check_is_open(_iop) \
  do {                                               \
      if ((rtems_libio_iop_flags(_iop) & LIBIO_FLAGS_OPEN) == 0) { \
          errno = EBADF;                             \
          return -1;                                 \
      }                                              \
  } while (0)
 
#define LIBIO_GET_IOP( _fd, _iop ) \
  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 )
 
#define LIBIO_GET_IOP_WITH_ACCESS( _fd, _iop, _access_flags, _access_error ) \
  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 )
 
/*
 *  rtems_libio_check_buffer
 *
 *  Macro to check if a buffer pointer is valid.
 */
 
#define rtems_libio_check_buffer(_buffer) \
  do {                                    \
      if ((_buffer) == 0) {               \
          errno = EINVAL;                 \
          return -1;                      \
      }                                   \
  } while (0)
 
/*
 *  rtems_libio_check_count
 *
 *  Macro to check if a count or length is valid.
 */
 
#define rtems_libio_check_count(_count) \
  do {                                  \
      if ((_count) == 0) {              \
          return 0;                     \
      }                                 \
  } while (0)
 
void rtems_filesystem_location_clone(
  rtems_filesystem_location_info_t *clone,
  const rtems_filesystem_location_info_t *master
);
 
void rtems_filesystem_location_free( rtems_filesystem_location_info_t *loc );
 
/*
 *  External structures
 */
#include <rtems/userenv.h>
 
void rtems_libio_lock( void );
 
void rtems_libio_unlock( void );
 
static inline void rtems_filesystem_mt_lock( void )
{
  rtems_libio_lock();
}
 
static inline void rtems_filesystem_mt_unlock( void )
{
  rtems_libio_unlock();
}
 
extern rtems_interrupt_lock rtems_filesystem_mt_entry_lock_control;
 
#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 )
 
static inline void rtems_filesystem_instance_lock(
  const rtems_filesystem_location_info_t *loc
)
{
  const rtems_filesystem_mount_table_entry_t *mt_entry = loc->mt_entry;
 
  (*mt_entry->ops->lock_h)( mt_entry );
}
 
static inline void rtems_filesystem_instance_unlock(
  const rtems_filesystem_location_info_t *loc
)
{
  const rtems_filesystem_mount_table_entry_t *mt_entry = loc->mt_entry;
 
  (*mt_entry->ops->unlock_h)( mt_entry );
}
 
bool rtems_filesystem_utime_tv_nsec_valid( struct timespec time );
 
int rtems_filesystem_utime_check_permissions(
  const rtems_filesystem_location_info_t *currentloc,
  const struct timespec times[2]
);
 
int rtems_filesystem_utime_update(
  const struct timespec times[2],
  struct timespec new_times[2]
);
 
/*
 *  File Descriptor Routine Prototypes
 */
 
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
);
 
/*
 *  File System Routine Prototypes
 */
 
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
);
 
typedef enum {
  RTEMS_FILESYSTEM_EVAL_PATH_GENERIC_CONTINUE,
  RTEMS_FILESYSTEM_EVAL_PATH_GENERIC_DONE,
  RTEMS_FILESYSTEM_EVAL_PATH_GENERIC_NO_ENTRY
} rtems_filesystem_eval_path_generic_status;
 
typedef bool (*rtems_filesystem_eval_path_is_directory)(
  rtems_filesystem_eval_path_context_t *ctx,
  void *arg
);
 
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
);
 
typedef struct {
  rtems_filesystem_eval_path_is_directory is_directory;
  rtems_filesystem_eval_path_eval_token eval_token;
} rtems_filesystem_eval_path_generic_config;
 
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);
 
rtems_filesystem_location_info_t *rtems_filesystem_location_copy(
  rtems_filesystem_location_info_t *dst,
  const rtems_filesystem_location_info_t *src
);
 
static inline rtems_filesystem_location_info_t *
rtems_filesystem_location_initialize_to_null(
  rtems_filesystem_location_info_t *loc
)
{
  return rtems_filesystem_location_copy(
    loc,
    &rtems_filesystem_global_location_null.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
);
 
rtems_filesystem_global_location_t *rtems_filesystem_global_location_obtain(
  rtems_filesystem_global_location_t *const *global_loc_ptr
);
 
void rtems_filesystem_global_location_release(
  rtems_filesystem_global_location_t *global_loc,
  bool deferred
);
 
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
);
 
static inline rtems_filesystem_global_location_t *
rtems_filesystem_global_location_obtain_null(void)
{
  rtems_filesystem_global_location_t *global_loc = NULL;
 
  return rtems_filesystem_global_location_obtain( &global_loc );
}
 
static inline bool rtems_filesystem_location_is_null(
  const rtems_filesystem_location_info_t *loc
)
{
  return loc->handlers == &rtems_filesystem_null_handlers;
}
 
static inline bool rtems_filesystem_global_location_is_null(
  const rtems_filesystem_global_location_t *global_loc
)
{
  return rtems_filesystem_location_is_null( &global_loc->location );
}
 
static inline void rtems_filesystem_location_error(
  const rtems_filesystem_location_info_t *loc,
  int eno
)
{
  if ( !rtems_filesystem_location_is_null( loc ) ) {
    errno = eno;
  }
}
 
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
);
 
static inline bool rtems_filesystem_is_ready_for_unmount(
  rtems_filesystem_mount_table_entry_t *mt_entry
)
{
  bool ready = !mt_entry->mounted
    && rtems_chain_has_only_one_node( &mt_entry->location_chain )
    && mt_entry->mt_fs_root->reference_count == 1;
 
  if ( ready ) {
    rtems_chain_initialize_empty( &mt_entry->location_chain );
  }
 
  return ready;
}
 
static inline void rtems_filesystem_location_add_to_mt_entry(
  rtems_filesystem_location_info_t *loc
)
{
  rtems_filesystem_mt_entry_declare_lock_context( lock_context );
 
  rtems_filesystem_mt_entry_lock( lock_context );
  rtems_chain_append_unprotected(
    &loc->mt_entry->location_chain,
    &loc->mt_entry_node
  );
  rtems_filesystem_mt_entry_unlock( lock_context );
}
 
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
);
 
static inline bool rtems_filesystem_location_is_instance_root(
  const rtems_filesystem_location_info_t *loc
)
{
  const rtems_filesystem_mount_table_entry_t *mt_entry = loc->mt_entry;
 
  return (*mt_entry->ops->are_nodes_equal_h)(
    loc,
    &mt_entry->mt_fs_root->location
  );
}
 
static inline const char *rtems_filesystem_eval_path_get_path(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->path;
}
 
static inline size_t rtems_filesystem_eval_path_get_pathlen(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->pathlen;
}
 
static inline void rtems_filesystem_eval_path_set_path(
  rtems_filesystem_eval_path_context_t *ctx,
  const char *path,
  size_t pathlen
)
{
  ctx->path = path;
  ctx->pathlen = pathlen;
}
 
static inline void rtems_filesystem_eval_path_clear_path(
  rtems_filesystem_eval_path_context_t *ctx
)
{
  ctx->pathlen = 0;
}
 
static inline const char *rtems_filesystem_eval_path_get_token(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->token;
}
 
static inline size_t rtems_filesystem_eval_path_get_tokenlen(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->tokenlen;
}
 
static inline void rtems_filesystem_eval_path_set_token(
  rtems_filesystem_eval_path_context_t *ctx,
  const char *token,
  size_t tokenlen
)
{
  ctx->token = token;
  ctx->tokenlen = tokenlen;
}
 
static inline void rtems_filesystem_eval_path_clear_token(
  rtems_filesystem_eval_path_context_t *ctx
)
{
  ctx->tokenlen = 0;
}
 
static inline void rtems_filesystem_eval_path_put_back_token(
  rtems_filesystem_eval_path_context_t *ctx
)
{
  size_t tokenlen = ctx->tokenlen;
 
  ctx->path -= tokenlen;
  ctx->pathlen += tokenlen;
  ctx->tokenlen = 0;
}
 
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
);
 
static inline void rtems_filesystem_eval_path_get_next_token(
  rtems_filesystem_eval_path_context_t *ctx,
  const char **token,
  size_t *tokenlen
)
{
  rtems_filesystem_eval_path_next_token(ctx);
  *token = ctx->token;
  *tokenlen = ctx->tokenlen;
}
 
static inline rtems_filesystem_location_info_t *
rtems_filesystem_eval_path_get_currentloc(
  rtems_filesystem_eval_path_context_t *ctx
)
{
  return &ctx->currentloc;
}
 
static inline bool rtems_filesystem_eval_path_has_path(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->pathlen > 0;
}
 
static inline bool rtems_filesystem_eval_path_has_token(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->tokenlen > 0;
}
 
static inline int rtems_filesystem_eval_path_get_flags(
  const rtems_filesystem_eval_path_context_t *ctx
)
{
  return ctx->flags;
}
 
static inline void rtems_filesystem_eval_path_set_flags(
  rtems_filesystem_eval_path_context_t *ctx,
  int flags
)
{
  ctx->flags = flags;
}
 
static inline void rtems_filesystem_eval_path_clear_and_set_flags(
  rtems_filesystem_eval_path_context_t *ctx,
  int clear,
  int set
)
{
  int flags = ctx->flags;
 
  flags &= ~clear;
  flags |= set;
 
  ctx->flags = flags;
}
 
static inline void rtems_filesystem_eval_path_extract_currentloc(
  rtems_filesystem_eval_path_context_t *ctx,
  rtems_filesystem_location_info_t *get
)
{
  rtems_filesystem_location_copy_and_detach(
    get,
    &ctx->currentloc
  );
}
 
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
);
 
bool rtems_filesystem_check_access(
  int flags,
  mode_t object_mode,
  uid_t object_uid,
  gid_t object_gid
);
 
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
);
 
static inline bool rtems_filesystem_is_delimiter(char c)
{
  return c == '/' || c == '\\';
}
 
static inline bool rtems_filesystem_is_current_directory(
  const char *token,
  size_t tokenlen
)
{
  return tokenlen == 1 && token [0] == '.';
}
 
static inline bool rtems_filesystem_is_parent_directory(
  const char *token,
  size_t tokenlen
)
{
  return tokenlen == 2 && token [0] == '.' && token [1] == '.';
}
 
typedef ssize_t ( *rtems_libio_iovec_adapter )(
  rtems_libio_t      *iop,
  const struct iovec *iov,
  int                 iovcnt,
  ssize_t             total
);
 
static inline ssize_t rtems_libio_iovec_eval(
  int                        fd,
  const struct iovec        *iov,
  int                        iovcnt,
  unsigned int               flags,
  rtems_libio_iovec_adapter  adapter
)
{
  ssize_t        total;
  int            v;
  rtems_libio_t *iop;
 
  /*
   *  Argument validation on IO vector
   */
  if ( iov == NULL )
    rtems_set_errno_and_return_minus_one( EINVAL );
 
  if ( iovcnt <= 0 )
    rtems_set_errno_and_return_minus_one( EINVAL );
 
  if ( iovcnt > IOV_MAX )
    rtems_set_errno_and_return_minus_one( EINVAL );
 
  /*
   *  OpenGroup says that you are supposed to return EINVAL if the
   *  sum of the iov_len values in the iov array would overflow a
   *  ssize_t.
   */
  total = 0;
  for ( v = 0 ; v < iovcnt ; ++v ) {
    size_t len = iov[ v ].iov_len;
 
    if ( len > ( size_t ) ( SSIZE_MAX - total ) ) {
      rtems_set_errno_and_return_minus_one( EINVAL );
    }
 
    total += ( ssize_t ) len;
 
    if ( iov[ v ].iov_base == NULL && len != 0 ) {
      rtems_set_errno_and_return_minus_one( EINVAL );
    }
  }
 
  LIBIO_GET_IOP_WITH_ACCESS( fd, iop, flags, EBADF );
 
  if ( total > 0 ) {
    total = ( *adapter )( iop, iov, iovcnt, total );
  }
 
  rtems_libio_iop_drop( iop );
  return total;
}
 
static inline mode_t rtems_filesystem_location_type(
  const rtems_filesystem_location_info_t *loc
)
{
  struct stat st;
 
  st.st_mode = 0;
  (void) ( *loc->handlers->fstat_h )( loc, &st );
 
  return st.st_mode;
}
 
#ifdef __cplusplus
}
#endif
 
#endif
/* end of include file */