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 <[email protected]> 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 <[email protected]> --- 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()``
