Document direct execution mode for rtld.

Reviewed by:	emaste, jonathan (previous version)
Sponsored by:	The FreeBSD Foundation
MFC after:	3 days
Differential Revision:	https://reviews.freebsd.org/D10826

libexec/rtld-elf/rtld.1

@@ -283,6 +283,77 @@ instead of postponing it until required.
 Normally, the filtees are opened at the time of the first symbol resolution
 from the filter object.
 .El
+.Sh DIRECT EXECUTION MODE
+.Nm
+is typically used implicitly, loaded by the kernel as requested by the
+.Dv PT_INTERP
+program header of the executed binary.
+.Fx
+also supports a direct execution mode for the dynamic linker.
+In this mode, the user explicitly executes
+.Nm
+and provides the path of the program to be linked and executed as
+an argument.
+This mode allows use of a non-standard dynamic linker for a program
+activation without changing the binary or without changing
+the installed dynamic linker.
+Execution options may be specified.
+.Pp
+The syntax of the direct invocation is
+.Bd -ragged -offset indent
+.Pa /libexec/ld-elf.so.1
+.Op Fl f Ar fd
+.Op Fl p
+.Op Fl -
+.Pa image_path
+.Op Ar image arguments
+.Ed
+.Pp
+The options are as follows:
+.Bl -tag -width indent
+.It Fl f Ar fd
+File descriptor
+.Ar fd
+references the binary to be activated by
+.Nm .
+It must already be opened in the process when executing
+.Nm .
+If this option is specified,
+.Ar image_path
+is only used to provide the
+.Va argv[0]
+value to the program.
+.It Fl p
+If the
+.Pa image_path
+argument specifies a name which does not contain a slash
+.Dq Li /
+character,
+.Nm
+uses the search path provided by the environment variable
+.Dv PATH
+to find the binary to execute.
+.It Fl -
+Ends the
+.Nm
+options.
+The argument following
+.Fl -
+is interpreted as the path of binary to execute.
+.El
+.Pp
+To conform to user expectation to not break some naively restricted
+execution environments, in the direct execution mode
+.Nm
+emulates verification of the binary execute permission
+for current user.
+The verification only uses Unix
+.Dv DACs ,
+ignores
+.Dv ACLs
+and is racy by its nature.
+The environments which rely on such restrictions are weak
+and breakable on its own.
 .Sh FILES
 .Bl -tag -width ".Pa /var/run/ld-elf32.so.hints" -compact
 .It Pa /var/run/ld-elf.so.hints