From 32e0724a29261a470cdd58a873ef4dd3bcfa08ac Mon Sep 17 00:00:00 2001 From: Dominik Ermel Date: Thu, 19 Oct 2023 16:53:17 +0000 Subject: [PATCH] fs: Clarify description of fs_open when no access bits given Add warning that file opened without R/W flags will have no read/write access. Remove suggestion for using fs_open to check if file exists. Clarify -ENOENT return reason. Fixes #64030 Signed-off-by: Dominik Ermel --- include/zephyr/fs/fs.h | 10 ++++++---- subsys/fs/fs.c | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/include/zephyr/fs/fs.h b/include/zephyr/fs/fs.h index ee628dc1b8b0..bb051804b6c3 100644 --- a/include/zephyr/fs/fs.h +++ b/include/zephyr/fs/fs.h @@ -1,6 +1,6 @@ /* * Copyright (c) 2016 Intel Corporation. - * Copyright (c) 2020-2021 Nordic Semiconductor ASA + * Copyright (c) 2020-2024 Nordic Semiconductor ASA * * SPDX-License-Identifier: Apache-2.0 */ @@ -252,6 +252,8 @@ static inline void fs_dir_t_init(struct fs_dir_t *zdp) * @brief Open or create file * * Opens or possibly creates a file and associates a stream with it. + * Successfully opened file, when no longer in use, should be closed + * with fs_close(). * * @details * @p flags can be 0 or a binary combination of one or more of the following @@ -262,8 +264,8 @@ static inline void fs_dir_t_init(struct fs_dir_t *zdp) * - @c FS_O_CREATE create file if it does not exist * - @c FS_O_APPEND move to end of file before each write * - * If @p flags are set to 0 the function will attempt to open an existing file - * with no read/write access; this may be used to e.g. check if the file exists. + * @warning If @p flags are set to 0 the function will open file, if it exists + * and is accessible, but you will have no read/write access to it. * * @param zfp Pointer to a file object * @param file_name The name of a file to open @@ -275,7 +277,7 @@ static inline void fs_dir_t_init(struct fs_dir_t *zdp) * @retval -EROFS when opening read-only file for write, or attempting to * create a file on a system that has been mounted with the * FS_MOUNT_FLAG_READ_ONLY flag; - * @retval -ENOENT when the file path is not possible (bad mount point); + * @retval -ENOENT when the file does not exist at the path; * @retval -ENOTSUP when not implemented by underlying file system driver; * @retval <0 an other negative errno code, depending on a file system back-end. */ diff --git a/subsys/fs/fs.c b/subsys/fs/fs.c index 60bb3e36453e..8a76a8572a7e 100644 --- a/subsys/fs/fs.c +++ b/subsys/fs/fs.c @@ -1,7 +1,7 @@ /* * Copyright (c) 2018 Intel Corporation. * Copyright (c) 2020 Peter Bigot Consulting, LLC - * Copyright (c) 2020 Nordic Semiconductor ASA + * Copyright (c) 2020-2024 Nordic Semiconductor ASA * * SPDX-License-Identifier: Apache-2.0 */