Re: [PATCH 5/5] Document the 'info proc files' command.

[Eli Zaretskii <eliz@gnu.org>]

> From: John Baldwin <jhb@FreeBSD.org>
> Date: Fri,  7 Sep 2018 17:36:59 -0700
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 75436b0fc3..f5ea98ac52 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -51,6 +51,9 @@ maint set dwarf unwinders (on|off)
>  maint show dwarf unwinders
>    Control whether DWARF unwinders can be used.
>  
> +info proc files
> +  Display a list of open files for a process.
> +

This is OK.

> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index f2d1155b4d..42c077aa69 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -22236,6 +22236,14 @@ supported on @sc{gnu}/Linux and FreeBSD.
>  Show the name of executable of the process.  This command is supported
>  on @sc{gnu}/Linux and FreeBSD.
>  
> +@item info proc files
> +@cindex info proc files
> +Report the open file descriptors accessible in the program.  Each

Not "accessible in", "open by", right?  "Accessible" is ambiguous, it
could mean "can potentially be accessed", and that is not what is
shown here, AFAIU.

> +entry displays the index and type of each descriptor.  The file name

By "index", I guess you meant the value of the descriptor, is that
right?

> +is also listed for descriptors with an associated file name.  Network
> +socket descriptors display the socket addresses in place of the file
> +name.

From the example you have shown (btw, why not show it in the manual?),
I understand that the Name field is always present, and is either a
file or directory name, or the protocol and socket address.  If that
is indeed correct, I suggest to reword the description:

  Show the file descriptors open by the process.  For each open file
  descriptor, @value{GDBN} shows its number, type (file, directory,
  character device, socket), offset, and the name of the resource open
  on the descriptor.  The resource name can be a file name (for files,
  directories, and devices) or a protocol followed by socket address
  (for network connections).

This lacks the details about "offset", which you didn't describe, and
I couldn't guess.

>        This command is supported on FreeBSD.

Only on FreeBSD?

I actually suggest to say something more future-proof, like "this
command is supported only on some systems".

Thanks.