1 /** 2 * @file vfs.h 3 * @copyright Copyright (C) 2015-2018 Alibaba Group Holding Limited 4 */ 5 6 #ifndef AOS_VFS_H 7 #define AOS_VFS_H 8 9 #include <stddef.h> 10 #include <stdint.h> 11 #include <unistd.h> 12 #include <time.h> 13 14 #include <sys/stat.h> 15 #include <sys/types.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /** @addtogroup aos_vfs VFS 22 * VFS AOS API. 23 * 24 * @{ 25 */ 26 27 /** 28 * @brief aos_utimbuf structure describes the filesystem inode's 29 * last access time and last modification time. 30 */ 31 struct aos_utimbuf { 32 time_t actime; /**< time of last access */ 33 time_t modtime; /**< time of last modification */ 34 }; 35 36 struct aos_statfs { 37 long f_type; /**< fs type */ 38 long f_bsize; /**< optimized transport block size */ 39 long f_blocks; /**< total blocks */ 40 long f_bfree; /**< available blocks */ 41 long f_bavail; /**< number of blocks that non-super users can acquire */ 42 long f_files; /**< total number of file nodes */ 43 long f_ffree; /**< available file nodes */ 44 long f_fsid; /**< fs id */ 45 long f_namelen; /**< max file name length */ 46 }; 47 48 struct aos_stat { 49 uint16_t st_mode; /**< mode of file */ 50 uint32_t st_size; /**< bytes of file */ 51 time_t st_actime; /**< time of last access */ 52 time_t st_modtime; /**< time of last modification */ 53 }; 54 55 typedef struct { 56 int32_t d_ino; /**< file number */ 57 uint8_t d_type; /**< type of file */ 58 char d_name[]; /**< file name */ 59 } aos_dirent_t; 60 61 typedef struct { 62 int32_t dd_vfs_fd; /**< file index in vfs */ 63 int32_t dd_rsv; /**< Reserved */ 64 } aos_dir_t; 65 66 typedef const struct file_ops file_ops_t; 67 typedef const struct fs_ops fs_ops_t; 68 69 union inode_ops_t { 70 const file_ops_t *i_ops; /**< char driver operations */ 71 const fs_ops_t *i_fops; /**< FS operations */ 72 }; 73 74 typedef struct { 75 union inode_ops_t ops; /**< inode operations */ 76 void *i_arg; /**< per inode private data */ 77 char *i_name; /**< name of inode */ 78 int i_flags; /**< flags for inode */ 79 uint8_t type; /**< type for inode */ 80 uint8_t refs; /**< refs for inode */ 81 } inode_t; 82 83 typedef struct { 84 inode_t *node; /**< node for file */ 85 void *f_arg; /**< f_arg for file */ 86 size_t offset; /**< offset for file */ 87 } file_t; 88 89 typedef void (*poll_notify_t)(void *pollfd, void *arg); 90 91 /** 92 * @brief file_ops structure defines the file operation handles 93 */ 94 struct file_ops { 95 int (*open)(inode_t *node, file_t *fp); 96 int (*close)(file_t *fp); 97 ssize_t (*read)(file_t *fp, void *buf, size_t nbytes); 98 ssize_t (*write)(file_t *fp, const void *buf, size_t nbytes); 99 int (*ioctl)(file_t *fp, int cmd, unsigned long arg); 100 int (*poll)(file_t *fp, int flag, poll_notify_t notify, void *fd, void *arg); 101 uint32_t (*lseek)(file_t *fp, int64_t off, int32_t whence); 102 int (*stat)(file_t *fp, const char *path, struct aos_stat *st); 103 void* (*mmap)(file_t *fp, size_t len); 104 int (*access)(file_t *fp, const char *path, int amode); 105 }; 106 107 /** 108 * @brief fs_ops structures defines the filesystem operation handles 109 */ 110 struct fs_ops { 111 int (*open)(file_t *fp, const char *path, int flags); 112 int (*close)(file_t *fp); 113 ssize_t (*read)(file_t *fp, char *buf, size_t len); 114 ssize_t (*write)(file_t *fp, const char *buf, size_t len); 115 off_t (*lseek)(file_t *fp, off_t off, int whence); 116 int (*sync)(file_t *fp); 117 int (*stat)(file_t *fp, const char *path, struct aos_stat *st); 118 int (*fstat)(file_t *fp, struct aos_stat *st); 119 int (*link)(file_t *fp, const char *path1, const char *path2); 120 int (*unlink)(file_t *fp, const char *path); 121 int (*remove)(file_t *fp, const char *path); 122 int (*rename)(file_t *fp, const char *oldpath, const char *newpath); 123 aos_dir_t *(*opendir)(file_t *fp, const char *path); 124 aos_dirent_t *(*readdir)(file_t *fp, aos_dir_t *dir); 125 int (*closedir)(file_t *fp, aos_dir_t *dir); 126 int (*mkdir)(file_t *fp, const char *path); 127 int (*rmdir)(file_t *fp, const char *path); 128 void (*rewinddir)(file_t *fp, aos_dir_t *dir); 129 long (*telldir)(file_t *fp, aos_dir_t *dir); 130 void (*seekdir)(file_t *fp, aos_dir_t *dir, long loc); 131 int (*ioctl)(file_t *fp, int cmd, unsigned long arg); 132 int (*statfs)(file_t *fp, const char *path, struct aos_statfs *suf); 133 int (*access)(file_t *fp, const char *path, int amode); 134 long (*pathconf)(file_t *fp, const char *path, int name); 135 long (*fpathconf)(file_t *fp, int name); 136 int (*utime)(file_t *fp, const char *path, const struct aos_utimbuf *times); 137 }; 138 139 /** 140 * @brief aos_vfs_init() initializes vfs system. 141 * 142 * @param[in] NULL 143 * 144 * @return On success, return new file descriptor. 145 * On error, negative error code is returned to indicate the cause 146 * of the error. 147 */ 148 int aos_vfs_init(void); 149 150 /** 151 * @brief aos_open() opens the file or device by its @path. 152 * 153 * @param[in] path the path of the file or device to open. 154 * @param[in] flags the mode of open operation. 155 * 156 * @return On success, return new file descriptor. 157 * On error, negative error code is returned to indicate the cause 158 * of the error. 159 */ 160 int aos_open(const char *path, int flags); 161 162 /** 163 * @brief aos_close() closes the file or device associated with file 164 * descriptor @fd. 165 * 166 * @param[in] fd the file descriptor of the file or device. 167 * 168 * @return On success, return 0. 169 * On error, negative error code is returned to indicate the cause 170 * of the error. 171 */ 172 int aos_close(int fd); 173 174 /** 175 * @brief aos_read() attempts to read up to @nbytes bytes from file 176 * descriptor @fd into the buffer starting at @buf. 177 * 178 * @param[in] fd the file descriptor of the file or device. 179 * @param[out] buf the buffer to read bytes into. 180 * @param[in] nbytes the number of bytes to read. 181 * 182 * @return On success, the number of bytes is returned (0 indicates end 183 * of file) and the file position is advanced by this number. 184 * On error, negative error code is returned to indicate the cause 185 * of the error. 186 */ 187 ssize_t aos_read(int fd, void *buf, size_t nbytes); 188 189 /** 190 * @brief aos_write() writes up to @nbytes bytes from the buffer starting 191 * at @buf to the file referred to by the file descriptor @fd. 192 * 193 * @param[in] fd the file descriptor of the file or device. 194 * @param[in] buf the buffer to write bytes from. 195 * @param[in] nbytes the number of bytes to write. 196 * 197 * @return On success, the number of bytes written is returned, adn the file 198 * position is advanced by this number.. 199 * On error, negative error code is returned to indicate the cause 200 * of the error. 201 */ 202 ssize_t aos_write(int fd, const void *buf, size_t nbytes); 203 204 /** 205 * @brief aos_ioctl() manipulates the underlying device parameters of special 206 * files. In particular, many operating characteristics of character 207 * special filse may be controlled with aos_iotcl() requests. The argumnet 208 * @fd must be an open file descriptor. 209 * 210 * @param[in] fd the file descriptior of the file or device. 211 * @param[in] cmd A device-dependent request code. 212 * @param[in] arg Argument to the request code, which is interpreted according 213 * to the request code. 214 * 215 * @return Usually, on success 0 is returned. Some requests use the return 216 * value as an output parameter and return a nonnegative value on success. 217 * On error, neagtive error code is returned to indicate the cause 218 * of the error. 219 */ 220 int aos_ioctl(int fd, int cmd, unsigned long arg); 221 222 /** 223 * @brief aos_do_pollfd() is a wildcard API for executing the particular poll events 224 * 225 * @param[in] fd The file descriptor of the file or device 226 * @param[in] flag The flag of the polling 227 * @param[in] notify The polling notify callback 228 * @param[in] fds A pointer to the array of pollfd 229 * @param[in] arg The arguments of the polling 230 * 231 * @return On success, return 0. 232 * On error, negative error code is returned to indicate the cause 233 * of the error. 234 */ 235 int aos_do_pollfd(int fd, int flag, poll_notify_t notify, void *fds, void *arg); 236 237 /** 238 * @brief aos_lseek() repositions the file offset of the open file 239 * description associated with the file descriptor @fd to the 240 * argument @offset according to the directive @whence as follows: 241 * 242 * SEEK_SET: The file offset is set to @offset bytes. 243 * SEEK_CUR: The file offset is set to its current location 244 * plus @offset bytes. 245 * SEEK_END: The file offset is set to the size of the file 246 * plus @offset bytes. 247 * 248 * @param[in] fd The file descriptor of the file. 249 * @param[in] offset The offset relative to @whence directive. 250 * @param[in] whence The start position where to seek. 251 * 252 * @return On success, return the resulting offset location as measured 253 * in bytes from the beginning of the file. 254 * On error, neagtive error code is returned to indicate the cause 255 * of the error. 256 */ 257 off_t aos_lseek(int fd, off_t offset, int whence); 258 259 /** 260 * @brief aos_sync causes the pending modifications of the specified file to 261 * be written to the underlying filesystems. 262 * 263 * @param[in] fd the file descriptor of the file. 264 * 265 * @return On success return 0. 266 * On error, negative error code is returned to indicate the cause 267 * of the error. 268 */ 269 int aos_sync(int fd); 270 271 /** 272 * @brief aos_allsync causes all pending modifications to filesystem metadata 273 * and cached file data to be written to the underlying filesystems. 274 * 275 * @return none 276 */ 277 void aos_allsync(void); 278 279 /** 280 * @brief aos_stat() return information about a file pointed to by @path 281 * in the buffer pointed to by @st. 282 * 283 * @param[in] path The path of the file to be quried. 284 * @param[out] st The buffer to receive information. 285 * 286 * @return On success, return 0. 287 * On error, negative error code is returned to indicate the cause 288 * of the error. 289 */ 290 int aos_stat(const char *path, struct aos_stat *st); 291 292 /** 293 * @brief aos_fstat() return information about a file specified by the file 294 * descriptor @fd in the buffer pointed to by @st. 295 * 296 * @note aos_fstat() is identical to aos_stat(), except that the file about 297 * which information is to be retrieved is specified by the file 298 * descriptor @fd. 299 * 300 * @param[in] fd The file descriptor of the file to be quired. 301 * @param[out] st The buffer to receive information. 302 * 303 * @return On success, return 0. 304 * On error, negative error code is returned to indicate the cause 305 * of the error. 306 */ 307 int aos_fstat(int fd, struct aos_stat *st); 308 309 /** 310 * @brief aos_link() creates a new link @newpath to an existing file @oldpath. 311 * 312 * @note If @newpath exists, it will not be ovrewritten. 313 * 314 * @param[in] oldpath The old path 315 * @param[in] newpath The new path to be created 316 * 317 * @return On success, return 0. 318 * On error, negative error code is returned to indicate the cause 319 * of the error. 320 */ 321 int aos_link(const char *oldpath, const char *newpath); 322 323 /** 324 * @brief aos_unlink() deletes a name from the filesystem. 325 * 326 * @param[in] path The path of the file to be deleted. 327 * 328 * @return On success, return 0. 329 * On error, negative error code is returned to indicate the cause 330 * of the error. 331 */ 332 int aos_unlink(const char *path); 333 334 /** 335 * @brief aos_remove() deletes a name from the filesystem. 336 * 337 * @param[in] path The path of the file to be deleted. 338 * 339 * @return On success, return 0. 340 * On error, negative error code is returned to indicate the cause 341 * of the error. 342 */ 343 int aos_remove(const char *path); 344 345 /** 346 * @brief aos_rename() renames a file, moving it between directories 347 * if required. 348 * 349 * @param[in] oldpath The old path of the file to rename. 350 * @param[in] newpath The new path to rename the file to. 351 * 352 * @return On success, return 0. 353 * On error, negative error code is returned to indicate the cause 354 * of the error. 355 */ 356 int aos_rename(const char *oldpath, const char *newpath); 357 358 /** 359 * @brief aos_opendir() opens a directory stream corresponding to the 360 * directory @path, and returns a pointer to the directory stream. 361 * The stream is positioned at the first entry in the directory. 362 * 363 * @param[in] path the path of the directory to open. 364 * 365 * @return On success, return a point of directory stream. 366 * On error, NULL is returned. 367 */ 368 aos_dir_t *aos_opendir(const char *path); 369 370 /** 371 * @brief aos_closedir() closes the directory stream associated with 372 * @dir. A successful call to aos_closedir() also closes the 373 * underlying file descriptor associated with @dir. The directory 374 * stream descriptor @dir is not available after this call. 375 * 376 * @param[in] dir The directory stream descriptor to be closed. 377 * 378 * @return On success, return 0. 379 * On error, negative error code is returned to indicate the cause 380 * of the error. 381 */ 382 int aos_closedir(aos_dir_t *dir); 383 384 /** 385 * @brief aos_readdir() returns a pointer to an @aos_dirent_t representing 386 * the next directory entry in the directory stream pointed to by 387 * @dir. It returns Null on reaching the end of the directory stream 388 * or if an error occurred. 389 * 390 * @param[in] dir The directory stream descriptor to read. 391 * 392 * @return On success, aos_readdir() returns a pointer to an @aos_dirent_t 393 * structure. If the end of the directory stream is reached, NULL is 394 * returned. 395 * On error, NULL is returned. 396 */ 397 aos_dirent_t *aos_readdir(aos_dir_t *dir); 398 399 /** 400 * @brief aos_mkdir() attempts to create a directory named @path 401 * 402 * @param[in] path The name of directory to be created. 403 * 404 * @return On success, return 0. 405 * On error, negative error code is returned to indicate the cause 406 * of the error. 407 */ 408 int aos_mkdir(const char *path); 409 410 /** 411 * @brief aos_rmdir() deletes a directory, which must be emtpy. 412 * 413 * @param[in] path The directory to be deleted. 414 * 415 * @return On success, return 0. 416 * On error, negative error code is returned to indicate the cause 417 * of the error. 418 */ 419 int aos_rmdir(const char *path); 420 421 /** 422 * @brief aos_rewinddir() resets the position of the directory stream @dir 423 * to the beginning of the directory. 424 * 425 * @param[in] dir The directory stream descriptor pointer. 426 * 427 * @return none. 428 */ 429 void aos_rewinddir(aos_dir_t *dir); 430 431 /** 432 * @brief aos_telldir() returns the current location associated with the 433 * directory stream @dir. 434 * 435 * @param[in] dir The directory stream descriptor pointer. 436 * 437 * @return On success, aos_telldir() returns the current location in the 438 * directory stream. 439 * On error, negative error code is returned to indicate the cause 440 * of the error. 441 */ 442 long aos_telldir(aos_dir_t *dir); 443 444 /** 445 * @brief aos_seekdir() sets the location in the directory stram from 446 * which the next aos_readdir() call will start. The @loc argument 447 * should be a value returnned by a previous call to aos_telldir(). 448 * 449 * @param[in] dir The directory stream descriptor pointer. 450 * @param[in] loc The location in the directory stream from which the next 451 * aos_readdir() call will start. 452 * 453 * @return none. 454 */ 455 void aos_seekdir(aos_dir_t *dir, long loc); 456 457 /** 458 * @brief aos_statfs() gets information about a mounted filesystem. 459 * 460 * @param[in] path The path name of any file within the mounted filessytem. 461 * @param[out] buf Buffer points to an aos_statfs structure to receive 462 * filesystem information. 463 * 464 * @return On success, return 0. 465 * On error, negative error code is returned to indicate the cause 466 * of the error. 467 */ 468 int aos_statfs(const char *path, struct aos_statfs *buf); 469 470 /** 471 * @brief aos_access() checks whether the calling process can access the 472 * file @path. 473 * 474 * @param[in] path The path of the file. 475 * @param[in] mode Specifies the accessibility check(s) to be performed, and 476 * is either the value of F_OK, or a mask consisting of the 477 * bitwise OR of one or more of R_OK, W_OK, and X_OK. F_OK 478 * tests for the existence of the file. R_OK, W_OK and X_OK 479 * tests whether the file exists and grants read, write, and 480 * execute permissions, repectively. 481 * 482 * @return On success (all requested permissions granted, or mode is F_OK and 483 * the file exists), 0 is returned. 484 * On error (at least one bit in mode asked for a permission that is 485 * denied, or mode is F_OK and the file does not exist, or some other 486 * error occurred), negative error code is returned to indicate the 487 * cause of the error. 488 */ 489 int aos_access(const char *path, int amode); 490 491 /** 492 * @brief aos_chdir() changes the current working directory of the calling 493 * process to the directory specified in @path. 494 * 495 * @param[in] path The path to change to. 496 * 497 * @return On success return 0. 498 * On error, negative error code is returned to indicate the cause 499 * of the error. 500 */ 501 int aos_chdir(const char *path); 502 503 /** 504 * @brief aos_getcwd() return a null-terminated string containing an absolute 505 * pathname that is the current working directory of the calling process. 506 * The pathname is returned as the function result and via the argument 507 * @buf, if present. 508 * aos_getcwd() function copies an absolute pathname of the current 509 * working directory to the array pointed by @buf, which is of length @size. 510 * 511 * If the length of the absolute pathname of the current working directory, 512 * including the terminating null byte, exceeds @size bytes, NULL is returned. 513 * 514 * @param[out] buf The buffer to receive the current working directory pathname. 515 * @param[in] size The size of buffer. 516 * 517 * @return On success, aos_getcwd() returns a pointer to a string containing 518 * the pathname of the current working directory. 519 * On error, NULL is returned. 520 */ 521 char *aos_getcwd(char *buf, size_t size); 522 523 /** 524 * @brief aos_pathconf() gets a value for configuration option @name for the 525 * filename @path. 526 * 527 * @param[in] path The path name to quire 528 * @param[in] name The configuration option 529 * 530 * @return On error, negative error code is returned to indicate the cause 531 * of the error. 532 * On success, if @name corresponds to an option, a positive value is 533 * returned if the option is supported. 534 */ 535 long aos_pathconf(const char *path, int name); 536 537 /** 538 * @brief aos_fpathconf() gets a value for the cofiguration option @name for 539 * the open file descriptor @fd. 540 * 541 * @param[in] fd The open file descriptor to quire 542 * @param[in] name The configuration option 543 * 544 * @return On success, if @name corresponds to an option, a positive value is 545 * returned if the option is supported. 546 * On error, negative error code is returned to indicate the cause 547 * of the error. 548 */ 549 long aos_fpathconf(int fd, int name); 550 551 /** 552 * @brief aos_utime() changes teh access and modification times of the inode 553 * specified by @path to the actime and modtime fields of the @times 554 * respectively. 555 * If @times is NULL, then the access and modification times of the file 556 * are set to the current time. 557 * 558 * @param[in] path Path name of the inode to operate. 559 * @param[in] times Buffer pointer to structure aos_utimbuf whose actime 560 * and modtime fields will be set to the inode @path. 561 * 562 * @return 0 on success, negative error code on failure 563 */ 564 int aos_utime(const char *path, const struct aos_utimbuf *times); 565 566 /** 567 * @brief aos_vfs_fd_offset_get() gets VFS fd offset 568 * 569 * @return VFS fd offset 570 */ 571 int aos_vfs_fd_offset_get(void); 572 573 /** 574 * @brief aos_fcntl() change the nature of the opened file 575 * 576 * @param[in] fd The open file descriptor to quire 577 * @param[in] cmd The configuration command. 578 * @param[in] val The configuration value. 579 * 580 * @return On success return 0. 581 * On error, negative error code is returned to indicate the cause 582 * of the error. 583 */ 584 int aos_fcntl(int fd, int cmd, int val); 585 586 /** 587 * @brief Bind driver to the file or device 588 * 589 * @param[in] path The path of the file or device 590 * @param[in] ops The driver operations to bind 591 * @param[in] arg The arguments of the driver operations 592 * 593 * @return On success return 0. 594 * On error, negative error code is returned to indicate the cause 595 * of the error. 596 */ 597 int aos_register_driver(const char *path, file_ops_t *ops, void *arg); 598 599 /** 600 * @brief Unbind driver from the file or device 601 * 602 * @param[in] path The path of the file or device 603 * 604 * @return On success return 0. 605 * On error, negative error code is returned to indicate the cause 606 * of the error. 607 */ 608 int aos_unregister_driver(const char *path); 609 610 /** 611 * @brief aos_register_fs() mounts filesystem to the path 612 * 613 * @param[in] path The mount point path 614 * @param[in] ops The filesystem operations 615 * @param[in] arg The arguments of the filesystem operations 616 * 617 * @return On success return 0. 618 * On error, negative error code is returned to indicate the cause 619 * of the error. 620 */ 621 int aos_register_fs(const char *path, fs_ops_t* ops, void *arg); 622 623 /** 624 * @brief aos_unregister_fs() unmounts the filesystem 625 * 626 * @param[in] path The mount point path 627 * 628 * @return On success return 0. 629 * On error, negative error code is returned to indicate the cause 630 * of the error. 631 */ 632 int aos_unregister_fs(const char *path); 633 634 /* adapter tmp */ 635 //typedef struct aos_stat stat; 636 637 /** @} */ 638 639 #ifdef __cplusplus 640 } 641 #endif 642 643 #endif /* AOS_VFS_H */ 644 645