[PATCH] Document how GDB searches for files when using -s, -e, and -se options

[PATCH] Document how GDB searches for files when using -s, -e, and -se options

[Kevin Buettner]

GDB's documentation of the 'file' command says:

    If you do not specify a directory and the file is not found in the
    GDB working directory, GDB uses the environment variable PATH as a
    list of directories to search, just as the shell does when looking
    for a program to run.

The same is true for files specified via commandline options -s, -e,
and -se.

This commit adds similar text to the section of the manual which
discusses these commandline options.
---
 gdb/doc/gdb.texinfo | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 5f09f3a1433..1ef7ed6fcb3 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -962,6 +962,15 @@ If @value{GDBN} has not been configured to included core file support,
 such as for most embedded targets, then it will complain about a second
 argument and ignore it.
 
+For the @samp{-s}, @samp{-e}, and @samp{-se} options, and their long
+form equivalents, if @var{file} does not specify a directory as a
+component of the filename and the file is not found in the
+@value{GDBN} working directory, @value{GDBN} uses the environment
+variable @env{PATH} as a list of directories to search, just as the
+shell does when looking for a program to run.  The search algorithm
+used for these options is identical to that used by the
+@code{symbol-file}, @code{exec-file}, and @code{file} commands.
+
 Many options have both long and short forms; both are shown in the
 following list.  @value{GDBN} also recognizes the long forms if you truncate
 them, so long as enough of the option is present to be unambiguous.
-- 
2.35.3

Re: [PATCH] Document how GDB searches for files when using -s, -e, and -se options

[Eli Zaretskii]

> Date: Thu,  2 Jun 2022 15:40:40 -0700
> From: Kevin Buettner via Gdb-patches <gdb-patches@sourceware.org>
> 
> GDB's documentation of the 'file' command says:
> 
>     If you do not specify a directory and the file is not found in the
>     GDB working directory, GDB uses the environment variable PATH as a
>     list of directories to search, just as the shell does when looking
>     for a program to run.
> 
> The same is true for files specified via commandline options -s, -e,
> and -se.
> 
> This commit adds similar text to the section of the manual which
> discusses these commandline options.

Thanks.  I don't think we need to repeat the same description in the
"File Options" section, we just need to mention this shortly and add a
cross-reference to where the 'file' command's description explains
that.

> +For the @samp{-s}, @samp{-e}, and @samp{-se} options, and their long
> +form equivalents, if @var{file} does not specify a directory as a
> +component of the filename and the file is not found in the
> +@value{GDBN} working directory, @value{GDBN} uses the environment
> +variable @env{PATH} as a list of directories to search, just as the
> +shell does when looking for a program to run.  The search algorithm
> +used for these options is identical to that used by the
> +@code{symbol-file}, @code{exec-file}, and @code{file} commands.

Could you please rewrite the above to be shorter and have a
cross-reference?