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 <dominik.ermel@nordicsemi.no>
diff --git a/include/zephyr/fs/fs.h b/include/zephyr/fs/fs.h
index ee628dc..bb05180 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 @@
* @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 @@
* - @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 @@
* @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 bf3cd71..e959f34 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
*/
