123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432 |
- /****************************************************************************
- * fs/inode/inode.h
- *
- * Copyright (C) 2007, 2009, 2012, 2014, 2017 Gregory Nutt. All rights reserved.
- * Author: Gregory Nutt <gnutt@nuttx.org>
- *
- * 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.
- * 3. Neither the name NuttX nor the names of its contributors may be
- * used to endorse or promote products derived from this software
- * without specific prior written permission.
- *
- * 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 __FS_INODE_H
- #define __FS_INODE_H
- /****************************************************************************
- * Included Files
- ****************************************************************************/
- #include <nuttx/config.h>
- #include <nuttx/compiler.h>
- #include <sys/types.h>
- #include <stdint.h>
- #include <stdbool.h>
- #include <dirent.h>
- #include <nuttx/kmalloc.h>
- #include <nuttx/fs/fs.h>
- /****************************************************************************
- * Pre-processor Definitions
- ****************************************************************************/
- #ifdef CONFIG_PSEUDOFS_SOFTLINKS
- # define SETUP_SEARCH(d,p,n) \
- do \
- { \
- (d)->path = (p); \
- (d)->node = NULL; \
- (d)->peer = NULL; \
- (d)->parent = NULL; \
- (d)->relpath = NULL; \
- (d)->linktgt = NULL; \
- (d)->buffer = NULL; \
- (d)->nofollow = (n); \
- } \
- while (0)
- # define RELEASE_SEARCH(d) \
- if ((d)->buffer != NULL) \
- { \
- kmm_free((d)->buffer); \
- (d)->buffer = NULL; \
- }
- #else
- # define SETUP_SEARCH(d,p,n) \
- do \
- { \
- (d)->path = (p); \
- (d)->node = NULL; \
- (d)->peer = NULL; \
- (d)->parent = NULL; \
- (d)->relpath = NULL; \
- } \
- while (0)
- # define RELEASE_SEARCH(d)
- #endif
- /****************************************************************************
- * Public Types
- ****************************************************************************/
- /* This is the type of the argument to inode_search().
- *
- * path - INPUT: Path of inode to find
- * OUTPUT: Residual part of path not traversed
- * node - INPUT: (not used)
- * OUTPUT: On success, holds the pointer to the inode found.
- * peer - INPUT: (not used)
- * OUTPUT: The inode to the "left" of the inode found.
- * parent - INPUT: (not used)
- * OUTPUT: The inode to the "above" of the inode found.
- * relpath - INPUT: (not used)
- * OUTPUT: If the returned inode is a mountpoint, this is the
- * relative path from the mountpoint.
- * linktgt - INPUT: (not used)
- * OUTPUT: If a symobolic link into a mounted file system is
- * detected while traversing the path, then the link
- * will be converted to a mountpoint inode if the
- * mountpoint link is in an intermediate node of the
- * path or at the final node of the path with nofollow=true.
- * nofollow - INPUT: true: terminal node is returned; false: if the
- * terminal is a soft link, then return the inode of
- * the link target.
- * - OUTPUT: (not used)
- * buffer - INPUT: Not used
- * - OUTPUT: May hold an allocated intermediate path which is
- * probably of no interest to the caller unless it holds
- * the relpath.
- */
- struct inode_search_s
- {
- FAR const char *path; /* Path of inode to find */
- FAR struct inode *node; /* Pointer to the inode found */
- FAR struct inode *peer; /* Node to the "left" for the found inode */
- FAR struct inode *parent; /* Node "above" the found inode */
- FAR const char *relpath; /* Relative path into the mountpoint */
- #ifdef CONFIG_PSEUDOFS_SOFTLINKS
- FAR const char *linktgt; /* Target of symbolic link if linked to a directory */
- FAR char *buffer; /* Path expansion buffer */
- bool nofollow; /* true: Don't follow terminal soft link */
- #endif
- };
- /* Callback used by foreach_inode to traverse all inodes in the pseudo-
- * file system.
- */
- typedef int (*foreach_inode_t)(FAR struct inode *node,
- FAR char dirpath[PATH_MAX],
- FAR void *arg);
- /****************************************************************************
- * Public Data
- ****************************************************************************/
- #undef EXTERN
- #if defined(__cplusplus)
- #define EXTERN extern "C"
- extern "C"
- {
- #else
- #define EXTERN extern
- #endif
- EXTERN FAR struct inode *g_root_inode;
- /****************************************************************************
- * Public Function Prototypes
- ****************************************************************************/
- /****************************************************************************
- * Name: inode_initialize
- *
- * Description:
- * This is called from the OS initialization logic to configure the file
- * system.
- *
- ****************************************************************************/
- void inode_initialize(void);
- /****************************************************************************
- * Name: inode_semtake
- *
- * Description:
- * Get exclusive access to the in-memory inode tree (tree_sem).
- *
- ****************************************************************************/
- void inode_semtake(void);
- /****************************************************************************
- * Name: inode_semgive
- *
- * Description:
- * Relinquish exclusive access to the in-memory inode tree (tree_sem).
- *
- ****************************************************************************/
- void inode_semgive(void);
- /****************************************************************************
- * Name: inode_search
- *
- * Description:
- * Find the inode associated with 'path' returning the inode references
- * and references to its companion nodes.
- *
- * If a mountpoint is encountered in the search prior to encountering the
- * terminal node, the search will terminate at the mountpoint inode. That
- * inode and the relative path from the mountpoint, 'relpath' will be
- * returned.
- *
- * inode_search will follow soft links in path leading up to the terminal
- * node. Whether or no inode_search() will deference that terminal node
- * depends on the 'nofollow' input.
- *
- * If a soft link is encountered that is not the terminal node in the path,
- * that link WILL be deferenced unconditionally.
- *
- * Assumptions:
- * The caller holds the g_inode_sem semaphore
- *
- ****************************************************************************/
- int inode_search(FAR struct inode_search_s *desc);
- /****************************************************************************
- * Name: inode_find
- *
- * Description:
- * This is called from the open() logic to get a reference to the inode
- * associated with a path. This is accomplished by calling inode_search().
- * inode_find() is a simple wrapper around inode_search(). The primary
- * difference between inode_find() and inode_search is that inode_find()
- * will lock the inode tree and increment the reference count on the inode.
- *
- ****************************************************************************/
- int inode_find(FAR struct inode_search_s *desc);
- /****************************************************************************
- * Name: inode_stat
- *
- * Description:
- * The inode_stat() function will obtain information about an 'inode' in
- * the pseudo file system and will write it to the area pointed to by 'buf'.
- *
- * The 'buf' argument is a pointer to a stat structure, as defined in
- * <sys/stat.h>, into which information is placed concerning the file.
- *
- * Input Parameters:
- * inode - The indoe of interest
- * buf - The caller provide location in which to return information about
- * the inode.
- *
- * Returned Value:
- * Zero (OK) returned on success. Otherwise, a negated errno value is
- * returned to indicate the nature of the failure.
- *
- ****************************************************************************/
- struct stat; /* Forward reference */
- int inode_stat(FAR struct inode *inode, FAR struct stat *buf);
- /****************************************************************************
- * Name: inode_free
- *
- * Description:
- * Free resources used by an inode
- *
- ****************************************************************************/
- void inode_free(FAR struct inode *node);
- /****************************************************************************
- * Name: inode_nextname
- *
- * Description:
- * Given a path with node names separated by '/', return the next node
- * name.
- *
- ****************************************************************************/
- const char *inode_nextname(FAR const char *name);
- /****************************************************************************
- * Name: inode_reserve
- *
- * Description:
- * Reserve an (initialized) inode the pseudo file system.
- *
- * NOTE: Caller must hold the inode semaphore
- *
- * Input Parameters:
- * path - The path to the inode to create
- * inode - The location to return the inode pointer
- *
- * Returned Value:
- * Zero on success (with the inode point in 'inode'); A negated errno
- * value is returned on failure:
- *
- * EINVAL - 'path' is invalid for this operation
- * EEXIST - An inode already exists at 'path'
- * ENOMEM - Failed to allocate in-memory resources for the operation
- *
- ****************************************************************************/
- int inode_reserve(FAR const char *path, FAR struct inode **inode);
- /****************************************************************************
- * Name: inode_unlink
- *
- * Description:
- * Given a path, remove a the node from the in-memory, inode tree that the
- * path refers to. This is normally done in preparation to removing or
- * moving an inode.
- *
- * Assumptions/Limitations:
- * The caller must hold the inode semaphore
- *
- ****************************************************************************/
- FAR struct inode *inode_unlink(FAR const char *path);
- /****************************************************************************
- * Name: inode_remove
- *
- * Description:
- * Given a path, remove a the node from the in-memory, inode tree that the
- * path refers to and free all resources related to the inode. If the
- * inode is in-use, then it will be unlinked, but will not be freed until
- * the last reference to the inode is released.
- *
- * Assumptions/Limitations:
- * The caller must hold the inode semaphore
- *
- ****************************************************************************/
- int inode_remove(FAR const char *path);
- /****************************************************************************
- * Name: inode_addref
- *
- * Description:
- * Increment the reference count on an inode (as when a file descriptor
- * is dup'ed).
- *
- ****************************************************************************/
- void inode_addref(FAR struct inode *inode);
- /****************************************************************************
- * Name: inode_release
- *
- * Description:
- * This is called from close() logic when it no longer refers to the inode.
- *
- ****************************************************************************/
- void inode_release(FAR struct inode *inode);
- /****************************************************************************
- * Name: foreach_inode
- *
- * Description:
- * Visit each inode in the pseudo-file system. The traversal is terminated
- * when the callback 'handler' returns a non-zero value, or when all of
- * the inodes have been visited.
- *
- * NOTE 1: Use with caution... The pseudo-file system is locked throughout
- * the traversal.
- * NOTE 2: The search algorithm is recursive and could, in principle, use
- * an indeterminant amount of stack space. This will not usually be a
- * real work issue.
- *
- ****************************************************************************/
- int foreach_inode(foreach_inode_t handler, FAR void *arg);
- /****************************************************************************
- * Name: files_initialize
- *
- * Description:
- * This is called from the FS initialization logic to configure the files.
- *
- ****************************************************************************/
- void weak_function files_initialize(void);
- /****************************************************************************
- * Name: files_allocate
- *
- * Description:
- * Allocate a struct files instance and associate it with an inode instance.
- * Returns the file descriptor == index into the files array.
- *
- ****************************************************************************/
- int files_allocate(FAR struct inode *inode, int oflags, off_t pos, int minfd);
- /****************************************************************************
- * Name: files_close
- *
- * Description:
- * Close an inode (if open)
- *
- * Assumuptions:
- * Caller holds the list semaphore because the file descriptor will be freed.
- *
- ****************************************************************************/
- int files_close(int fd);
- /****************************************************************************
- * Name: files_release
- *
- * Assumuptions:
- * Similar to files_close(). Called only from open() logic on error
- * conditions.
- *
- ****************************************************************************/
- void files_release(int fd);
- #undef EXTERN
- #if defined(__cplusplus)
- }
- #endif
- #endif /* __FS_INODE_H */
|