diff mbox

[4/4] Update documentation on catching a group of related syscalls.

Message ID 1414956944-8856-5-git-send-email-gabriel@krisman.be
State New
Headers show

Commit Message

Gabriel Krisman Bertazi Nov. 2, 2014, 7:35 p.m. UTC
gdb/

	* breakpoint.c (_initialize_breakpoint): Update catch syscall
	command documentation.
	* NEWS: Include section about catching groups of syscalls.

gdb/doc/

	* gdb.texinfo (Set Catchpoints): Add 'group' argument to catch
	syscall.
---
 gdb/NEWS            |  5 +++++
 gdb/breakpoint.c    | 10 +++++-----
 gdb/doc/gdb.texinfo |  8 +++++++-
 3 files changed, 17 insertions(+), 6 deletions(-)

Comments

Eli Zaretskii Nov. 2, 2014, 7:45 p.m. UTC | #1
> From: Gabriel Krisman Bertazi <gabriel@krisman.be>
> Cc: Gabriel Krisman Bertazi <gabriel@krisman.be>
> Date: Sun,  2 Nov 2014 17:35:44 -0200
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index 649c29e..edea1ff 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS

This part is OK.

>  @item syscall
> -@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{} 
> +@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @var{group:groupname} @r{|} @var{g:groupname}@r{]} @dots{}

Only "groupname" should be in @var, the "g:" and "group:" prefixes are
literal strings, so they should be in @r{}, like the brackets.

> +You may specify a group of related syscalls to be caught at once
> +using the @code{group:} syntax (@code{g:} is a shorter equivalent.).
> +For instance, on some platforms GDB allows you to catch all network
                                   ^^^
"@value{GDBN}"

> +related syscalls, by passing the argument @code{group:network} to
> +@code{catch syscall}.

How does one know which groups, if any, exist?

Thanks.
Sergio Durigan Junior Nov. 3, 2014, 6:38 p.m. UTC | #2
On Sunday, November 02 2014, Gabriel Krisman Bertazi wrote:

> diff --git a/gdb/NEWS b/gdb/NEWS
> index 649c29e..edea1ff 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -60,6 +60,11 @@ SGI Irix-6.x				mips-*-irix6*
>  VAX running (4.2 - 4.3 Reno) BSD 	vax-*-bsd*
>  VAX running Ultrix 			vax-*-ultrix*
>  
> +* Catch syscall catches groups of related syscalls.
> +
> +  Catch syscall command supports catching a group of related
> +  syscalls using the 'group:' or 'g:' prefix.
> +

Yay, thanks for the patch.  Almost there!

Hmm, I would prefer not to use capital letters when naming commands.
How about:

* The "catch syscall" command now supports catching groups of relates
  system calls, using the "group:" or "g:" prefixes.

?

> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 15c2908..ca16e11 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -4254,7 +4254,7 @@ A call to @code{exec}.  This is currently only available for HP-UX
>  and @sc{gnu}/Linux.
>  
>  @item syscall
> -@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{} 
> +@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @var{group:groupname} @r{|} @var{g:groupname}@r{]} @dots{}
>  @kindex catch syscall
>  @cindex break on a system call.
>  A call to or return from a system call, a.k.a.@: @dfn{syscall}.  A
> @@ -4289,6 +4289,12 @@ may be useful if @value{GDBN}'s database does not have the complete
>  list of syscalls on your system (e.g., because @value{GDBN} lags
>  behind the OS upgrades).
>  
> +You may specify a group of related syscalls to be caught at once
> +using the @code{group:} syntax (@code{g:} is a shorter equivalent.).
> +For instance, on some platforms GDB allows you to catch all network
> +related syscalls, by passing the argument @code{group:network} to
> +@code{catch syscall}.
> +

Aside from Eli's comments, I would really like to see an example of how
to use this feature in the manual.

Thanks,
Gabriel Krisman Bertazi Nov. 12, 2014, 2:04 a.m. UTC | #3
Eli Zaretskii <eliz@gnu.org> writes:

