Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[documentation][dfs]add some comments to dfs posix APIs for supplement. #9730

Merged
merged 1 commit into from
Dec 1, 2024
Merged

[documentation][dfs]add some comments to dfs posix APIs for supplement. #9730

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 49 additions & 9 deletions components/dfs/dfs_v1/src/dfs_posix.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2006-2021, RT-Thread Development Team
* Copyright (c) 2006-2024 RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
Expand Down Expand Up @@ -28,7 +28,17 @@
* return a file descriptor according specified flags.
*
* @param file the path name of file.
* @param flags the file open flags.
* @param flags the file open flags. Common values include:
* - Access modes (mutually exclusive):
* - `O_RDONLY`: Open for read-only access.
* - `O_WRONLY`: Open for write-only access.
* - `O_RDWR`: Open for both reading and writing.
* - File status flags (can be combined with bitwise OR `|`):
* - `O_CREAT`: Create the file if it does not exist. Requires a `mode` argument.
* - `O_TRUNC`: Truncate the file to zero length if it already exists.
* - `O_APPEND`: Append writes to the end of the file.
* - `O_EXCL`: Ensure that `O_CREAT` creates the file exclusively.
* - Other platform-specific flags
*
* @return the non-negative integer on successful open, others for failed.
*/
Expand Down Expand Up @@ -65,6 +75,22 @@ RTM_EXPORT(open);
#ifndef AT_FDCWD
#define AT_FDCWD (-100)
#endif

