Skip to contentSkip to conversation

Documentation/binfmt-misc.rst: Clarify "P" flag

PATCH In review Charlie Jenkins 2 participants 5 messages Apr 19 – Apr 23

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

cover Documentation/binfmt-misc.rst: Clarify "P" flag

Improve the wording of the description of the "P" flag to explain that the interpreter gets the path to the file provided by execve and not the full path as well as documenting that AT_FLAGS can be read to see if the "P" flag is set.

---
Charlie Jenkins (2):
Documentation/binfmt-misc.rst: Include AT_FLAGS info in "P" flag description Documenation/binfmt-misc.rst: Make "P" flag path desc more precise

 Documentation/admin-guide/binfmt-misc.rst | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

---
base-commit: 028ef9c96e96197026887c0f092424679298aae8
change-id: ${change-id}

- Charlie

#1 lore raw

PATCH 1/2 Documentation/binfmt-misc.rst: Include AT_FLAGS info in "P" flag description

Commit 2347961b11d4 ("binfmt_misc: pass binfmt_misc flags to the interpreter") added a bit to AT_FLAGS in the aux vector to notify an interpreter that the 'P' flag was set in binfmt-misc. Clarify that the interpreter is able to be aware of the 'P' flag by using this bit.

---
 Documentation/admin-guide/binfmt-misc.rst | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/admin-guide/binfmt-misc.rst +5 -3
index 59cd902e3549..2e2be2922ba6 100644
@@ -61,9 +61,11 @@ Here is what the fields mean:
             vector for this purpose, thus preserving the original ``argv[0]``.
             e.g. If your interp is set to ``/bin/foo`` and you run ``blah``
             (which is in ``/usr/local/bin``), then the kernel will execute
-            ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``.  The interp has to be aware of this so it can
-            execute ``/usr/local/bin/blah``
-            with ``argv[]`` set to ``["blah"]``.
+            ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo",
+            "/usr/local/bin/blah", "blah"]``.  The interp can be aware of this
+            by checking if bit 0 in AT_FLAGS in the auxilary vector is set to 1
+            so it can execute ``/usr/local/bin/blah`` with ``argv[]`` set to
+            ``["blah"]``.
       ``O`` - open-binary
 	    Legacy behavior of binfmt_misc is to pass the full path
             of the binary to the interpreter as an argument. When this flag is
Signature · 1 line
2.53.0
#2 lore raw

PATCH 2/2 Documenation/binfmt-misc.rst: Make "P" flag path desc more precise

In reply to Charlie Jenkins

The "full path" is not passed through to the interpreter, but rather whatever path was passed to execve. The user's shell is the mechanism that is converting the executable name "blah" into the full path name of "/usr/local/bin/blah" instead of the kernel. Clarify this in the documentation by noting that the path is found in execve and including "shell" in the conversation for locating "blah".

---
 Documentation/admin-guide/binfmt-misc.rst | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
Documentation/admin-guide/binfmt-misc.rst +10 -10
index 2e2be2922ba6..aabf6599ac49 100644
@@ -56,16 +56,16 @@ Here is what the fields mean:
 
       ``P`` - preserve-argv[0]
             Legacy behavior of binfmt_misc is to overwrite
-            the original argv[0] with the full path to the binary. When this
-            flag is included, binfmt_misc will add an argument to the argument
-            vector for this purpose, thus preserving the original ``argv[0]``.
-            e.g. If your interp is set to ``/bin/foo`` and you run ``blah``
-            (which is in ``/usr/local/bin``), then the kernel will execute
-            ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo",
-            "/usr/local/bin/blah", "blah"]``.  The interp can be aware of this
-            by checking if bit 0 in AT_FLAGS in the auxilary vector is set to 1
-            so it can execute ``/usr/local/bin/blah`` with ``argv[]`` set to
-            ``["blah"]``.
+            the original argv[0] with the path to the binary found in execve.
+            When this flag is included, binfmt_misc will add an argument to the
+            argument vector for this purpose, thus preserving the original
+            ``argv[0]``. e.g. If your interp is set to ``/bin/foo`` and you run
+            ``blah`` (which your shell finds in ``/usr/local/bin``), then the
+            kernel will execute ``/bin/foo`` with ``argv[]`` set to
+            ``["/bin/foo", "/usr/local/bin/blah", "blah"]``.  The interp can be
+            aware of this by checking if bit 0 in AT_FLAGS in the auxilary
+            vector is set to 1 so it can execute ``/usr/local/bin/blah`` with
+            ``argv[]`` set to ``["blah"]``.
       ``O`` - open-binary
 	    Legacy behavior of binfmt_misc is to pass the full path
             of the binary to the interpreter as an argument. When this flag is
Signature · 1 line
2.53.0
maintainer
#3 lore raw
In reply to Charlie Jenkins
Quoted 4 lines · Charlie Jenkins

Improve the wording of the description of the "P" flag to explain that the interpreter gets the path to the file provided by execve and not the full path as well as documenting that AT_FLAGS can be read to see if the "P" flag is set.

Thanks for the clarifications! I'll get this into the execve tree once the merge window is over. (I usually wait for -rc2 to be released.) (Or maybe this should go via linux-doc? I should add this file to the EXEC entry in MAINTAINERS...)

How did you happen across this mismatch(?weakness?) in the docs?

-Kees

Signature · 1 line
Kees Cook
#4 lore raw
Quoted 6 lines · Kees Cook
Quoted 4 lines · Charlie Jenkins

Improve the wording of the description of the "P" flag to explain that the interpreter gets the path to the file provided by execve and not the full path as well as documenting that AT_FLAGS can be read to see if the "P" flag is set.

Quoted 6 lines

Thanks for the clarifications! I'll get this into the execve tree once the merge window is over. (I usually wait for -rc2 to be released.) (Or maybe this should go via linux-doc? I should add this file to the EXEC entry in MAINTAINERS...)

How did you happen across this mismatch(?weakness?) in the docs?

I was writing an interpreter application that was using binfmt-misc and was using this documentation to do so. I was getting unexpected results so I read through the kernel code to figure out what was going on.

- Charlie

Quoted 5 lines

-Kees

Signature · 1 line
Kees Cook