1 /**************************************************************************** 2 * fs/inode/inode.h 3 * 4 * Licensed to the Apache Software Foundation (ASF) under one or more 5 * contributor license agreements. See the NOTICE file distributed with 6 * this work for additional information regarding copyright ownership. The 7 * ASF licenses this file to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance with the 9 * License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, software 14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 16 * License for the specific language governing permissions and limitations 17 * under the License. 18 * 19 ****************************************************************************/ 20 21 #ifndef __FS_INODE_H 22 #define __FS_INODE_H 23 24 /**************************************************************************** 25 * Included Files 26 ****************************************************************************/ 27 28 #include <nuttx/config.h> 29 #include <nuttx/compiler.h> 30 31 #include <sys/types.h> 32 #include <stdint.h> 33 #include <stdbool.h> 34 #include <dirent.h> 35 36 #include <nuttx/kmalloc.h> 37 #ifdef CONFIG_VFS_DISABLE_INCLUDE_NUTTX_FS_H 38 #include "limits.h" 39 #include "fs/fs.h" 40 #include "fs/file.h" 41 #else 42 #include <nuttx/fs/fs.h> 43 #endif 44 45 #ifdef CONFIG_VFS_SUPPORT_ERROR_RETURN 46 #ifndef ERROR 47 #define ERROR -1 48 #endif 49 #endif 50 /**************************************************************************** 51 * Pre-processor Definitions 52 ****************************************************************************/ 53 54 #define SETUP_SEARCH(d,p,n) \ 55 do \ 56 { \ 57 (d)->path = (p); \ 58 (d)->node = NULL; \ 59 (d)->peer = NULL; \ 60 (d)->parent = NULL; \ 61 (d)->relpath = NULL; \ 62 (d)->buffer = NULL; \ 63 (d)->nofollow = (n); \ 64 } \ 65 while (0) 66 67 #define RELEASE_SEARCH(d) \ 68 do \ 69 { \ 70 if ((d)->buffer != NULL) \ 71 { \ 72 kmm_free((d)->buffer); \ 73 (d)->buffer = NULL; \ 74 } \ 75 } \ 76 while (0) 77 78 /**************************************************************************** 79 * Public Types 80 ****************************************************************************/ 81 82 /* This is the type of the argument to inode_search(). 83 * 84 * path - INPUT: Path of inode to find 85 * OUTPUT: Residual part of path not traversed 86 * node - INPUT: (not used) 87 * OUTPUT: On success, holds the pointer to the inode found. 88 * peer - INPUT: (not used) 89 * OUTPUT: The inode to the "left" of the inode found. 90 * parent - INPUT: (not used) 91 * OUTPUT: The inode to the "above" of the inode found. 92 * relpath - INPUT: (not used) 93 * OUTPUT: If the returned inode is a mountpoint, this is the 94 * relative path from the mountpoint. 95 * OUTPUT: If a symobolic link into a mounted file system is 96 * detected while traversing the path, then the link 97 * will be converted to a mountpoint inode if the 98 * mountpoint link is in an intermediate node of the 99 * path or at the final node of the path with 100 * nofollow=true. 101 * nofollow - INPUT: true: terminal node is returned; false: if the 102 * terminal is a soft link, then return the inode of 103 * the link target. 104 * - OUTPUT: (not used) 105 * buffer - INPUT: Not used 106 * - OUTPUT: May hold an allocated intermediate path which is 107 * probably of no interest to the caller unless it holds 108 * the relpath. 109 */ 110 111 struct inode_search_s 112 { 113 FAR const char *path; /* Path of inode to find */ 114 FAR struct inode *node; /* Pointer to the inode found */ 115 FAR struct inode *peer; /* Node to the "left" for the found inode */ 116 FAR struct inode *parent; /* Node "above" the found inode */ 117 FAR const char *relpath; /* Relative path into the mountpoint */ 118 FAR char *buffer; /* Path expansion buffer */ 119 bool nofollow; /* true: Don't follow terminal soft link */ 120 }; 121 122 /* Callback used by foreach_inode to traverse all inodes in the pseudo- 123 * file system. 124 */ 125 126 typedef int (*foreach_inode_t)(FAR struct inode *node, 127 FAR char dirpath[PATH_MAX], 128 FAR void *arg); 129 130 /**************************************************************************** 131 * Public Data 132 ****************************************************************************/ 133 134 #undef EXTERN 135 #if defined(__cplusplus) 136 #define EXTERN extern "C" 137 extern "C" 138 { 139 #else 140 #define EXTERN extern 141 #endif 142 143 EXTERN FAR struct inode *g_root_inode; 144 145 /**************************************************************************** 146 * Public Function Prototypes 147 ****************************************************************************/ 148 149 /**************************************************************************** 150 * Name: inode_initialize 151 * 152 * Description: 153 * This is called from the OS initialization logic to configure the file 154 * system. 155 * 156 ****************************************************************************/ 157 158 void inode_initialize(void); 159 160 /**************************************************************************** 161 * Name: inode_semtake 162 * 163 * Description: 164 * Get exclusive access to the in-memory inode tree (tree_sem). 165 * 166 ****************************************************************************/ 167 168 int inode_semtake(void); 169 170 /**************************************************************************** 171 * Name: inode_semgive 172 * 173 * Description: 174 * Relinquish exclusive access to the in-memory inode tree (tree_sem). 175 * 176 ****************************************************************************/ 177 178 void inode_semgive(void); 179 180 /**************************************************************************** 181 * Name: inode_checkflags 182 * 183 * Description: 184 * Check if the access described by 'oflags' is supported on 'inode' 185 * 186 ****************************************************************************/ 187 188 int inode_checkflags(FAR struct inode *inode, int oflags); 189 190 /**************************************************************************** 191 * Name: inode_search 192 * 193 * Description: 194 * Find the inode associated with 'path' returning the inode references 195 * and references to its companion nodes. 196 * 197 * If a mountpoint is encountered in the search prior to encountering the 198 * terminal node, the search will terminate at the mountpoint inode. That 199 * inode and the relative path from the mountpoint, 'relpath' will be 200 * returned. 201 * 202 * inode_search will follow soft links in path leading up to the terminal 203 * node. Whether or no inode_search() will deference that terminal node 204 * depends on the 'nofollow' input. 205 * 206 * If a soft link is encountered that is not the terminal node in the path, 207 * that link WILL be deferenced unconditionally. 208 * 209 * Assumptions: 210 * The caller holds the g_inode_sem semaphore 211 * 212 ****************************************************************************/ 213 214 int inode_search(FAR struct inode_search_s *desc); 215 216 /**************************************************************************** 217 * Name: inode_find 218 * 219 * Description: 220 * This is called from the open() logic to get a reference to the inode 221 * associated with a path. This is accomplished by calling inode_search(). 222 * inode_find() is a simple wrapper around inode_search(). The primary 223 * difference between inode_find() and inode_search is that inode_find() 224 * will lock the inode tree and increment the reference count on the inode. 225 * 226 ****************************************************************************/ 227 228 int inode_find(FAR struct inode_search_s *desc); 229 230 /**************************************************************************** 231 * Name: inode_stat 232 * 233 * Description: 234 * The inode_stat() function will obtain information about an 'inode' in 235 * the pseudo file system and will write it to the area pointed to by 236 * 'buf'. 237 * 238 * The 'buf' argument is a pointer to a stat structure, as defined in 239 * <sys/stat.h>, into which information is placed concerning the file. 240 * 241 * Input Parameters: 242 * inode - The inode of interest 243 * buf - The caller-provided location in which to return information 244 * about the inode. 245 * resolve - Whether to resolve the symbolic link: 246 * 0: Don't resolve the symbolic line 247 * 1: Resolve the symbolic link 248 * >=2: The recursive count in the resolving process 249 * 250 * Returned Value: 251 * Zero (OK) returned on success. Otherwise, a negated errno value is 252 * returned to indicate the nature of the failure. 253 * 254 ****************************************************************************/ 255 256 int inode_stat(FAR struct inode *inode, FAR struct stat *buf, int resolve); 257 258 /**************************************************************************** 259 * Name: inode_chstat 260 * 261 * Description: 262 * The inode_chstat() function will change information about an 'inode' 263 * in the pseudo file system according the area pointed to by 'buf'. 264 * 265 * The 'buf' argument is a pointer to a stat structure, as defined in 266 * <sys/stat.h>, which information is placed concerning the file. 267 * 268 * Input Parameters: 269 * inode - The inode of interest 270 * buf - The caller provide location in which to apply information 271 * about the inode. 272 * flags - The vaild field in buf 273 * resolve - Whether to resolve the symbolic link 274 * 275 * Returned Value: 276 * Zero (OK) returned on success. Otherwise, a negated errno value is 277 * returned to indicate the nature of the failure. 278 * 279 ****************************************************************************/ 280 281 int inode_chstat(FAR struct inode *inode, 282 FAR const struct stat *buf, int flags, int resolve); 283 284 /**************************************************************************** 285 * Name: inode_getpath 286 * 287 * Description: 288 * Given the full path from inode. 289 * 290 ****************************************************************************/ 291 292 int inode_getpath(FAR struct inode *node, FAR char *path); 293 294 /**************************************************************************** 295 * Name: inode_free 296 * 297 * Description: 298 * Free resources used by an inode 299 * 300 ****************************************************************************/ 301 302 void inode_free(FAR struct inode *node); 303 304 /**************************************************************************** 305 * Name: inode_nextname 306 * 307 * Description: 308 * Given a path with node names separated by '/', return the next node 309 * name. 310 * 311 ****************************************************************************/ 312 313 const char *inode_nextname(FAR const char *name); 314 315 /**************************************************************************** 316 * Name: inode_root_reserve 317 * 318 * Description: 319 * Reserve the root node for the pseudo file system. 320 * 321 ****************************************************************************/ 322 323 void inode_root_reserve(void); 324 325 /**************************************************************************** 326 * Name: inode_reserve 327 * 328 * Description: 329 * Reserve an (initialized) inode the pseudo file system. 330 * 331 * NOTE: Caller must hold the inode semaphore 332 * 333 * Input Parameters: 334 * path - The path to the inode to create 335 * mode - inmode privileges 336 * inode - The location to return the inode pointer 337 * 338 * Returned Value: 339 * Zero on success (with the inode point in 'inode'); A negated errno 340 * value is returned on failure: 341 * 342 * EINVAL - 'path' is invalid for this operation 343 * EEXIST - An inode already exists at 'path' 344 * ENOMEM - Failed to allocate in-memory resources for the operation 345 * 346 ****************************************************************************/ 347 348 int inode_reserve(FAR const char *path, 349 mode_t mode, FAR struct inode **inode); 350 351 /**************************************************************************** 352 * Name: inode_unlink 353 * 354 * Description: 355 * Given a path, remove a the node from the in-memory, inode tree that the 356 * path refers to. This is normally done in preparation to removing or 357 * moving an inode. 358 * 359 * Assumptions/Limitations: 360 * The caller must hold the inode semaphore 361 * 362 ****************************************************************************/ 363 364 FAR struct inode *inode_unlink(FAR const char *path); 365 366 /**************************************************************************** 367 * Name: inode_remove 368 * 369 * Description: 370 * Given a path, remove a the node from the in-memory, inode tree that the 371 * path refers to and free all resources related to the inode. If the 372 * inode is in-use, then it will be unlinked, but will not be freed until 373 * the last reference to the inode is released. 374 * 375 * Assumptions/Limitations: 376 * The caller must hold the inode semaphore 377 * 378 ****************************************************************************/ 379 380 int inode_remove(FAR const char *path); 381 382 /**************************************************************************** 383 * Name: inode_addref 384 * 385 * Description: 386 * Increment the reference count on an inode (as when a file descriptor 387 * is dup'ed). 388 * 389 ****************************************************************************/ 390 391 int inode_addref(FAR struct inode *inode); 392 393 /**************************************************************************** 394 * Name: inode_release 395 * 396 * Description: 397 * This is called from close() logic when it no longer refers to the inode. 398 * 399 ****************************************************************************/ 400 401 void inode_release(FAR struct inode *inode); 402 403 /**************************************************************************** 404 * Name: foreach_inode 405 * 406 * Description: 407 * Visit each inode in the pseudo-file system. The traversal is terminated 408 * when the callback 'handler' returns a non-zero value, or when all of 409 * the inodes have been visited. 410 * 411 * NOTE 1: Use with caution... The pseudo-file system is locked throughout 412 * the traversal. 413 * NOTE 2: The search algorithm is recursive and could, in principle, use 414 * an indeterminate amount of stack space. This will not usually be a 415 * real work issue. 416 * 417 ****************************************************************************/ 418 419 int foreach_inode(foreach_inode_t handler, FAR void *arg); 420 421 /**************************************************************************** 422 * Name: files_allocate 423 * 424 * Description: 425 * Allocate a struct files instance and associate it with an inode 426 * instance. Returns the file descriptor == index into the files array. 427 * 428 ****************************************************************************/ 429 430 #ifdef CONFIG_FILES_ALLOCATE_WITH_FILEP 431 int files_allocate(FAR struct inode *inode, int oflags, off_t pos, 432 FAR void *priv, int minfd, FAR struct file *filep); 433 #else 434 int files_allocate(FAR struct inode *inode, int oflags, off_t pos, 435 FAR void *priv, int minfd); 436 #endif 437 438 #ifdef CONFIG_VFS_FULLPATH_ACQUIRE 439 int vfs_normalize_path(const char *directory, const char *filename, char **pathname); 440 #endif 441 442 #ifdef CONFIG_VFS_INODE_ALLOC 443 FAR struct inode *vfs_inode_zalloc(int namelen); 444 #endif 445 446 #ifdef CONFIG_VFS_ENABLE_FILE_STRUCT_PATH 447 int vfs_dup_process_file_struct_path(FAR struct file *filep1, char **fullpath, 448 struct file *temp, struct inode_search_s *desc); 449 void vfs_release_for_dup_failed(char *fullpath, FAR struct inode *inode, struct inode_search_s *desc); 450 #endif 451 452 #undef EXTERN 453 #if defined(__cplusplus) 454 } 455 #endif 456 457 #endif /* __FS_INODE_H */ 458