1 /**************************************************************************** 2 * include/nuttx/fs/fs.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 __INCLUDE_NUTTX_FS_FS_H 22 #define __INCLUDE_NUTTX_FS_FS_H 23 24 /**************************************************************************** 25 * Included Files 26 ****************************************************************************/ 27 28 #include <nuttx/config.h> 29 #include <nuttx/compiler.h> 30 #ifdef CONFIG_VFS_POLL_WITHOUT_SETUP 31 #include <poll.h> 32 #endif 33 #include <sys/types.h> 34 #include <sys/stat.h> 35 36 #include <stdarg.h> 37 #include <stdint.h> 38 #include <stdbool.h> 39 #include <time.h> 40 #ifdef CONFIG_VFS_EXTEND_HEADER_FILE 41 #include <vfs_extend.h> 42 #endif 43 #include <nuttx/semaphore.h> 44 45 /**************************************************************************** 46 * Pre-processor Definitions 47 ****************************************************************************/ 48 49 /* Most internal OS interfaces are not available in the user space in 50 * PROTECTED and KERNEL builds. In that context, the corresponding 51 * application interfaces must be used. The differences between the two 52 * sets of interfaces are: The internal OS interfaces (1) do not cause 53 * cancellation points and (2) they do not modify the errno variable. 54 * 55 * This is only important when compiling libraries (libc or libnx) that are 56 * used both by the OS (libkc.a and libknx.a) or by the applications 57 * (libc.a and libnx.a). In that case, the correct interface must be 58 * used for the build context. 59 * 60 * REVISIT: In the flat build, the same functions must be used both by 61 * the OS and by applications. We have to use the normal user functions 62 * in this case or we will fail to set the errno or fail to create the 63 * cancellation point. 64 * 65 * The interfaces close(), creat(), read(), pread(), write(), pwrite(), 66 * poll(), select(), fcntl(), and aio_suspend() are all cancellation 67 * points. 68 * 69 * REVISIT: These cancellation points are an issue and may cause 70 * violations: It use of these internally will cause the calling function 71 * to become a cancellation points! 72 */ 73 74 #if !defined(CONFIG_BUILD_FLAT) && defined(__KERNEL__) 75 # define _NX_OPEN nx_open 76 # define _NX_CLOSE(f) nx_close(f) 77 # define _NX_READ(f,b,s) nx_read(f,b,s) 78 # define _NX_WRITE(f,b,s) nx_write(f,b,s) 79 # define _NX_SEEK(f,o,w) nx_seek(f,o,w) 80 # define _NX_IOCTL(f,r,a) nx_ioctl(f,r,a) 81 # define _NX_STAT(p,s) nx_stat(p,s,1) 82 # define _NX_GETERRNO(r) (-(r)) 83 # define _NX_SETERRNO(r) set_errno(-(r)) 84 # define _NX_GETERRVAL(r) (r) 85 #else 86 # define _NX_OPEN open 87 # define _NX_CLOSE(f) close(f) 88 # define _NX_READ(f,b,s) read(f,b,s) 89 # define _NX_WRITE(f,b,s) write(f,b,s) 90 # define _NX_SEEK(f,o,w) lseek(f,o,w) 91 # define _NX_IOCTL(f,r,a) ioctl(f,r,a) 92 # define _NX_STAT(p,s) stat(p,s) 93 # define _NX_GETERRNO(r) errno 94 # define _NX_SETERRNO(r) ((void)(r)) 95 # define _NX_GETERRVAL(r) (-errno) 96 #endif 97 98 /* Stream flags for the fs_flags field of in struct file_struct */ 99 100 #define __FS_FLAG_EOF (1 << 0) /* EOF detected by a read operation */ 101 #define __FS_FLAG_ERROR (1 << 1) /* Error detected by any operation */ 102 #define __FS_FLAG_LBF (1 << 2) /* Line buffered */ 103 #define __FS_FLAG_UBF (1 << 3) /* Buffer allocated by caller of setvbuf */ 104 105 /* Inode i_flags values: 106 * 107 * Bit 0-3: Inode type (Bit 3 indicates internal OS types) 108 * Bit 4: Set if inode has been unlinked and is pending removal. 109 */ 110 111 #define FSNODEFLAG_TYPE_MASK 0x0000000f /* Isolates type field */ 112 #define FSNODEFLAG_TYPE_PSEUDODIR 0x00000000 /* Pseudo dir (default) */ 113 #define FSNODEFLAG_TYPE_DRIVER 0x00000001 /* Character driver */ 114 #define FSNODEFLAG_TYPE_BLOCK 0x00000002 /* Block driver */ 115 #define FSNODEFLAG_TYPE_MOUNTPT 0x00000003 /* Mount point */ 116 #define FSNODEFLAG_TYPE_NAMEDSEM 0x00000004 /* Named semaphore */ 117 #define FSNODEFLAG_TYPE_MQUEUE 0x00000005 /* Message Queue */ 118 #define FSNODEFLAG_TYPE_SHM 0x00000006 /* Shared memory region */ 119 #define FSNODEFLAG_TYPE_MTD 0x00000007 /* Named MTD driver */ 120 #define FSNODEFLAG_TYPE_SOFTLINK 0x00000008 /* Soft link */ 121 #define FSNODEFLAG_TYPE_SOCKET 0x00000009 /* Socket */ 122 #define FSNODEFLAG_DELETED 0x00000010 /* Unlinked */ 123 124 #define INODE_IS_TYPE(i,t) \ 125 (((i)->i_flags & FSNODEFLAG_TYPE_MASK) == (t)) 126 127 #define INODE_IS_PSEUDODIR(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_PSEUDODIR) 128 #define INODE_IS_DRIVER(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_DRIVER) 129 #define INODE_IS_BLOCK(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_BLOCK) 130 #define INODE_IS_MOUNTPT(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_MOUNTPT) 131 #define INODE_IS_NAMEDSEM(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_NAMEDSEM) 132 #define INODE_IS_MQUEUE(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_MQUEUE) 133 #define INODE_IS_SHM(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_SHM) 134 #define INODE_IS_MTD(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_MTD) 135 #define INODE_IS_SOFTLINK(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_SOFTLINK) 136 #define INODE_IS_SOCKET(i) INODE_IS_TYPE(i,FSNODEFLAG_TYPE_SOCKET) 137 138 #define INODE_GET_TYPE(i) ((i)->i_flags & FSNODEFLAG_TYPE_MASK) 139 #define INODE_SET_TYPE(i,t) \ 140 do \ 141 { \ 142 (i)->i_flags = ((i)->i_flags & ~FSNODEFLAG_TYPE_MASK) | (t); \ 143 } \ 144 while (0) 145 146 #define INODE_SET_DRIVER(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_DRIVER) 147 #define INODE_SET_BLOCK(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_BLOCK) 148 #define INODE_SET_MOUNTPT(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_MOUNTPT) 149 #define INODE_SET_NAMEDSEM(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_NAMEDSEM) 150 #define INODE_SET_MQUEUE(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_MQUEUE) 151 #define INODE_SET_SHM(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_SHM) 152 #define INODE_SET_MTD(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_MTD) 153 #define INODE_SET_SOFTLINK(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_SOFTLINK) 154 #define INODE_SET_SOCKET(i) INODE_SET_TYPE(i,FSNODEFLAG_TYPE_SOCKET) 155 156 /* Mountpoint fd_flags values */ 157 158 #define DIRENTFLAGS_PSEUDONODE 1 159 160 #define DIRENT_SETPSEUDONODE(f) do (f) |= DIRENTFLAGS_PSEUDONODE; while (0) 161 #define DIRENT_ISPSEUDONODE(f) (((f) & DIRENTFLAGS_PSEUDONODE) != 0) 162 163 /* The status change flags. 164 * These should be or-ed together to figure out what want to change. 165 */ 166 167 #define CH_STAT_MODE (1 << 0) 168 #define CH_STAT_UID (1 << 1) 169 #define CH_STAT_GID (1 << 2) 170 #define CH_STAT_ATIME (1 << 3) 171 #define CH_STAT_MTIME (1 << 4) 172 173 #ifndef CONFIG_VFS_UNBIND_WITHOUT_FLAGS 174 /* nx_umount() is equivalent to nx_umount2() with flags = 0 */ 175 #define umount(t) umount2(t,0) 176 #endif 177 /**************************************************************************** 178 * Public Type Definitions 179 ****************************************************************************/ 180 181 /* Forward references */ 182 183 struct file; 184 struct inode; 185 struct stat; 186 struct statfs; 187 #ifndef CONFIG_VFS_POLL_DISABLE 188 struct pollfd; 189 #endif 190 struct fs_dirent_s; 191 struct mtd_dev_s; 192 193 /* This structure is provided by devices when they are registered with the 194 * system. It is used to call back to perform device specific operations. 195 */ 196 197 #ifdef CONFIG_VFS_OPERATION_EXTEND 198 struct file_operations_vfs 199 #else 200 struct file_operations 201 #endif 202 { 203 /* The device driver open method differs from the mountpoint open method */ 204 205 int (*open)(FAR struct file *filep); 206 207 /* The following methods must be identical in signature and position 208 * because the struct file_operations and struct mountp_operations are 209 * treated like unions. 210 */ 211 212 int (*close)(FAR struct file *filep); 213 ssize_t (*read)(FAR struct file *filep, FAR char *buffer, size_t buflen); 214 ssize_t (*write)(FAR struct file *filep, FAR const char *buffer, 215 size_t buflen); 216 off_t (*seek)(FAR struct file *filep, off_t offset, int whence); 217 int (*ioctl)(FAR struct file *filep, int cmd, unsigned long arg); 218 219 /* The two structures need not be common after this point */ 220 #ifndef CONFIG_VFS_POLL_DISABLE 221 #ifdef CONFIG_VFS_POLL_WITHOUT_SETUP 222 int (*poll)(FAR struct file *filep, poll_table *fds); 223 #else 224 int (*poll)(FAR struct file *filep, struct pollfd *fds, bool setup); 225 #endif 226 #endif 227 228 #ifndef CONFIG_DISABLE_PSEUDOFS_OPERATIONS 229 int (*unlink)(FAR struct inode *inode); 230 #endif 231 }; 232 233 /* This structure provides information about the state of a block driver */ 234 235 #ifndef CONFIG_DISABLE_MOUNTPOINT 236 struct geometry 237 { 238 bool geo_available; /* true: The device is available */ 239 bool geo_mediachanged; /* true: The media has changed since last query */ 240 bool geo_writeenabled; /* true: It is okay to write to this device */ 241 #ifdef CONFIG_VFS_64BIT_ACCESS 242 unsigned long long geo_nsectors; /* Number of sectors on the device */ 243 #else 244 blkcnt_t geo_nsectors; /* Number of sectors on the device */ 245 #endif 246 blksize_t geo_sectorsize; /* Size of one sector */ 247 }; 248 249 struct partition_info_s 250 { 251 size_t numsectors; /* Number of sectors in the partition */ 252 size_t sectorsize; /* Size in bytes of a single sector */ 253 off_t startsector; /* Offset to the first section/block of the 254 * managed sub-region */ 255 256 /* NULL-terminated string representing the name of the parent node of the 257 * partition. 258 */ 259 260 char parent[NAME_MAX + 1]; 261 }; 262 263 /* This structure is provided by block devices when they register with the 264 * system. It is used by file systems to perform filesystem transfers. It 265 * differs from the normal driver vtable in several ways -- most notably in 266 * that it deals in struct inode vs. struct filep. 267 */ 268 269 struct inode; 270 struct block_operations 271 { 272 int (*open)(FAR struct inode *inode); 273 int (*close)(FAR struct inode *inode); 274 #ifdef CONFIG_VFS_64BIT_ACCESS 275 ssize_t (*read)(FAR struct inode *inode, FAR unsigned char *buffer, 276 unsigned long long start_sector, unsigned int nsectors); 277 ssize_t (*write)(FAR struct inode *inode, FAR const unsigned char *buffer, 278 unsigned long long start_sector, unsigned int nsectors); 279 #else 280 ssize_t (*read)(FAR struct inode *inode, FAR unsigned char *buffer, 281 blkcnt_t start_sector, unsigned int nsectors); 282 ssize_t (*write)(FAR struct inode *inode, FAR const unsigned char *buffer, 283 blkcnt_t start_sector, unsigned int nsectors); 284 #endif 285 #ifdef CONFIG_VFS_WRITEV_SUPPORT 286 ssize_t (*writev)(FAR struct inode *inode, FAR const struct iovec *iov, /* iov_len indicates the nsectors */ 287 unsigned int cnt, unsigned long long start_sector); 288 #endif 289 int (*geometry)(FAR struct inode *inode, FAR struct geometry 290 *geometry); 291 int (*ioctl)(FAR struct inode *inode, int cmd, unsigned long arg); 292 #ifndef CONFIG_DISABLE_PSEUDOFS_OPERATIONS 293 int (*unlink)(FAR struct inode *inode); 294 #endif 295 }; 296 297 /* This structure is provided by a filesystem to describe a mount point. 298 * Note that this structure differs from file_operations ONLY in the form of 299 * the open method. Once the file is opened, it can be accessed either as a 300 * struct file_operations or struct mountpt_operations 301 */ 302 303 struct mountpt_operations 304 { 305 /* The mountpoint open method differs from the driver open method 306 * because it receives (1) the inode that contains the mountpoint 307 * private data, (2) the relative path into the mountpoint, and (3) 308 * information to manage privileges. 309 */ 310 311 int (*open)(FAR struct file *filep, FAR const char *relpath, 312 int oflags, mode_t mode); 313 314 /* The following methods must be identical in signature and position 315 * because the struct file_operations and struct mountpt_operations are 316 * treated like unions. 317 */ 318 319 int (*close)(FAR struct file *filep); 320 ssize_t (*read)(FAR struct file *filep, FAR char *buffer, size_t buflen); 321 ssize_t (*write)(FAR struct file *filep, FAR const char *buffer, 322 size_t buflen); 323 off_t (*seek)(FAR struct file *filep, off_t offset, int whence); 324 int (*ioctl)(FAR struct file *filep, int cmd, unsigned long arg); 325 326 /* The two structures need not be common after this point. The following 327 * are extended methods needed to deal with the unique needs of mounted 328 * file systems. 329 * 330 * Additional open-file-specific mountpoint operations: 331 */ 332 333 int (*sync)(FAR struct file *filep); 334 int (*dup)(FAR const struct file *oldp, FAR struct file *newp); 335 int (*fstat)(FAR const struct file *filep, FAR struct stat *buf); 336 int (*fchstat)(FAR const struct file *filep, 337 FAR const struct stat *buf, int flags); 338 int (*truncate)(FAR struct file *filep, off_t length); 339 340 /* Directory operations */ 341 342 int (*opendir)(FAR struct inode *mountpt, FAR const char *relpath, 343 FAR struct fs_dirent_s *dir); 344 int (*closedir)(FAR struct inode *mountpt, 345 FAR struct fs_dirent_s *dir); 346 int (*readdir)(FAR struct inode *mountpt, 347 FAR struct fs_dirent_s *dir); 348 int (*rewinddir)(FAR struct inode *mountpt, 349 FAR struct fs_dirent_s *dir); 350 351 /* General volume-related mountpoint operations: */ 352 #ifdef CONFIG_VFS_BIND_WITH_PATH 353 int (*bind)(FAR struct inode *blkdriver, FAR const void *data, 354 FAR void **handle, FAR const char *realpath); 355 #else 356 int (*bind)(FAR struct inode *blkdriver, FAR const void *data, 357 FAR void **handle); 358 #endif 359 #ifdef CONFIG_VFS_UNBIND_WITHOUT_FLAGS 360 int (*unbind)(FAR void *handle, FAR struct inode **blkdriver); 361 #else 362 int (*unbind)(FAR void *handle, FAR struct inode **blkdriver, 363 unsigned int flags); 364 #endif 365 int (*statfs)(FAR struct inode *mountpt, FAR struct statfs *buf); 366 #ifdef CONFIG_VFS_OPERATION_EXTEND 367 int (*virstatfs)(struct inode *mountpt, const char* relpath, struct statfs *buf); 368 #endif 369 /* Operations on paths */ 370 371 int (*unlink)(FAR struct inode *mountpt, FAR const char *relpath); 372 int (*mkdir)(FAR struct inode *mountpt, FAR const char *relpath, 373 mode_t mode); 374 int (*rmdir)(FAR struct inode *mountpt, FAR const char *relpath); 375 int (*rename)(FAR struct inode *mountpt, FAR const char *oldrelpath, 376 FAR const char *newrelpath); 377 int (*stat)(FAR struct inode *mountpt, FAR const char *relpath, 378 FAR struct stat *buf); 379 int (*chstat)(FAR struct inode *mountpt, FAR const char *relpath, 380 FAR const struct stat *buf, int flags); 381 #ifdef CONFIG_VFS_OPERATION_EXTEND 382 int (*utime)(FAR struct inode *mountpt, FAR const char *relpath, 383 FAR const struct tm *times); 384 int (*chattr)(FAR struct inode *mountpt, FAR const char *relpath, 385 mode_t mode); 386 loff_t (*seek64)(FAR struct file *filep, loff_t offset, int whence); 387 int (*getlabel)(FAR void *handle,FAR char* label); 388 int (*fallocate)(FAR struct file *filep, int mode, off_t offset, off_t len); 389 int (*fallocate64)(FAR struct file *filep, int mode, off64_t offset, off64_t len); 390 int (*truncate64)(FAR struct file *filep, off64_t length); 391 int (*fscheck)(FAR struct inode *mountpt, FAR const char *relpath, 392 FAR struct fs_dirent_s *dir); 393 #endif 394 }; 395 #endif /* CONFIG_DISABLE_MOUNTPOINT */ 396 397 /* Named OS resources are also maintained by the VFS. This includes: 398 * 399 * - Named semaphores: sem_open(), sem_close(), and sem_unlink() 400 * - POSIX Message Queues: mq_open() and mq_close() 401 * - Shared memory: shm_open() and shm_unlink(); 402 * 403 * These are a special case in that they do not follow quite the same 404 * pattern as the other file system types in that they have operations. 405 */ 406 407 /* These are the various kinds of operations that can be associated with 408 * an inode. 409 */ 410 411 union inode_ops_u 412 { 413 #ifdef CONFIG_VFS_OPERATION_EXTEND 414 FAR const struct file_operations_vfs *i_ops; /* Driver operations for inode */ 415 #else 416 FAR const struct file_operations *i_ops; /* Driver operations for inode */ 417 #endif 418 #ifndef CONFIG_DISABLE_MOUNTPOINT 419 FAR const struct block_operations *i_bops; /* Block driver operations */ 420 #ifndef CONFIG_VFS_MTD_DISABLE 421 FAR struct mtd_dev_s *i_mtd; /* MTD device driver */ 422 #endif 423 FAR const struct mountpt_operations *i_mops; /* Operations on a mountpoint */ 424 #endif 425 #ifdef CONFIG_FS_NAMED_SEMAPHORES 426 FAR struct nsem_inode_s *i_nsem; /* Named semaphore */ 427 #endif 428 #ifdef CONFIG_PSEUDOFS_SOFTLINKS 429 FAR char *i_link; /* Full path to link target */ 430 #endif 431 }; 432 433 /* This structure represents one inode in the NuttX pseudo-file system */ 434 435 struct inode 436 { 437 FAR struct inode *i_parent; /* Link to parent level inode */ 438 FAR struct inode *i_peer; /* Link to same level inode */ 439 FAR struct inode *i_child; /* Link to lower level inode */ 440 int16_t i_crefs; /* References to inode */ 441 uint16_t i_flags; /* Flags for inode */ 442 union inode_ops_u u; /* Inode operations */ 443 #ifdef CONFIG_PSEUDOFS_ATTRIBUTES 444 mode_t i_mode; /* Access mode flags */ 445 uid_t i_owner; /* Owner */ 446 gid_t i_group; /* Group */ 447 struct timespec i_atime; /* Time of last access */ 448 struct timespec i_mtime; /* Time of last modification */ 449 struct timespec i_ctime; /* Time of last status change */ 450 #endif 451 FAR void *i_private; /* Per inode driver private data */ 452 #ifdef CONFIG_VFS_MOUNT_STATUS_ENABLE 453 unsigned long mountflags; /* Flags for mount */ 454 int32_t e_status; /* Status for mount */ 455 #endif 456 char i_name[1]; /* Name of inode (variable) */ 457 }; 458 459 #define FSNODE_SIZE(n) (sizeof(struct inode) + (n)) 460 461 /* This is the underlying representation of an open file. A file 462 * descriptor is an index into an array of such types. The type associates 463 * the file descriptor to the file state and to a set of inode operations. 464 */ 465 466 struct file 467 { 468 int f_oflags; /* Open mode flags */ 469 #ifdef CONFIG_VFS_64BIT_ACCESS 470 loff_t f_pos; /* File position */ 471 #else 472 off_t f_pos; /* File position */ 473 #endif 474 FAR struct inode *f_inode; /* Driver or file system interface */ 475 FAR void *f_priv; /* Per file driver private data */ 476 #ifdef CONFIG_VFS_FULLPATH_ACQUIRE 477 char *f_path; /* File fullpath */ 478 const char *f_relpath; /* realpath */ 479 #endif 480 }; 481 482 /* This defines a two layer array of files indexed by the file descriptor. 483 * Each row of this array is fixed size: CONFIG_NFILE_DESCRIPTORS_PER_BLOCK. 484 * You can get file instance in filelist by the follow methods: 485 * (file descriptor / CONFIG_NFILE_DESCRIPTORS_PER_BLOCK) as row index and 486 * (file descriptor % CONFIG_NFILE_DESCRIPTORS_PER_BLOCK) as column index. 487 */ 488 489 struct filelist 490 { 491 sem_t fl_sem; /* Manage access to the file list */ 492 uint8_t fl_rows; /* The number of rows of fl_files array */ 493 FAR struct file **fl_files; /* The pointer of two layer file descriptors array */ 494 }; 495 #ifdef CONFIG_VFS_FILELIST_EXTERN 496 extern struct filelist tg_filelist; 497 #endif 498 /* The following structure defines the list of files used for standard C I/O. 499 * Note that NuttX can support the standard C APIs with or without buffering 500 * 501 * When buffering is used, the following describes the usage of the I/O 502 * buffer. 503 * The buffer can be used for reading or writing -- but not both at the same 504 * time. 505 * An fflush is implied between each change in direction of access. 506 * 507 * The field fs_bufread determines whether the buffer is being used for 508 * reading or for writing as follows: 509 * 510 * BUFFER 511 * +----------------------+ <- fs_bufstart Points to the beginning of 512 * | | the buffer. 513 * | WR: Buffered data | WR: Start of buffered write 514 * | | data. 515 * | RD: Already read | RD: Start of already read 516 * | | data. 517 * +----------------------+ 518 * | WR: Available buffer | <- fs_bufpos Points to next byte: 519 * | RD: Read-ahead data | WR: End+1 of buffered write 520 * | | data. 521 * | | RD: Points to next char to 522 * | | return 523 * +----------------------+ 524 * | WR: Available | <- fs_bufread Top+1 of buffered read data 525 * | RD: Available | WR: bufstart buffer used for 526 * | | writing. 527 * | | RD: Pointer to last buffered 528 * | | read char+1 529 * +----------------------+ 530 * <- fs_bufend Points to the end of the 531 * buffer+1 532 */ 533 534 #ifdef CONFIG_FILE_STREAM 535 struct file_struct 536 { 537 FAR struct file_struct *fs_next; /* Pointer to next file stream */ 538 int fs_fd; /* File descriptor associated with stream */ 539 #ifndef CONFIG_STDIO_DISABLE_BUFFERING 540 sem_t fs_sem; /* For thread safety */ 541 pid_t fs_holder; /* Holder of sem */ 542 int fs_counts; /* Number of times sem is held */ 543 FAR unsigned char *fs_bufstart; /* Pointer to start of buffer */ 544 FAR unsigned char *fs_bufend; /* Pointer to 1 past end of buffer */ 545 FAR unsigned char *fs_bufpos; /* Current position in buffer */ 546 FAR unsigned char *fs_bufread; /* Pointer to 1 past last buffered read char. */ 547 # if CONFIG_STDIO_BUFFER_SIZE > 0 548 unsigned char fs_buffer[CONFIG_STDIO_BUFFER_SIZE]; 549 # endif 550 #endif 551 uint16_t fs_oflags; /* Open mode flags */ 552 uint8_t fs_flags; /* Stream flags */ 553 #if CONFIG_NUNGET_CHARS > 0 554 uint8_t fs_nungotten; /* The number of characters buffered for ungetc */ 555 unsigned char fs_ungotten[CONFIG_NUNGET_CHARS]; 556 #endif 557 }; 558 559 struct streamlist 560 { 561 sem_t sl_sem; /* For thread safety */ 562 struct file_struct sl_std[3]; 563 FAR struct file_struct *sl_head; 564 FAR struct file_struct *sl_tail; 565 }; 566 #endif /* CONFIG_FILE_STREAM */ 567 568 /**************************************************************************** 569 * Public Function Prototypes 570 ****************************************************************************/ 571 572 #undef EXTERN 573 #if defined(__cplusplus) 574 #define EXTERN extern "C" 575 extern "C" 576 { 577 #else 578 #define EXTERN extern 579 #endif 580 581 #ifndef CONFIG_DISABLE_MOUNTPOINT 582 struct statfs; /* Forward reference */ 583 typedef int (*foreach_mountpoint_t)(FAR const char *mountpoint, 584 FAR struct statfs *statbuf, 585 FAR void *arg); 586 #endif 587 588 /**************************************************************************** 589 * Name: foreach_mountpoint 590 * 591 * Description: 592 * Visit each mountpoint in the pseudo-file system 593 * 594 * Input Parameters: 595 * handler - foreach_mountpoint_t operation function when find a mount point 596 * arg - The private data 597 * 598 * Returned Value: 599 * Zero is returned on success; a negated value is returned on any failure. 600 ****************************************************************************/ 601 602 #ifndef CONFIG_DISABLE_MOUNTPOINT 603 int foreach_mountpoint(foreach_mountpoint_t handler, FAR void *arg); 604 #endif 605 606 /**************************************************************************** 607 * Name: find_blockdriver 608 * 609 * Description: 610 * Return the inode of the block driver specified by 'pathname' 611 * 612 * Input Parameters: 613 * pathname - The full path to the block driver to be located 614 * mountflags - If MS_RDONLY is not set, then driver must support write 615 * operations (see include/sys/mount.h) 616 * ppinode - Address of the location to return the inode reference 617 * 618 * Returned Value: 619 * Returns zero on success or a negated errno on failure: 620 * 621 * EINVAL - pathname or ppinode is NULL. 622 * ENOENT - No block driver of this name is registered 623 * ENOTBLK - The inode associated with the pathname is not a block driver 624 * EACCESS - The MS_RDONLY option was not set but this driver does not 625 * support write access 626 * 627 ****************************************************************************/ 628 629 #if CONFIG_NFILE_DESCRIPTORS > 0 630 int find_blockdriver(FAR const char *pathname, int mountflags, 631 FAR struct inode **ppinode); 632 #endif 633 634 /**************************************************************************** 635 * Name: fs_initialize 636 * 637 * Description: 638 * This is called from the OS initialization logic to configure the file 639 * system. 640 * 641 ****************************************************************************/ 642 643 void fs_initialize(void); 644 645 /**************************************************************************** 646 * Name: register_driver 647 * 648 * Description: 649 * Register a character driver inode the pseudo file system. 650 * 651 * Input Parameters: 652 * path - The path to the inode to create 653 * fops - The file operations structure 654 * mode - Access privileges 655 * priv - Private, user data that will be associated with the inode. 656 * 657 * Returned Value: 658 * Zero on success (with the inode point in 'inode'); A negated errno 659 * value is returned on a failure (all error values returned by 660 * inode_reserve): 661 * 662 * EINVAL - 'path' is invalid for this operation 663 * EEXIST - An inode already exists at 'path' 664 * ENOMEM - Failed to allocate in-memory resources for the operation 665 * 666 ****************************************************************************/ 667 668 #ifdef CONFIG_VFS_OPERATION_EXTEND 669 int register_driver(FAR const char *path, 670 FAR const struct file_operations_vfs *fops, mode_t mode, 671 FAR void *priv); 672 #else 673 int register_driver(FAR const char *path, 674 FAR const struct file_operations *fops, mode_t mode, 675 FAR void *priv); 676 #endif 677 /**************************************************************************** 678 * Name: register_blockdriver 679 * 680 * Description: 681 * Register a block driver inode the pseudo file system. 682 * 683 * Input Parameters: 684 * path - The path to the inode to create 685 * bops - The block driver operations structure 686 * mode - Access privileges 687 * priv - Private, user data that will be associated with the inode. 688 * 689 * Returned Value: 690 * Zero on success (with the inode point in 'inode'); A negated errno 691 * value is returned on a failure (all error values returned by 692 * inode_reserve): 693 * 694 * EINVAL - 'path' is invalid for this operation 695 * EEXIST - An inode already exists at 'path' 696 * ENOMEM - Failed to allocate in-memory resources for the operation 697 * 698 ****************************************************************************/ 699 700 #ifndef CONFIG_DISABLE_MOUNTPOINT 701 int register_blockdriver(FAR const char *path, 702 FAR const struct block_operations *bops, 703 mode_t mode, FAR void *priv); 704 #endif 705 706 /**************************************************************************** 707 * Name: register_blockpartition 708 * 709 * Description: 710 * Register a block partition driver inode the pseudo file system. 711 * 712 * Input Parameters: 713 * partition - The path to the partition inode 714 * parent - The path to the parent inode 715 * firstsector - The offset in sectors to the partition 716 * nsectors - The number of sectors in the partition 717 * 718 * Returned Value: 719 * Zero on success (with the inode point in 'inode'); A negated errno 720 * value is returned on a failure (all error values returned by 721 * inode_reserve): 722 * 723 * EINVAL - 'path' is invalid for this operation 724 * EEXIST - An inode already exists at 'path' 725 * ENOMEM - Failed to allocate in-memory resources for the operation 726 * 727 ****************************************************************************/ 728 729 #ifndef CONFIG_DISABLE_MOUNTPOINT 730 int register_blockpartition(FAR const char *partition, 731 mode_t mode, FAR const char *parent, 732 off_t firstsector, off_t nsectors); 733 #endif 734 735 /**************************************************************************** 736 * Name: unregister_driver 737 * 738 * Description: 739 * Remove the character driver inode at 'path' from the pseudo-file system 740 * 741 ****************************************************************************/ 742 743 int unregister_driver(FAR const char *path); 744 745 /**************************************************************************** 746 * Name: unregister_blockdriver 747 * 748 * Description: 749 * Remove the block driver inode at 'path' from the pseudo-file system 750 * 751 ****************************************************************************/ 752 753 int unregister_blockdriver(FAR const char *path); 754 755 /**************************************************************************** 756 * Name: register_mtddriver 757 * 758 * Description: 759 * Register an MTD driver inode the pseudo file system. 760 * 761 * Input Parameters: 762 * path - The path to the inode to create 763 * mtd - The MTD driver structure 764 * mode - inode privileges 765 * priv - Private, user data that will be associated with the inode. 766 * 767 * Returned Value: 768 * Zero on success (with the inode point in 'inode'); A negated errno 769 * value is returned on a failure (all error values returned by 770 * inode_reserve): 771 * 772 * EINVAL - 'path' is invalid for this operation 773 * EEXIST - An inode already exists at 'path' 774 * ENOMEM - Failed to allocate in-memory resources for the operation 775 * 776 ****************************************************************************/ 777 778 #ifdef CONFIG_MTD 779 int register_mtddriver(FAR const char *path, FAR struct mtd_dev_s *mtd, 780 mode_t mode, FAR void *priv); 781 #endif 782 783 /**************************************************************************** 784 * Name: register_mtdpartition 785 * 786 * Description: 787 * Register a mtd partition driver inode the pseudo file system. 788 * 789 * Input Parameters: 790 * partition - The path to the partition inode 791 * parent - The path to the parent inode 792 * firstblock - The offset in block to the partition 793 * nblocks - The number of block in the partition 794 * 795 * Returned Value: 796 * Zero on success (with the inode point in 'inode'); A negated errno 797 * value is returned on a failure (all error values returned by 798 * inode_reserve): 799 * 800 * EINVAL - 'path' is invalid for this operation 801 * EEXIST - An inode already exists at 'path' 802 * ENOMEM - Failed to allocate in-memory resources for the operation 803 * 804 ****************************************************************************/ 805 806 #ifdef CONFIG_MTD 807 int register_mtdpartition(FAR const char *partition, 808 mode_t mode, FAR const char *parent, 809 off_t firstblock, off_t nblocks); 810 #endif 811 812 /**************************************************************************** 813 * Name: unregister_mtddriver 814 * 815 * Description: 816 * Remove the named TMD driver inode at 'path' from the pseudo-file system 817 * 818 ****************************************************************************/ 819 820 #ifdef CONFIG_MTD 821 int unregister_mtddriver(FAR const char *path); 822 #endif 823 824 /**************************************************************************** 825 * Name: nx_mount 826 * 827 * Description: 828 * nx_mount() is similar to the standard 'mount' interface except that is 829 * not a cancellation point and it does not modify the errno variable. 830 * 831 * nx_mount() is an internal NuttX interface and should not be called from 832 * applications. 833 * 834 * Returned Value: 835 * Zero is returned on success; a negated value is returned on any failure. 836 * 837 ****************************************************************************/ 838 839 #ifndef CONFIG_DISABLE_MOUNTPOINT 840 int nx_mount(FAR const char *source, FAR const char *target, 841 FAR const char *filesystemtype, unsigned long mountflags, 842 FAR const void *data); 843 #endif 844 845 /**************************************************************************** 846 * Name: nx_umount2 847 * 848 * Description: 849 * nx_umount2() is similar to the standard 'umount2' interface except that 850 * is not a cancellation point and it does not modify the errno variable. 851 * 852 * nx_umount2() is an internal NuttX interface and should not be called 853 * from applications. 854 * 855 * Returned Value: 856 * Zero is returned on success; a negated value is returned on any failure. 857 * 858 ****************************************************************************/ 859 860 #ifndef CONFIG_DISABLE_MOUNTPOINT 861 #ifdef CONFIG_VFS_UNBIND_WITHOUT_FLAGS 862 int nx_umount2(FAR const char *target); 863 #else 864 int nx_umount2(FAR const char *target, unsigned int flags); 865 #endif 866 #endif 867 868 /**************************************************************************** 869 * Name: files_initlist 870 * 871 * Description: 872 * Initializes the list of files for a new task 873 * 874 ****************************************************************************/ 875 876 void files_initlist(FAR struct filelist *list); 877 878 /**************************************************************************** 879 * Name: files_releaselist 880 * 881 * Description: 882 * Release a reference to the file list 883 * 884 ****************************************************************************/ 885 886 void files_releaselist(FAR struct filelist *list); 887 888 /**************************************************************************** 889 * Name: files_duplist 890 * 891 * Description: 892 * Duplicate parent task's file descriptors. 893 * 894 * Returned Value: 895 * Zero (OK) is returned on success; a negated errno value is returned on 896 * any failure. 897 * 898 ****************************************************************************/ 899 900 int files_duplist(FAR struct filelist *plist, FAR struct filelist *clist); 901 902 /**************************************************************************** 903 * Name: file_dup 904 * 905 * Description: 906 * Equivalent to the standard dup() function except that it 907 * accepts a struct file instance instead of a file descriptor. 908 * 909 * Returned Value: 910 * Zero (OK) is returned on success; a negated errno value is returned on 911 * any failure. 912 * 913 ****************************************************************************/ 914 915 int file_dup(FAR struct file *filep, int minfd); 916 917 /**************************************************************************** 918 * Name: nx_dup 919 * 920 * Description: 921 * nx_dup() is similar to the standard 'dup' interface except that is 922 * not a cancellation point and it does not modify the errno variable. 923 * 924 * nx_dup() is an internal NuttX interface and should not be called from 925 * applications. 926 * 927 * Returned Value: 928 * The new file descriptor is returned on success; a negated errno value is 929 * returned on any failure. 930 * 931 ****************************************************************************/ 932 933 int nx_dup(int fd); 934 935 /**************************************************************************** 936 * Name: file_dup2 937 * 938 * Description: 939 * Assign an inode to a specific files structure. This is the heart of 940 * dup2. 941 * 942 * Equivalent to the non-standard dup2() function except that it 943 * accepts struct file instances instead of file descriptors. 944 * 945 * Returned Value: 946 * Zero (OK) is returned on success; a negated errno value is return on 947 * any failure. 948 * 949 ****************************************************************************/ 950 951 int file_dup2(FAR struct file *filep1, FAR struct file *filep2); 952 953 /**************************************************************************** 954 * Name: nx_dup2 955 * 956 * Description: 957 * nx_dup2() is similar to the standard 'dup2' interface except that is 958 * not a cancellation point and it does not modify the errno variable. 959 * 960 * nx_dup2() is an internal NuttX interface and should not be called from 961 * applications. 962 * 963 * Returned Value: 964 * fd2 is returned on success; a negated errno value is return on 965 * any failure. 966 * 967 ****************************************************************************/ 968 969 int nx_dup2(int fd1, int fd2); 970 971 /**************************************************************************** 972 * Name: file_open 973 * 974 * Description: 975 * file_open() is similar to the standard 'open' interface except that it 976 * returns an instance of 'struct file' rather than a file descriptor. It 977 * also is not a cancellation point and does not modify the errno variable. 978 * 979 * Input Parameters: 980 * filep - The caller provided location in which to return the 'struct 981 * file' instance. 982 * path - The full path to the file to be open. 983 * oflags - open flags 984 * ... - Variable number of arguments, may include 'mode_t mode' 985 * 986 * Returned Value: 987 * Zero (OK) is returned on success. On failure, a negated errno value is 988 * returned. 989 * 990 ****************************************************************************/ 991 992 int file_open(FAR struct file *filep, FAR const char *path, int oflags, ...); 993 994 /**************************************************************************** 995 * Name: nx_open 996 * 997 * Description: 998 * nx_open() is similar to the standard 'open' interface except that is is 999 * not a cancellation point and it does not modify the errno variable. 1000 * 1001 * nx_open() is an internal NuttX interface and should not be called 1002 * from applications. 1003 * 1004 * Returned Value: 1005 * The new file descriptor is returned on success; a negated errno value is 1006 * returned on any failure. 1007 * 1008 ****************************************************************************/ 1009 1010 int nx_open(FAR const char *path, int oflags, ...); 1011 1012 /**************************************************************************** 1013 * Name: fs_getfilep 1014 * 1015 * Description: 1016 * Given a file descriptor, return the corresponding instance of struct 1017 * file. NOTE that this function will currently fail if it is provided 1018 * with a socket descriptor. 1019 * 1020 * Input Parameters: 1021 * fd - The file descriptor 1022 * filep - The location to return the struct file instance 1023 * 1024 * Returned Value: 1025 * Zero (OK) is returned on success; a negated errno value is returned on 1026 * any failure. 1027 * 1028 ****************************************************************************/ 1029 1030 int fs_getfilep(int fd, FAR struct file **filep); 1031 1032 /**************************************************************************** 1033 * Name: file_close 1034 * 1035 * Description: 1036 * Close a file that was previously opened with file_open(). 1037 * 1038 * Input Parameters: 1039 * filep - A pointer to a user provided memory location containing the 1040 * open file data returned by file_open(). 1041 * 1042 * Returned Value: 1043 * Zero (OK) is returned on success; A negated errno value is returned on 1044 * any failure to indicate the nature of the failure. 1045 * 1046 ****************************************************************************/ 1047 #ifdef CONFIG_VFS_FILE_FORCE_RELEASE 1048 int file_close(FAR struct file *filep, bool force); 1049 #else 1050 int file_close(FAR struct file *filep); 1051 #endif 1052 /**************************************************************************** 1053 * Name: nx_close 1054 * 1055 * Description: 1056 * nx_close() is similar to the standard 'close' interface except that is 1057 * not a cancellation point and it does not modify the errno variable. 1058 * 1059 * nx_close() is an internal NuttX interface and should not be called from 1060 * applications. 1061 * 1062 * Returned Value: 1063 * The new file descriptor is returned on success; a negated errno value is 1064 * returned on any failure. 1065 * 1066 ****************************************************************************/ 1067 1068 int nx_close(int fd); 1069 1070 /**************************************************************************** 1071 * Name: open_blockdriver 1072 * 1073 * Description: 1074 * Return the inode of the block driver specified by 'pathname' 1075 * 1076 * Input Parameters: 1077 * pathname - the full path to the block driver to be opened 1078 * mountflags - if MS_RDONLY is not set, then driver must support write 1079 * operations (see include/sys/mount.h) 1080 * ppinode - address of the location to return the inode reference 1081 * 1082 * Returned Value: 1083 * Returns zero on success or a negated errno on failure: 1084 * 1085 * EINVAL - pathname or pinode is NULL 1086 * ENOENT - No block driver of this name is registered 1087 * ENOTBLK - The inode associated with the pathname is not a block driver 1088 * EACCESS - The MS_RDONLY option was not set but this driver does not 1089 * support write access 1090 * 1091 ****************************************************************************/ 1092 1093 int open_blockdriver(FAR const char *pathname, int mountflags, 1094 FAR struct inode **ppinode); 1095 1096 /**************************************************************************** 1097 * Name: close_blockdriver 1098 * 1099 * Description: 1100 * Call the close method and release the inode 1101 * 1102 * Input Parameters: 1103 * inode - reference to the inode of a block driver opened by 1104 * open_blockdriver 1105 * 1106 * Returned Value: 1107 * Returns zero on success or a negated errno on failure: 1108 * 1109 * EINVAL - inode is NULL 1110 * ENOTBLK - The inode is not a block driver 1111 * 1112 ****************************************************************************/ 1113 1114 int close_blockdriver(FAR struct inode *inode); 1115 1116 /**************************************************************************** 1117 * Name: fs_fdopen 1118 * 1119 * Description: 1120 * This function does the core operations for fopen and fdopen. It is 1121 * used by the OS to clone stdin, stdout, stderr 1122 * 1123 ****************************************************************************/ 1124 1125 #ifdef CONFIG_FILE_STREAM 1126 struct tcb_s; /* Forward reference */ 1127 int fs_fdopen(int fd, int oflags, FAR struct tcb_s *tcb, 1128 FAR struct file_struct **filep); 1129 #endif 1130 1131 /**************************************************************************** 1132 * Name: lib_flushall 1133 * 1134 * Description: 1135 * Called either (1) by the OS when a task exits, or (2) from fflush() 1136 * when a NULL stream argument is provided. 1137 * 1138 ****************************************************************************/ 1139 1140 #ifdef CONFIG_FILE_STREAM 1141 int lib_flushall(FAR struct streamlist *list); 1142 #endif 1143 1144 /**************************************************************************** 1145 * Name: file_read 1146 * 1147 * Description: 1148 * file_read() is an internal OS interface. It is functionally similar to 1149 * the standard read() interface except: 1150 * 1151 * - It does not modify the errno variable, 1152 * - It is not a cancellation point, 1153 * - It does not handle socket descriptors, and 1154 * - It accepts a file structure instance instead of file descriptor. 1155 * 1156 * Input Parameters: 1157 * filep - File structure instance 1158 * buf - User-provided to save the data 1159 * nbytes - The maximum size of the user-provided buffer 1160 * 1161 * Returned Value: 1162 * The positive non-zero number of bytes read on success, 0 on if an 1163 * end-of-file condition, or a negated errno value on any failure. 1164 * 1165 ****************************************************************************/ 1166 1167 ssize_t file_read(FAR struct file *filep, FAR void *buf, size_t nbytes); 1168 1169 /**************************************************************************** 1170 * Name: nx_read 1171 * 1172 * Description: 1173 * nx_read() is an internal OS interface. It is functionally similar to 1174 * the standard read() interface except: 1175 * 1176 * - It does not modify the errno variable, and 1177 * - It is not a cancellation point. 1178 * 1179 * Input Parameters: 1180 * fd - File descriptor to read from 1181 * buf - User-provided to save the data 1182 * nbytes - The maximum size of the user-provided buffer 1183 * 1184 * Returned Value: 1185 * The positive non-zero number of bytes read on success, 0 on if an 1186 * end-of-file condition, or a negated errno value on any failure. 1187 * 1188 ****************************************************************************/ 1189 1190 ssize_t nx_read(int fd, FAR void *buf, size_t nbytes); 1191 1192 /**************************************************************************** 1193 * Name: file_write 1194 * 1195 * Description: 1196 * Equivalent to the standard write() function except that is accepts a 1197 * struct file instance instead of a file descriptor. It is functionally 1198 * equivalent to write() except that in addition to the differences in 1199 * input parameters: 1200 * 1201 * - It does not modify the errno variable, 1202 * - It is not a cancellation point, and 1203 * - It does not handle socket descriptors. 1204 * 1205 * Input Parameters: 1206 * filep - Instance of struct file to use with the write 1207 * buf - Data to write 1208 * nbytes - Length of data to write 1209 * 1210 * Returned Value: 1211 * On success, the number of bytes written are returned (zero indicates 1212 * nothing was written). On any failure, a negated errno value is returned 1213 * (see comments withwrite() for a description of the appropriate errno 1214 * values). 1215 * 1216 ****************************************************************************/ 1217 1218 ssize_t file_write(FAR struct file *filep, FAR const void *buf, 1219 size_t nbytes); 1220 1221 /**************************************************************************** 1222 * Name: nx_write 1223 * 1224 * Description: 1225 * nx_write() writes up to nbytes bytes to the file referenced by the file 1226 * descriptor fd from the buffer starting at buf. nx_write() is an 1227 * internal OS function. It is functionally equivalent to write() except 1228 * that: 1229 * 1230 * - It does not modify the errno variable, and 1231 * - It is not a cancellation point. 1232 * 1233 * Input Parameters: 1234 * fd - file descriptor (or socket descriptor) to write to 1235 * buf - Data to write 1236 * nbytes - Length of data to write 1237 * 1238 * Returned Value: 1239 * On success, the number of bytes written are returned (zero indicates 1240 * nothing was written). On any failure, a negated errno value is returned 1241 * (see comments with write() for a description of the appropriate errno 1242 * values). 1243 * 1244 ****************************************************************************/ 1245 1246 ssize_t nx_write(int fd, FAR const void *buf, size_t nbytes); 1247 1248 /**************************************************************************** 1249 * Name: file_pread 1250 * 1251 * Description: 1252 * Equivalent to the standard pread function except that is accepts a 1253 * struct file instance instead of a file descriptor. Currently used 1254 * only by aio_read(); 1255 * 1256 ****************************************************************************/ 1257 1258 ssize_t file_pread(FAR struct file *filep, FAR void *buf, size_t nbytes, 1259 off_t offset); 1260 1261 /**************************************************************************** 1262 * Name: file_pwrite 1263 * 1264 * Description: 1265 * Equivalent to the standard pwrite function except that is accepts a 1266 * struct file instance instead of a file descriptor. Currently used 1267 * only by aio_write(); 1268 * 1269 ****************************************************************************/ 1270 1271 ssize_t file_pwrite(FAR struct file *filep, FAR const void *buf, 1272 size_t nbytes, off_t offset); 1273 1274 /**************************************************************************** 1275 * Name: file_sendfile 1276 * 1277 * Description: 1278 * Equivalent to the standard sendfile function except that is accepts a 1279 * struct file instance instead of a file descriptor. 1280 * 1281 ****************************************************************************/ 1282 1283 ssize_t file_sendfile(FAR struct file *outfile, FAR struct file *infile, 1284 off_t *offset, size_t count); 1285 1286 /**************************************************************************** 1287 * Name: file_seek 1288 * 1289 * Description: 1290 * Equivalent to the standard lseek() function except that is accepts a 1291 * struct file instance instead of a file descriptor. Currently used 1292 * only by net_sendfile() 1293 * 1294 ****************************************************************************/ 1295 1296 off_t file_seek(FAR struct file *filep, off_t offset, int whence); 1297 1298 /**************************************************************************** 1299 * Name: nx_seek 1300 * 1301 * Description: 1302 * nx_seek() function repositions the offset of the open file associated 1303 * with the file descriptor fd to the argument 'offset' according to the 1304 * directive 'whence'. nx_seek() is an internal OS function. It is 1305 * functionally equivalent to lseek() except that: 1306 * 1307 * - It does not modify the errno variable, and 1308 * - It is not a cancellation point. 1309 * 1310 ****************************************************************************/ 1311 1312 off_t nx_seek(int fd, off_t offset, int whence); 1313 1314 /**************************************************************************** 1315 * Name: file_fsync 1316 * 1317 * Description: 1318 * Equivalent to the standard fsync() function except that is accepts a 1319 * struct file instance instead of a file descriptor and it does not set 1320 * the errno variable. 1321 * 1322 ****************************************************************************/ 1323 1324 #ifndef CONFIG_DISABLE_MOUNTPOINT 1325 int file_fsync(FAR struct file *filep); 1326 #endif 1327 1328 /**************************************************************************** 1329 * Name: file_truncate 1330 * 1331 * Description: 1332 * Equivalent to the standard ftruncate() function except that is accepts 1333 * a struct file instance instead of a file descriptor and it does not set 1334 * the errno variable. 1335 * 1336 ****************************************************************************/ 1337 1338 #ifndef CONFIG_DISABLE_MOUNTPOINT 1339 int file_truncate(FAR struct file *filep, off_t length); 1340 #endif 1341 1342 /**************************************************************************** 1343 * Name: file_mmap 1344 * 1345 * Description: 1346 * Equivalent to the standard mmap() function except that is accepts 1347 * a struct file instance instead of a file descriptor and it does not set 1348 * the errno variable. 1349 * 1350 ****************************************************************************/ 1351 1352 int file_mmap(FAR struct file *filep, FAR void *start, size_t length, 1353 int prot, int flags, off_t offset, FAR void **mapped); 1354 1355 /**************************************************************************** 1356 * Name: file_mummap 1357 * 1358 * Description: 1359 * Equivalent to the standard mummap() function except it does not set 1360 * the errno variable. 1361 * 1362 ****************************************************************************/ 1363 1364 int file_munmap(FAR void *start, size_t length); 1365 1366 /**************************************************************************** 1367 * Name: file_ioctl 1368 * 1369 * Description: 1370 * Perform device specific operations. 1371 * 1372 * Input Parameters: 1373 * file File structure instance 1374 * req The ioctl command 1375 * ap The argument of the ioctl cmd 1376 * 1377 * Returned Value: 1378 * Returns a non-negative number on success; A negated errno value is 1379 * returned on any failure (see comments ioctl() for a list of appropriate 1380 * errno values). 1381 * 1382 ****************************************************************************/ 1383 1384 int file_ioctl(FAR struct file *filep, int req, ...); 1385 1386 /**************************************************************************** 1387 * Name: nx_ioctl 1388 * 1389 * Description: 1390 * nx_ioctl() is similar to the standard 'ioctl' interface except that is 1391 * not a cancellation point and it does not modify the errno variable. 1392 * 1393 * nx_ioctl() is an internal NuttX interface and should not be called from 1394 * applications. 1395 * 1396 * Returned Value: 1397 * Returns a non-negative number on success; A negated errno value is 1398 * returned on any failure (see comments ioctl() for a list of appropriate 1399 * errno values). 1400 * 1401 ****************************************************************************/ 1402 1403 int nx_ioctl(int fd, int req, ...); 1404 1405 /**************************************************************************** 1406 * Name: file_fcntl 1407 * 1408 * Description: 1409 * Similar to the standard fcntl function except that is accepts a struct 1410 * struct file instance instead of a file descriptor. 1411 * 1412 * Input Parameters: 1413 * filep - Instance for struct file for the opened file. 1414 * cmd - Identifies the operation to be performed. Command specific 1415 * arguments may follow. 1416 * 1417 * Returned Value: 1418 * The nature of the return value depends on the command. Non-negative 1419 * values indicate success. Failures are reported as negated errno 1420 * values. 1421 * 1422 ****************************************************************************/ 1423 1424 int file_fcntl(FAR struct file *filep, int cmd, ...); 1425 1426 /**************************************************************************** 1427 * Name: nx_fcntl 1428 * 1429 * Description: 1430 * nx_fcntl() is similar to the standard 'fcntl' interface except that is 1431 * not a cancellation point and it does not modify the errno variable. 1432 * 1433 * nx_fcntl() is an internal NuttX interface and should not be called 1434 * from applications. 1435 * 1436 * Returned Value: 1437 * Returns a non-negative number on success; A negated errno value is 1438 * returned on any failure (see comments fcntl() for a list of appropriate 1439 * errno values). 1440 * 1441 ****************************************************************************/ 1442 1443 int nx_fcntl(int fd, int cmd, ...); 1444 1445 /**************************************************************************** 1446 * Name: file_poll 1447 * 1448 * Description: 1449 * Low-level poll operation based on struct file. This is used both to (1) 1450 * support detached file, and also (2) by poll_fdsetup() to perform all 1451 * normal operations on file descriptors. 1452 * 1453 * Input Parameters: 1454 * file File structure instance 1455 * fds - The structure describing the events to be monitored, OR NULL if 1456 * this is a request to stop monitoring events. 1457 * setup - true: Setup up the poll; false: Teardown the poll 1458 * 1459 * Returned Value: 1460 * 0: Success; Negated errno on failure 1461 * 1462 ****************************************************************************/ 1463 #ifndef CONFIG_VFS_POLL_DISABLE 1464 #ifndef CONFIG_VFS_POLL_WITHOUT_SETUP 1465 int file_poll(FAR struct file *filep, FAR struct pollfd *fds, bool setup); 1466 #endif 1467 #endif 1468 /**************************************************************************** 1469 * Name: nx_poll 1470 * 1471 * Description: 1472 * nx_poll() is similar to the standard 'poll' interface except that is 1473 * not a cancellation point and it does not modify the errno variable. 1474 * 1475 * nx_poll() is an internal NuttX interface and should not be called from 1476 * applications. 1477 * 1478 * Returned Value: 1479 * Zero is returned on success; a negated value is returned on any failure. 1480 * 1481 ****************************************************************************/ 1482 #ifndef CONFIG_VFS_POLL_DISABLE 1483 int nx_poll(FAR struct pollfd *fds, unsigned int nfds, int timeout); 1484 #endif 1485 /**************************************************************************** 1486 * Name: file_fstat 1487 * 1488 * Description: 1489 * file_fstat() is an internal OS interface. It is functionally similar to 1490 * the standard fstat() interface except: 1491 * 1492 * - It does not modify the errno variable, 1493 * - It is not a cancellation point, 1494 * - It does not handle socket descriptors, and 1495 * - It accepts a file structure instance instead of file descriptor. 1496 * 1497 * Input Parameters: 1498 * filep - File structure instance 1499 * buf - The caller provide location in which to return information 1500 * about the open file. 1501 * 1502 * Returned Value: 1503 * Upon successful completion, 0 shall be returned. Otherwise, -1 shall be 1504 * returned and errno set to indicate the error. 1505 * 1506 ****************************************************************************/ 1507 1508 int file_fstat(FAR struct file *filep, FAR struct stat *buf); 1509 1510 /**************************************************************************** 1511 * Name: nx_stat 1512 * 1513 * Description: 1514 * nx_stat() is similar to the standard 'stat' interface except that is 1515 * not a cancellation point and it does not modify the errno variable. 1516 * 1517 * nx_stat() is an internal NuttX interface and should not be called from 1518 * applications. 1519 * 1520 * Returned Value: 1521 * Zero is returned on success; a negated value is returned on any failure. 1522 * 1523 ****************************************************************************/ 1524 1525 int nx_stat(FAR const char *path, FAR struct stat *buf, int resolve); 1526 1527 /**************************************************************************** 1528 * Name: file_fchstat 1529 * 1530 * Description: 1531 * file_fchstat() is an internal OS interface. It is functionally similar 1532 * to the combination of fchmod/fchown/futimens standard interface except: 1533 * 1534 * - It does not modify the errno variable, 1535 * - It is not a cancellation point, 1536 * - It does not handle socket descriptors, and 1537 * - It accepts a file structure instance instead of file descriptor. 1538 * 1539 * Input Parameters: 1540 * filep - File structure instance 1541 * buf - The stat to be modified 1542 * flags - The vaild field in buf 1543 * 1544 * Returned Value: 1545 * Upon successful completion, 0 shall be returned. Otherwise, the 1546 * negative errno shall be returned to indicate the error. 1547 * 1548 ****************************************************************************/ 1549 1550 int file_fchstat(FAR struct file *filep, FAR struct stat *buf, int flags); 1551 1552 /**************************************************************************** 1553 * Name: nx_unlink 1554 * 1555 * Description: 1556 * nx_unlink() is similar to the standard 'unlink' interface except that 1557 * is not a cancellation point and it does not modify the errno variable. 1558 * 1559 * nx_unlink() is an internal NuttX interface and should not be called 1560 * from applications. 1561 * 1562 * Returned Value: 1563 * Zero is returned on success; a negated value is returned on any failure. 1564 * 1565 ****************************************************************************/ 1566 1567 int nx_unlink(FAR const char *pathname); 1568 1569 /**************************************************************************** 1570 * Name: nx_pipe 1571 * 1572 * Description: 1573 * nx_pipe() creates a pair of file descriptors, pointing to a pipe inode, 1574 * and places them in the array pointed to by 'fd'. fd[0] is for reading, 1575 * fd[1] is for writing. 1576 * 1577 * NOTE: nx_pipe is a special, non-standard, NuttX-only interface. Since 1578 * the NuttX FIFOs are based in in-memory, circular buffers, the ability 1579 * to control the size of those buffers is critical for system tuning. 1580 * 1581 * Input Parameters: 1582 * fd[2] - The user provided array in which to catch the pipe file 1583 * descriptors 1584 * bufsize - The size of the in-memory, circular buffer in bytes. 1585 * flags - The file status flags. 1586 * 1587 * Returned Value: 1588 * 0 is returned on success; a negated errno value is returned on a 1589 * failure. 1590 * 1591 ****************************************************************************/ 1592 1593 #if defined(CONFIG_PIPES) && CONFIG_DEV_PIPE_SIZE > 0 1594 int file_pipe(FAR struct file *filep[2], size_t bufsize, int flags); 1595 int nx_pipe(int fd[2], size_t bufsize, int flags); 1596 #endif 1597 1598 /**************************************************************************** 1599 * Name: nx_mkfifo 1600 * 1601 * Description: 1602 * nx_mkfifo() makes a FIFO device driver file with name 'pathname.' Unlike 1603 * Linux, a NuttX FIFO is not a special file type but simply a device 1604 * driver instance. 'mode' specifies the FIFO's permissions. 1605 * 1606 * Once the FIFO has been created by nx_mkfifo(), any thread can open it 1607 * for reading or writing, in the same way as an ordinary file. However, it 1608 * must have been opened from both reading and writing before input or 1609 * output can be performed. This FIFO implementation will block all 1610 * attempts to open a FIFO read-only until at least one thread has opened 1611 * the FIFO for writing. 1612 * 1613 * If all threads that write to the FIFO have closed, subsequent calls to 1614 * read() on the FIFO will return 0 (end-of-file). 1615 * 1616 * NOTE: nx_mkfifo is a special, non-standard, NuttX-only interface. Since 1617 * the NuttX FIFOs are based in in-memory, circular buffers, the ability 1618 * to control the size of those buffers is critical for system tuning. 1619 * 1620 * Input Parameters: 1621 * pathname - The full path to the FIFO instance to attach to or to create 1622 * (if not already created). 1623 * mode - Ignored for now 1624 * bufsize - The size of the in-memory, circular buffer in bytes. 1625 * 1626 * Returned Value: 1627 * 0 is returned on success; a negated errno value is returned on a 1628 * failure. 1629 * 1630 ****************************************************************************/ 1631 1632 #if defined(CONFIG_PIPES) && CONFIG_DEV_FIFO_SIZE > 0 1633 int nx_mkfifo(FAR const char *pathname, mode_t mode, size_t bufsize); 1634 #endif 1635 1636 #ifdef CONFIG_VFS_FULLPATH_ACQUIRE 1637 int vfs_acquire_fullpath(const char *path, char **fullpath); 1638 #endif 1639 1640 #ifdef CONFIG_VFS_FILELIST_ALLOC 1641 void vfs_files_initlist(FAR struct filelist *list); 1642 #endif 1643 1644 #ifdef CONFIG_VFS_MINFD_VERIFY 1645 void vfs_minfd_verify(int *minfd); 1646 #endif 1647 1648 #ifdef CONFIG_FILES_ALLOCATE_WITH_FILEP 1649 void vfs_filep_path_set(FAR struct file *files, struct file *filep); 1650 #endif 1651 1652 #ifdef CONFIG_VFS_SOCKET 1653 int vfs_close_socket(int fd); 1654 int vfs_vfcntl_socket(int fd, int cmd, va_list ap); 1655 int vfs_ioctl_socket(int fd, int req, va_list ap); 1656 ssize_t vfs_read_socket(int fd, void *buf, size_t nbytes); 1657 ssize_t vfs_write_socket(int fd, const void *buf, size_t nbytes); 1658 #endif 1659 1660 #ifdef CONFIG_VFS_CONSOLE 1661 ssize_t vfs_console_update_fd(int *fd); 1662 #endif 1663 1664 #ifdef CONFIG_VFS_INODE_PATH_VERIFY 1665 int vfs_inode_path_verify(const char *path); 1666 #endif 1667 1668 #ifdef CONFIG_VFS_SEEK_VERIFY 1669 int vfs_seek_verify(struct inode *inode, int whence); 1670 #endif 1671 1672 #ifdef CONFIG_VFS_DISK_STATUS_VERIFY 1673 bool vfs_disk_is_inuse(struct inode *inode); 1674 #endif 1675 1676 #ifdef CONFIG_VFS_OPTIMIZATION_ALLOC_POLLFD 1677 int vfs_optimization_alloc_pollfd(struct pollfd **pollset, struct pollfd *pfd, int npfds, int *pfd_alloc_flag); 1678 void vfs_optimization_free_pollfd(struct pollfd *pollset, int pfd_alloc_flag); 1679 int vfs_select_wait(FAR struct timeval *timeout); 1680 #endif 1681 1682 #ifdef CONFIG_VFS_INODE_UBIND 1683 int vfs_mountpt_inode_unbind( FAR struct inode **mountpt_inode, FAR struct inode **blkdrvr_inode); 1684 #endif 1685 1686 #ifdef CONFIG_VFS_RMDIR_RELPATH_VERIFY 1687 int vfs_rmdir_relpath_verify(const char *relpath); 1688 #endif 1689 1690 #undef EXTERN 1691 #if defined(__cplusplus) 1692 } 1693 #endif 1694 1695 #endif /* __INCLUDE_NUTTX_FS_FS_H */ 1696