>> From: Gabriel Krisman Bertazi <gabriel@krisman.be>
>> Cc: Gabriel Krisman Bertazi <gabriel@krisman.be>
>> Date: Sun,  2 Nov 2014 17:35:44 -0200
>> 
>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index 649c29e..edea1ff 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>
> This part is OK.

Eli,

Thanks for your review.

>> +related syscalls, by passing the argument @code{group:network} to
>> +@code{catch syscall}.
>
> How does one know which groups, if any, exist?
>

Indeed, as I said in part 0, I don't provide any way to list which group
exists, other than the usual word completion.  The reason is that catch
syscall does not provide a way to list system calls and we couldn't
agree on the right syntax for this feature on the RFC I sent earlier to
this list.

Maybe I could rewrite this part of the documentation to suggest
something like "Tab is your friend". WDYT? :)
Eli Zaretskii Nov. 12, 2014, 3:47 a.m. UTC | #4
> From: Gabriel Krisman Bertazi <gabriel@krisman.be>
> Cc: gdb-patches@sourceware.org
> Date: Wed, 12 Nov 2014 00:04:28 -0200
> 
> >> +related syscalls, by passing the argument @code{group:network} to
> >> +@code{catch syscall}.
> >
> > How does one know which groups, if any, exist?
> >
> 
> Indeed, as I said in part 0, I don't provide any way to list which group
> exists, other than the usual word completion.  The reason is that catch
> syscall does not provide a way to list system calls and we couldn't
> agree on the right syntax for this feature on the RFC I sent earlier to
> this list.
> 
> Maybe I could rewrite this part of the documentation to suggest
> something like "Tab is your friend". WDYT? :)

Yes, saying that TAB-completion (including M-TAB) can be used to see
the list of groups is fine with me.

Thanks.
diff mbox

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 649c29e..edea1ff 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -60,6 +60,11 @@  SGI Irix-6.x				mips-*-irix6*
 VAX running (4.2 - 4.3 Reno) BSD 	vax-*-bsd*
 VAX running Ultrix 			vax-*-ultrix*
 
+* Catch syscall catches groups of related syscalls.
+
+  Catch syscall command supports catching a group of related
+  syscalls using the 'group:' or 'g:' prefix.
+
 *** Changes in GDB 7.8
 
 * New command line options
diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index 8520361..9bd3519 100644
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -16736,11 +16736,11 @@  If REGEX is given, only stop for libraries matching the regular expression."),
 		     CATCH_PERMANENT,
 		     CATCH_TEMPORARY);
   add_catch_command ("syscall", _("\
-Catch system calls by their names and/or numbers.\n\
-Arguments say which system calls to catch.  If no arguments\n\
-are given, every system call will be caught.\n\
-Arguments, if given, should be one or more system call names\n\
-(if your system supports that), or system call numbers."),
+Catch system calls by their names, groups and/or numbers.  Arguments\n\
+say which system calls to catch.  If no arguments are given, every\n\
+system call will be caught.  Arguments, if given, should be one or\n\
+more system call names (if your system supports that), system call\n\
+groups or system call numbers."),
 		     catch_syscall_command_1,
 		     catch_syscall_completer,
 		     CATCH_PERMANENT,
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 15c2908..ca16e11 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -4254,7 +4254,7 @@  A call to @code{exec}.  This is currently only available for HP-UX
 and @sc{gnu}/Linux.
 
 @item syscall
-@itemx syscall @r{[}@var{name} @r{|} @var{number}@r{]} @dots{} 
+@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @var{group:groupname} @r{|} @var{g:groupname}@r{]} @dots{}
 @kindex catch syscall
 @cindex break on a system call.
 A call to or return from a system call, a.k.a.@: @dfn{syscall}.  A
@@ -4289,6 +4289,12 @@  may be useful if @value{GDBN}'s database does not have the complete
 list of syscalls on your system (e.g., because @value{GDBN} lags
 behind the OS upgrades).
 
+You may specify a group of related syscalls to be caught at once
+using the @code{group:} syntax (@code{g:} is a shorter equivalent.).
+For instance, on some platforms GDB allows you to catch all network
+related syscalls, by passing the argument @code{group:network} to
+@code{catch syscall}.
+
 The example below illustrates how this command works if you don't provide
 arguments to it: