(nuttx) 04/04: Documentation/binfmt: Describe the script binary format.

[ac...@apache.org]

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 b3b2c3e07f25af4745c8d467cb4ad60abb65a982
Author: Marco Casaroli <ma...@gmail.com>
AuthorDate: Sat Oct 17 19:59:15 2026 +0200

    Documentation/binfmt: Describe the script binary format.
    
    CONFIG_BINFMT_SCRIPT adds a binary format for files that start with
    "#!". The binary loader page did not list it.
    
    Add the script format to the list of formats. Add a section that gives
    the form of the first line, the argument list of the interpreter, the
    limits and the errors. Add the option to the configuration variables.
    
    Assisted-by: Claude Code:claude-opus-5-5
    Signed-off-by: Marco Casaroli <ma...@gmail.com>
---
 Documentation/os/binfmt/index.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/Documentation/os/binfmt/index.rst b/Documentation/os/binfmt/index.rst
index 9cb18d3a36e..ab5757a06b3 100644
--- a/Documentation/os/binfmt/index.rst
+++ b/Documentation/os/binfmt/index.rst
@@ -30,6 +30,8 @@ At present, the following binary formats are support by NuttX:
   - **NXFLAT**. NuttX NXFLAT formatted files. More information about the
     NXFLAT binary format can be found in the :ref:`NXFLAT
     documentation <nxflat>`.
+  - **Scripts**. A file that starts with ``#!`` is run by the interpreter
+    that its first line names. See `Scripts`_ below.
 
 **Executables and Libraries** The generic binary loader logic does not
 care what it is that it being loaded. It could load an executable
@@ -48,6 +50,30 @@ However, the NuttX binary loader is an independent development and
 shares nothing with the Linux binary loader other the same name and the
 same basic functionality.
 
+Scripts
+=======
+
+With ``CONFIG_BINFMT_SCRIPT`` (default ``n``), ``exec()`` and
+``posix_spawn()`` can run a file whose first line has this form::
+
+  #!<interpreter> [<argument>]
+
+The loader starts the interpreter with the argument list that Linux uses::
+
+  <interpreter> [<argument>] <script> <argv[1]> ...
+
+``<script>`` is the path of the script that was loaded, also when it was
+found through ``PATH``. The interpreter ends at the first white space. The
+rest of the line, without the white space around it, is one optional
+argument. The loader reads at most 127 bytes of the first line.
+
+The interpreter must be a file that another binary format can load, for
+example an ELF program or a builtin application. The interpreter can be a
+script too, up to four levels. A deeper chain fails with ``ELOOP``. A
+missing interpreter fails with ``ENOENT``. The script format is tried after
+all other formats, so a file that no format accepts fails with
+``ENOEXEC``.
+
 Binary Loader Interface
 =======================
 
@@ -356,6 +382,8 @@ Configuration Variables
   - ``CONFIG_BINFMT_DISABLE``: By default, support for loadable binary formats is built.
     This logic may be suppressed be defining this setting.
   - ``CONFIG_BINFMT_CONSTRUCTORS``: Build in support for C++ constructors in loaded modules.
+  - ``CONFIG_BINFMT_SCRIPT``: Run files that start with ``#!`` through the
+    interpreter that they name. Default: ``n``.
   - ``CONFIG_SYMTAB_ORDEREDBYNAME``: Symbol tables are order by name (rather than value).
   - ``CONFIG_SYMTAB_DECORATED``: Symbols will have a leading underscore in object files.