/**
* @brief Opens a file relative to a directory file descriptor.
*
* @param dirfd The file descriptor of the directory to base the relative path on.
* @param pathname The path to the file to be opened, relative to the directory specified by `dirfd`.
* Can be an absolute path (in which case `dirfd` is ignored).
* @param flags File access and status flags (e.g., `O_RDONLY`, `O_WRONLY`, `O_CREAT`).
*
* @return On success, returns a new file descriptor for the opened file.
* On failure, returns `-1` and sets `errno` to indicate the error.
*
* @note When using relative paths, ensure `dirfd` is a valid directory descriptor.
* When `pathname` is absolute, the `dirfd` argument is ignored.
*
*/
int openat(int dirfd, const char *path, int flag, ...)
{
struct dfs_file *d;
Expand Down Expand Up @@ -241,14 +267,22 @@ ssize_t write(int fd, const void *buf, size_t len)
RTM_EXPORT(write);

/**
* this function is a POSIX compliant version, which will seek the offset for
* this function is a POSIX compliant version, which will Reposition the file offset for
* an open file descriptor.
*
* The `lseek` function sets the file offset for the file descriptor `fd`
* to a new value, determined by the `offset` and `whence` parameters.
* It can be used to seek to specific positions in a file for reading or writing.
*
* @param fd the file descriptor.
* @param offset the offset to be seeked.
* @param whence the directory of seek.
* @param offset The offset, in bytes, to set the file position.
* The meaning of `offset` depends on the value of `whence`.
* @param whence the directive of seek. It can be one of:
* - `SEEK_SET`: Set the offset to `offset` bytes from the beginning of the file.
* - `SEEK_CUR`: Set the offset to its current location plus `offset` bytes.
* - `SEEK_END`: Set the offset to the size of the file plus `offset` bytes.
*
* @return the current read/write position in the file, or -1 on failed.
* @return the resulting read/write position in the file, or -1 on failed.
*/
off_t lseek(int fd, off_t offset, int whence)
{
Expand Down Expand Up @@ -436,9 +470,15 @@ RTM_EXPORT(fsync);
* control functions on devices.
*
* @param fildes the file description
* @param cmd the specified command
* @param cmd the specified command, Common values include:
* - `F_DUPFD`: Duplicate a file descriptor.
* - `F_GETFD`: Get the file descriptor flags.
* - `F_SETFD`: Set the file descriptor flags.
* - `F_GETFL`: Get the file status flags.
* - `F_SETFL`: Set the file status flags.
* @param ... represents the additional information that is needed by this
* specific device to perform the requested function.
* specific device to perform the requested function. For example:
* - When `cmd` is `F_SETFL`, an additional integer argument specifies the new status flags.
*
* @return 0 on successful completion. Otherwise, -1 shall be returned and errno
* set to indicate the error.
Expand Down Expand Up @@ -595,7 +635,7 @@ RTM_EXPORT(fstatfs);
* this function is a POSIX compliant version, which will make a directory
*
* @param path the directory path to be made.
* @param mode
* @param mode The permission mode for the new directory (unused here, can be set to 0).
*
* @return 0 on successful, others on failed.
*/
Expand Down
60 changes: 50 additions & 10 deletions components/dfs/dfs_v2/src/dfs_posix.c
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2006-2023, RT-Thread Development Team
* Copyright (c) 2006-2024 RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
Expand Down Expand Up @@ -31,7 +31,17 @@
* return a file descriptor according specified flags.
*
* @param file the path name of file.
* @param flags the file open flags.
* @param flags the file open flags. Common values include:
* - Access modes (mutually exclusive):
* - `O_RDONLY`: Open for read-only access.
* - `O_WRONLY`: Open for write-only access.
* - `O_RDWR`: Open for both reading and writing.
* - File status flags (can be combined with bitwise OR `|`):
* - `O_CREAT`: Create the file if it does not exist. Requires a `mode` argument.
* - `O_TRUNC`: Truncate the file to zero length if it already exists.
* - `O_APPEND`: Append writes to the end of the file.
* - `O_EXCL`: Ensure that `O_CREAT` creates the file exclusively.
* - Other platform-specific flags
*
* @return the non-negative integer on successful open, others for failed.
*/
Expand Down Expand Up @@ -81,6 +91,22 @@ RTM_EXPORT(open);
#ifndef AT_FDCWD
#define AT_FDCWD (-100)
#endif

/**
* @brief Opens a file relative to a directory file descriptor.
*
* @param dirfd The file descriptor of the directory to base the relative path on.
* @param pathname The path to the file to be opened, relative to the directory specified by `dirfd`.
* Can be an absolute path (in which case `dirfd` is ignored).
* @param flags File access and status flags (e.g., `O_RDONLY`, `O_WRONLY`, `O_CREAT`).
*
* @return On success, returns a new file descriptor for the opened file.
* On failure, returns `-1` and sets `errno` to indicate the error.
*
* @note When using relative paths, ensure `dirfd` is a valid directory descriptor.
* When `pathname` is absolute, the `dirfd` argument is ignored.
*
*/
int openat(int dirfd, const char *path, int flag, ...)
{
struct dfs_file *d;
Expand Down Expand Up @@ -171,7 +197,7 @@ int utimensat(int __fd, const char *__path, const struct timespec __times[2], in
}
}

//update time
/*update time*/
attr.ia_valid = ATTR_ATIME_SET | ATTR_MTIME_SET;
time(&current_time);
if (UTIME_NOW == __times[0].tv_nsec)
Expand Down Expand Up @@ -374,14 +400,22 @@ ssize_t write(int fd, const void *buf, size_t len)
RTM_EXPORT(write);

/**
* this function is a POSIX compliant version, which will seek the offset for
* this function is a POSIX compliant version, which will Reposition the file offset for
* an open file descriptor.
*
* The `lseek` function sets the file offset for the file descriptor `fd`
* to a new value, determined by the `offset` and `whence` parameters.
* It can be used to seek to specific positions in a file for reading or writing.
*
* @param fd the file descriptor.
* @param offset the offset to be seeked.
* @param whence the directory of seek.
* @param offset The offset, in bytes, to set the file position.
* The meaning of `offset` depends on the value of `whence`.
* @param whence the directive of seek. It can be one of:
* - `SEEK_SET`: Set the offset to `offset` bytes from the beginning of the file.
* - `SEEK_CUR`: Set the offset to its current location plus `offset` bytes.
* - `SEEK_END`: Set the offset to the size of the file plus `offset` bytes.
*
* @return the current read/write position in the file, or -1 on failed.
* @return the resulting read/write position in the file, or -1 on failed.
*/
off_t lseek(int fd, off_t offset, int whence)
{
Expand Down Expand Up @@ -581,9 +615,15 @@ RTM_EXPORT(fsync);
* control functions on devices.
*
* @param fildes the file description
* @param cmd the specified command
* @param cmd the specified command, Common values include:
* - `F_DUPFD`: Duplicate a file descriptor.
* - `F_GETFD`: Get the file descriptor flags.
* - `F_SETFD`: Set the file descriptor flags.
* - `F_GETFL`: Get the file status flags.
* - `F_SETFL`: Set the file status flags.
* @param ... represents the additional information that is needed by this
* specific device to perform the requested function.
* specific device to perform the requested function. For example:
* - When `cmd` is `F_SETFL`, an additional integer argument specifies the new status flags.
*
* @return 0 on successful completion. Otherwise, -1 shall be returned and errno
* set to indicate the error.
Expand Down Expand Up @@ -765,7 +805,7 @@ RTM_EXPORT(fstatfs);
* this function is a POSIX compliant version, which will make a directory
*
* @param path the directory path to be made.
* @param mode
* @param mode The permission mode for the new directory (unused here, can be set to 0).
*
* @return 0 on successful, others on failed.
*/
Expand Down