rtems/rfs/rtems-rfs-dir.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief RTEMS File System Directory Support
0007  *
0008  * @ingroup rtems_rfs
0009  *
0010  * RTEMS File System Directory Support
0011  *
0012  * This file provides the directory support functions.
0013  */
0014
0015 /*
0016  *  COPYRIGHT (c) 2010 Chris Johns <chrisj@rtems.org>
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #if !defined (_RTEMS_RFS_DIR_H_)
0041 #define _RTEMS_RFS_DIR_H_
0042
0043 #include <dirent.h>
0044
0045 #include <rtems/libio_.h>
0046
0047 #include <rtems/rfs/rtems-rfs-data.h>
0048 #include <rtems/rfs/rtems-rfs-file-system.h>
0049 #include <rtems/rfs/rtems-rfs-inode.h>
0050
0051 /**
0052  * Define the offsets of the fields of a directory entry.
0053  */
0054 #define RTEMS_RFS_DIR_ENTRY_INO  (0) /**< The ino offset in a directory
0055                                       * entry. */
0056 #define RTEMS_RFS_DIR_ENTRY_HASH (4) /**< The hash offset in a directory
0057                                       * entry. The hash is 32bits. We need at
0058                                       * least 16bits and given the length and
0059                                       * ino field are 4 the extra 2 bytes is
0060                                       * not a big overhead.*/
0061 #define RTEMS_RFS_DIR_ENTRY_LEN  (8) /**< The length offset in a directory
0062                                       * entry. */
0063
0064 /**
0065  * The length of the directory entry header.
0066  */
0067 #define RTEMS_RFS_DIR_ENTRY_SIZE (4 + 4 + 2)
0068
0069 /**
0070  * The length when the remainder of the directory block is empty.
0071  */
0072 #define RTEMS_RFS_DIR_ENTRY_EMPTY (0xffff)
0073
0074 /**
0075  * Return the hash of the entry.
0076  *
0077  * @param[in] _e is a pointer to the directory entry.
0078  *
0079  * @retval hash The uint32_t hash of the entry.
0080  */
0081 #define rtems_rfs_dir_entry_hash(_e) \
0082   rtems_rfs_read_u32 (_e + RTEMS_RFS_DIR_ENTRY_HASH)
0083
0084 /**
0085  * Set the hash of the entry.
0086  *
0087  * @param[in] _e is a pointer to the directory entry.
0088  *
0089  * @param[in] _h is the hash of the entry.
0090  */
0091 #define rtems_rfs_dir_set_entry_hash(_e, _h) \
0092   rtems_rfs_write_u32 (_e + RTEMS_RFS_DIR_ENTRY_HASH, _h)
0093
0094 /**
0095  * Return the ino of the entry.
0096  *
0097  * @param[in] _e is a pointer to the directory entry.
0098  *
0099  * @retval ino The ino of the entry.
0100  */
0101 #define rtems_rfs_dir_entry_ino(_e) \
0102   rtems_rfs_read_u32 (_e + RTEMS_RFS_DIR_ENTRY_INO)
0103
0104 /**
0105  * Set the ino of the entry.
0106  *
0107  * @param[in] _e is a pointer to the directory entry.
0108  *
0109  * @param[in] _i is the ino of the entry.
0110  */
0111 #define rtems_rfs_dir_set_entry_ino(_e, _i) \
0112   rtems_rfs_write_u32 (_e + RTEMS_RFS_DIR_ENTRY_INO, _i)
0113
0114 /**
0115  * Return the length of the entry.
0116  *
0117  * @param[in] _e Pointer to the directory entry.
0118  *
0119  * @retval length The length of the entry.
0120  */
0121 #define rtems_rfs_dir_entry_length(_e) \
0122   rtems_rfs_read_u16 (_e + RTEMS_RFS_DIR_ENTRY_LEN)
0123
0124 /**
0125  * Set the length of the entry.
0126  *
0127  * @param[in] _e is a pointer to the directory entry.
0128  * @param[in] _l is the length.
0129  */
0130 #define rtems_rfs_dir_set_entry_length(_e, _l) \
0131   rtems_rfs_write_u16 (_e + RTEMS_RFS_DIR_ENTRY_LEN, _l)
0132
0133 /**
0134  * Look up a directory entry in the directory pointed to by the inode. The look
0135  * up is local to this directory. No need to decend.
0136  *
0137  * @param[in] fs is the file system.
0138  * @param[in] inode is a pointer to the inode of the directory to search.
0139  * @param[in] name is a pointer to the name to look up. The name may not be
0140  *             nul terminated.
0141  * @param[in] length is the length of the name.
0142  * @param[out] ino will be filled in with the inode number
0143  *              if there is no error.
0144  * @param[in] offset is the offset in the directory for the entry.
0145  *
0146  * @retval 0 Successful operation.
0147  * @retval error_code An error occurred.
0148  */
0149 int rtems_rfs_dir_lookup_ino (rtems_rfs_file_system*  fs,
0150                               rtems_rfs_inode_handle* inode,
0151                               const char*             name,
0152                               int                     length,
0153                               rtems_rfs_ino*          ino,
0154                               uint32_t*               offset);
0155
0156 /**
0157  * Add an entry to the directory returing the inode number allocated to the
0158  * entry.
0159  *
0160  * @param[in] fs is the file system data.
0161  * @param[in] dir is a pointer to the directory inode the
0162  *             entry is to be added too.
0163  * @param[in] name is a pointer to the name of the entry to be added.
0164  * @param[in] length is the length of the name excluding a terminating 0.
0165  * @param[in] ino is the ino of the entry.
0166  *
0167  * @retval 0 Successful operation.
0168  * @retval error_code An error occurred.
0169  */
0170 int rtems_rfs_dir_add_entry (rtems_rfs_file_system*  fs,
0171                              rtems_rfs_inode_handle* dir,
0172                              const char*             name,
0173                              size_t                  length,
0174                              rtems_rfs_ino           ino);
0175
0176 /**
0177  * Del an entry from the directory using an inode number as a key.
0178  *
0179  * @param[in] fs is the file system data.
0180  * @param[in] dir is a pointer to the directory inode the
0181  * entry is to be deleted from.
0182  * @param[in] ino is the ino of the entry.
0183  * @param[in] offset is the offset in the directory of the entry
0184  *               to delete. If 0  search from the start for the ino.
0185  *
0186  * @retval 0 Successful operation.
0187  * @retval error_code An error occurred.
0188  */
0189 int rtems_rfs_dir_del_entry (rtems_rfs_file_system*  fs,
0190                              rtems_rfs_inode_handle* dir,
0191                              rtems_rfs_ino           ino,
0192                              uint32_t                offset);
0193
0194 /**
0195  * Read the directory entry from offset into the directory entry buffer and
0196  * return the length of space this entry uses in the directory table.
0197  *
0198  * @param[in] fs is the file system data.
0199  * @param[in] dir is a pointer to the direct inode handler.
0200  * @param[in] offset is the offset in the directory to read from.
0201  * @param[in] dirent is a ointer to the dirent structure the entry
0202  *              is written into.
0203  * @param[out] length will contain the length this entry
0204  *               takes in the directory.
0205  *
0206  * @retval 0 Successful operation.
0207  * @retval error_code An error occurred.
0208  */
0209 int rtems_rfs_dir_read (rtems_rfs_file_system*  fs,
0210                         rtems_rfs_inode_handle* dir,
0211                         rtems_rfs_pos_rel       offset,
0212                         struct dirent*          dirent,
0213                         size_t*                 length);
0214
0215 /**
0216  * Check if the directory is empty. The current and parent directory entries
0217  * are ignored.
0218  *
0219  * @param[in] fs is the file system data
0220  * @param[in] dir is a pointer to the directory inode to check.
0221  *
0222  * @retval 0 Successful operation.
0223  * @retval error_code An error occurred.
0224  */
0225 int rtems_rfs_dir_empty (rtems_rfs_file_system*  fs,
0226                          rtems_rfs_inode_handle* dir);
0227
0228 #endif