You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2026/10/17 22:31:43 UTC
(nuttx) 01/04: Documentation: Describe the PATH search of exec() and posix_spawn().
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 2bc760936f429b52da946aa38f5c97684eb6c577
Author: Marco Casaroli <ma...@gmail.com>
AuthorDate: Sat Oct 17 19:58:10 2026 +0200
Documentation: Describe the PATH search of exec() and posix_spawn().
exec(), execv(), execl(), posix_spawn() and load_module() search PATH
only for a name that contains no '/'. Any other name is a path: an
absolute path, or a path relative to the current working directory.
The documentation said that a relative path is searched in PATH, and
that without CONFIG_LIBC_ENVPATH the path must be absolute.
Describe the PATH rule for each of these functions. Also remove the
broken second ":param path:" line of execv() and execl().
Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: Marco Casaroli <ma...@gmail.com>
---
Documentation/os/binfmt/index.rst | 11 +++---
Documentation/reference/user/01_task_control.rst | 44 ++++++++++++++----------
2 files changed, 31 insertions(+), 24 deletions(-)
diff --git a/Documentation/os/binfmt/index.rst b/Documentation/os/binfmt/index.rst
index 13b9e18af4d..9cb18d3a36e 100644
--- a/Documentation/os/binfmt/index.rst
+++ b/Documentation/os/binfmt/index.rst
@@ -181,11 +181,12 @@ Basic module management
:param bin:
The ``filename`` field will be used
in order to locate the module to be loaded from the file system.
- The filename must be the full, absolute path to the file to be executed
- unless ``CONFIG_LIBC_ENVPATH`` is defined. In that case, filename may be
- a relative path; a set of candidate absolute paths will be generated using
- the ``PATH`` environment variable and ``load_module()`` will attempt to load each
- file that is found at those absolute paths.
+ With ``CONFIG_LIBC_ENVPATH``, a filename that contains no ``/`` is
+ searched for in the directories of the ``PATH`` environment variable,
+ and ``load_module()`` tries to load each file that it finds there. Any
+ other filename is a path and is used as it is: an absolute path, or a
+ path relative to the current working directory. Without
+ ``CONFIG_LIBC_ENVPATH``, each filename is used as a path.
:return:
This is a NuttX internal function so it follows the convention that 0 (``OK``)
diff --git a/Documentation/reference/user/01_task_control.rst b/Documentation/reference/user/01_task_control.rst
index 53cb6f880f3..884832bfb2f 100644
--- a/Documentation/reference/user/01_task_control.rst
+++ b/Documentation/reference/user/01_task_control.rst
@@ -454,10 +454,13 @@ Functions
those features there is then no mechanism to unload the module once it
exits.
- :param filename: The path to the program to be executed. If
- ``CONFIG_LIBC_ENVPATH`` is defined in the configuration, then this may
- be a relative path from the current working directory. Otherwise,
- ``path`` must be the absolute path to the program.
+ :param filename: The program to be executed. With
+ ``CONFIG_LIBC_ENVPATH``, a name that contains no ``/`` is searched for
+ in the directories of the ``PATH`` environment variable. Any other name
+ is a path and is used as it is: an absolute path, or a path relative to
+ the current working directory, such as ``./hello`` or ``bin/hello``.
+ Without ``CONFIG_LIBC_ENVPATH``, no ``PATH`` search is done, and each
+ name is used as a path.
:param argv: A pointer to an array of string arguments. The end of the
array is indicated with a NULL entry.
:param exports: The address of the start of the caller-provided symbol
@@ -526,10 +529,12 @@ Functions
function. So the parent function cannot know the ID of the ``exec``'ed
task.
- :param path: The path to the program to be executed. If
- ``CONFIG_LIBC_ENVPATH`` is defined in the configuration, then this may
- be a relative path from the current working directory. Otherwise,
- :param path: must be the absolute path to the program.
+ :param path: The program to be executed. With ``CONFIG_LIBC_ENVPATH``, a
+ name that contains no ``/`` is searched for in the directories of the
+ ``PATH`` environment variable. Any other name is a path and is used as
+ it is: an absolute path, or a path relative to the current working
+ directory. Without ``CONFIG_LIBC_ENVPATH``, no ``PATH`` search is done,
+ and each name is used as a path.
:return: This function does not return on success. On
failure, it will return -1 (``ERROR``) and will set the ``errno`` value
@@ -546,10 +551,12 @@ Functions
parameters. See the description of `execv() <#execv>`__ for additional
information.
- :param path: The path to the program to be executed. If
- ``CONFIG_LIBC_ENVPATH`` is defined in the configuration, then this may
- be a relative path from the current working directory. Otherwise,
- :param path: must be the absolute path to the program.
+ :param path: The program to be executed. With ``CONFIG_LIBC_ENVPATH``, a
+ name that contains no ``/`` is searched for in the directories of the
+ ``PATH`` environment variable. Any other name is a path and is used as
+ it is: an absolute path, or a path relative to the current working
+ directory. Without ``CONFIG_LIBC_ENVPATH``, no ``PATH`` search is done,
+ and each name is used as a path.
:return: This function does not return on success. On
failure, it will return -1 (``ERROR``) and will set the ``errno`` value
@@ -579,13 +586,12 @@ Functions
argument. If the ``pid`` argument is a null pointer, the process ID
of the child is not returned to the caller.
- :param path: The ``path`` argument to ``posix_spawn()`` is
- the absolute path that identifies the file to execute. The ``file``
- argument to ``posix_spawnp()`` may also be a relative path and will
- be used to construct a pathname that identifies the file to execute.
- In the case of a relative path, the path prefix for the file will be
- obtained by a search of the directories passed as the environment
- variable PATH.
+ :param path: The ``path`` argument to ``posix_spawn()`` and the ``file``
+ argument to ``posix_spawnp()`` identify the file to execute. With
+ ``CONFIG_LIBC_ENVPATH``, a name that contains no ``/`` is searched for
+ in the directories of the ``PATH`` environment variable. Any other name
+ is a path and is used as it is: an absolute path, or a path relative to
+ the current working directory, such as ``./hello`` or ``bin/hello``.
NOTE: NuttX provides only one implementation: If
``CONFIG_LIBC_ENVPATH`` is defined, then only ``posix_spawnp()``