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 938e0c445bb96b007822b50270bb71b1b43fed81 Author: Marco Casaroli <[email protected]> AuthorDate: Sat Oct 17 19:58:38 2026 +0200 Documentation: Describe environ and the envp argument. The documentation of posix_spawn() and task_spawn() said that NuttX ignores envp and does not support the environ variable. The new task gets a copy of envp, or of the environment of the caller when envp is NULL. environ is a macro in <stdlib.h> that a program can read and assign. Describe envp for posix_spawn() and task_spawn(). Add a section about environ to the environment variables page: the macro, the third argument of main() that crt0 passes, the environment functions in the C library, and the environment strings that stay until the task group exits. Add libs/libc/environ to the list of libc sub-directories. Assisted-by: Claude Code:claude-opus-5-5 Signed-off-by: Marco Casaroli <[email protected]> --- Documentation/os/libs/libc/index.rst | 1 + Documentation/reference/user/01_task_control.rst | 18 +++++-------- Documentation/reference/user/09_env_vars.rst | 34 ++++++++++++++++++++++++ 3 files changed, 42 insertions(+), 11 deletions(-) diff --git a/Documentation/os/libs/libc/index.rst b/Documentation/os/libs/libc/index.rst index 87b16eef6b9..2d0e7acd5b4 100644 --- a/Documentation/os/libs/libc/index.rst +++ b/Documentation/os/libs/libc/index.rst @@ -33,6 +33,7 @@ functions. So we have:: builtin - Support for builtin applications. Used by nuttx/binfmt and NSH. dlfcn - dlfcn.h endian - endian.h + environ - Environment variables: getenv(), setenv() and others (stdlib.h) errno - errno.h hex2bin - hex2bin.h libgen - libgen.h diff --git a/Documentation/reference/user/01_task_control.rst b/Documentation/reference/user/01_task_control.rst index 884832bfb2f..07ecddd7a5c 100644 --- a/Documentation/reference/user/01_task_control.rst +++ b/Documentation/reference/user/01_task_control.rst @@ -629,13 +629,10 @@ Functions ``argv[]`` is an array of pointers to null-terminated strings. The list is terminated with a null pointer. - :param envp: The ``envp[]`` argument is not used by NuttX and may be - ``NULL``. In standard implementations, ``envp[]`` is an array of - character pointers to null-terminated strings that provide the - environment for the new process image. The environment array is - terminated by a null pointer. In NuttX, the ``envp[]`` argument is - ignored and the new task will inherit the environment of the parent - task unconditionally. + :param envp: ``envp[]`` is an array of pointers to null-terminated + ``name=value`` strings that is the environment of the new task. The + array is terminated by a null pointer. If ``envp`` is ``NULL``, the new + task gets a copy of the environment of the caller (``environ``). :return: Zero on success. Otherwise, an error number will be returned as the function return value to indicate the error: @@ -652,8 +649,6 @@ Functions ``CONFIG_LIBC_ENVPATH`` is defined, then only ``posix_spawnp()`` behavior is supported; otherwise, only ``posix_spawn()`` behavior is supported. - - The ``envp`` argument is not used and the ``environ`` variable is not - altered (NuttX does not support the ``environ`` variable). - Process groups are not supported (See ``POSIX_SPAWN_SETPGROUP`` above). - Effective user IDs are not supported (See ``POSIX_SPAWN_RESETIDS`` @@ -924,8 +919,9 @@ Functions ``argv[]`` is an array of pointers to null-terminated strings. The list is terminated with a null pointer. - :param envp: The ``envp[]`` argument is not used by NuttX and may be - ``NULL``. + :param envp: The environment of the new task, as for + :c:func:`posix_spawn`. If ``envp`` is ``NULL``, the new task gets a + copy of the environment of the caller. :return: ``task_spawn()`` will return process ID of new task on success. Otherwise, a negative number will be returned as the function return diff --git a/Documentation/reference/user/09_env_vars.rst b/Documentation/reference/user/09_env_vars.rst index 44908b00df4..3cfd381a4cb 100644 --- a/Documentation/reference/user/09_env_vars.rst +++ b/Documentation/reference/user/09_env_vars.rst @@ -41,6 +41,40 @@ All support for environment variables can be disabled by setting ``CONFIG_DISABLE_ENVIRON`` in the board configuration file. +The ``environ`` Variable +======================== + +``environ`` points to the environment of the calling task group: an array +of ``name=value`` strings that ends with a ``NULL`` pointer. Each task +group has its own environment, so ``<stdlib.h>`` defines ``environ`` as a +macro, ``(*get_environ_ptr())``. NuttX has no ``environ`` symbol: include +``<stdlib.h>`` to use ``environ``. A program can read the array, change an +entry in place, or assign its own array to ``environ``. The functions +below then work on that array. With ``CONFIG_DISABLE_ENVIRON``, +``environ`` is ``NULL``. + +An ELF program can also get the environment as the third argument of +``main()``: + +.. code-block:: c + + int main(int argc, FAR char *argv[], FAR char *envp[]); + +The ``crt0`` of NuttX passes ``environ`` there on arm, arm64, risc-v, +x86_64 and xtensa (``NULL`` with ``CONFIG_DISABLE_ENVIRON``). A program +that is not started through ``crt0``, for example a builtin application, +gets only ``argc`` and ``argv``. + +The environment functions are in the C library, not system calls. Each +environment is in the heap that holds the task information of its task +group: the user heap for a user task, the kernel heap for a kernel thread. + +The C library frees no environment string that it allocated until the +task group exits. So a pointer that :c:func:`getenv` returned stays valid +after :c:func:`setenv`, :c:func:`putenv`, :c:func:`unsetenv` or +:c:func:`clearenv` changes the environment. A program that sets one +variable many times keeps the old values until it exits. + Functions =========
