[PATCH 0/3] ptrace.2: explain new commands to work with signals

[PATCH 0/3] ptrace.2: explain new commands to work with signals

[Andrey Vagin]

Andrey Vagin (3):
  ptrace.2: place GETSIGINFO and SETSIGINFO near each other
  ptrace.2: add description for PTRACE_PEEKSIGINFO
  ptrace.2: add description for PTRACE_{GET,SET}SIGMASK

 man2/ptrace.2 | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 66 insertions(+), 12 deletions(-)

-- 
1.8.3.1

[PATCH 1/3] ptrace.2: place GETSIGINFO and SETSIGINFO near each other

[Andrey Vagin]

Signed-off-by: Andrey Vagin <avagin@openvz.org>
---
 man2/ptrace.2 | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index 0d77e3f..5fcac2b 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -255,18 +255,6 @@ On return, the kernel modifies
 .B iov.len
 to indicate the actual number of bytes returned.
 .TP
-.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
-Retrieve information about the signal that caused the stop.
-Copy a
-.I siginfo_t
-structure (see
-.BR sigaction (2))
-from the tracee to the address
-.I data
-in the tracer.
-.RI ( addr
-is ignored.)
-.TP
 .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
 Modify the tracee's general-purpose or floating-point registers,
 respectively, from the address
@@ -301,6 +289,18 @@ and
 is analogous to
 .BR PTRACE_GETREGSET .
 .TP
+.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
+Retrieve information about the signal that caused the stop.
+Copy a
+.I siginfo_t
+structure (see
+.BR sigaction (2))
+from the tracee to the address
+.I data
+in the tracer.
+.RI ( addr
+is ignored.)
+.TP
 .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
 Set signal information:
 copy a
-- 
1.8.3.1

Re: [PATCH 1/3] ptrace.2: place GETSIGINFO and SETSIGINFO near each other

[Michael Kerrisk]

Thanks Andrey. Applied.

M


On 07/16/13 10:19, Andrey Vagin wrote:
> Signed-off-by: Andrey Vagin <avagin@openvz.org>
> ---
>  man2/ptrace.2 | 24 ++++++++++++------------
>  1 file changed, 12 insertions(+), 12 deletions(-)
> 
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index 0d77e3f..5fcac2b 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -255,18 +255,6 @@ On return, the kernel modifies
>  .B iov.len
>  to indicate the actual number of bytes returned.
>  .TP
> -.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
> -Retrieve information about the signal that caused the stop.
> -Copy a
> -.I siginfo_t
> -structure (see
> -.BR sigaction (2))
> -from the tracee to the address
> -.I data
> -in the tracer.
> -.RI ( addr
> -is ignored.)
> -.TP
>  .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
>  Modify the tracee's general-purpose or floating-point registers,
>  respectively, from the address
> @@ -301,6 +289,18 @@ and
>  is analogous to
>  .BR PTRACE_GETREGSET .
>  .TP
> +.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
> +Retrieve information about the signal that caused the stop.
> +Copy a
> +.I siginfo_t
> +structure (see
> +.BR sigaction (2))
> +from the tracee to the address
> +.I data
> +in the tracer.
> +.RI ( addr
> +is ignored.)
> +.TP
>  .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
>  Set signal information:
>  copy a
> 

Re: [PATCH 1/3] ptrace.2: place GETSIGINFO and SETSIGINFO near each other

[Andrew Vagin]

Hi Michael,

On Thu, Jul 18, 2013 at 03:13:39AM +0200, Michael Kerrisk wrote:
> Thanks Andrey. Applied.

You committed one of three patches. What do you think about other
patches?

ptrace.2: add description for PTRACE_PEEKSIGINFO
ptrace.2: add description for PTRACE_{GET,SET}SIGMASK


Thanks,
Andrey

> 
> M
> 
> 
> On 07/16/13 10:19, Andrey Vagin wrote:
> > Signed-off-by: Andrey Vagin <avagin@openvz.org>
> > ---
> >  man2/ptrace.2 | 24 ++++++++++++------------
> >  1 file changed, 12 insertions(+), 12 deletions(-)
> > 
> > diff --git a/man2/ptrace.2 b/man2/ptrace.2
> > index 0d77e3f..5fcac2b 100644
> > --- a/man2/ptrace.2
> > +++ b/man2/ptrace.2
> > @@ -255,18 +255,6 @@ On return, the kernel modifies
> >  .B iov.len
> >  to indicate the actual number of bytes returned.
> >  .TP
> > -.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
> > -Retrieve information about the signal that caused the stop.
> > -Copy a
> > -.I siginfo_t
> > -structure (see
> > -.BR sigaction (2))
> > -from the tracee to the address
> > -.I data
> > -in the tracer.
> > -.RI ( addr
> > -is ignored.)
> > -.TP
> >  .BR PTRACE_SETREGS ", " PTRACE_SETFPREGS
> >  Modify the tracee's general-purpose or floating-point registers,
> >  respectively, from the address
> > @@ -301,6 +289,18 @@ and
> >  is analogous to
> >  .BR PTRACE_GETREGSET .
> >  .TP
> > +.BR PTRACE_GETSIGINFO " (since Linux 2.3.99-pre6)"
> > +Retrieve information about the signal that caused the stop.
> > +Copy a
> > +.I siginfo_t
> > +structure (see
> > +.BR sigaction (2))
> > +from the tracee to the address
> > +.I data
> > +in the tracer.
> > +.RI ( addr
> > +is ignored.)
> > +.TP
> >  .BR PTRACE_SETSIGINFO " (since Linux 2.3.99-pre6)"
> >  Set signal information:
> >  copy a
> > 
> 

[PATCH 2/3] ptrace.2: add description for PTRACE_PEEKSIGINFO

[Andrey Vagin]

Retrieve signals without removing them from a queue.

Signed-off-by: Andrey Vagin <avagin@openvz.org>
---
 man2/ptrace.2 | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index 5fcac2b..e74535e 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -317,6 +317,45 @@ itself.
 .RI ( addr
 is ignored.)
 .TP
+.BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
+.\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
+Retrieve
+.I siginfo_t
+structures without removing signals from a queue.
+.I addr
+points to a
+.I ptrace_peeksiginfo_args
+structure.
+.I siginfo_t
+structures are copied into the buffer starting at
+.I data.
+The return value contains a number of copied signals (zero indicates
+that a signal with this sequence number doesn't exist).
+A result
+.I siginfo
+contains a kernel part of
+.IR si_code
+(
+.BR __SI_CHLD,
+.BR __SI_FAULT,
+etc), which is not shown in other places.
+.PP
+.in +10n
+.nf
+struct ptrace_peeksiginfo_args {
+	u64 off;        /* from which siginfo to start */
+	u32 flags;
+	s32 nr;         /* how may siginfos to take */
+};
+.fi
+
+Currently here is only one flag
+.BR PTRACE_PEEKSIGINFO_SHARED
+for dumping signals from process-wide queue.
+If this flag is not set, signals are read from a per-thread queue.
+.in
+.PP
+.TP
 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
 Set ptrace options from
 .IR data .
-- 
1.8.3.1

Re: [PATCH 2/3] ptrace.2: add description for PTRACE_PEEKSIGINFO

[Michael Kerrisk (man-pages)]

Andrey,


On 07/16/2013 10:19 AM, Andrey Vagin wrote:
> Retrieve signals without removing them from a queue.
> 
> Signed-off-by: Andrey Vagin <avagin@openvz.org>
> ---
>  man2/ptrace.2 | 39 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 39 insertions(+)
> 
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index 5fcac2b..e74535e 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -317,6 +317,45 @@ itself.
>  .RI ( addr
>  is ignored.)
>  .TP
> +.BR PTRACE_PEEKSIGINFO " (since Linux 3.10)"
> +.\" commit 84c751bd4aebbaae995fe32279d3dba48327bad4
> +Retrieve
> +.I siginfo_t
> +structures without removing signals from a queue.
> +.I addr
> +points to a
> +.I ptrace_peeksiginfo_args
> +structure.
> +.I siginfo_t
> +structures are copied into the buffer starting at
> +.I data.
> +The return value contains a number of copied signals (zero indicates
> +that a signal with this sequence number doesn't exist).
> +A result
> +.I siginfo
> +contains a kernel part of
> +.IR si_code
> +(
> +.BR __SI_CHLD,
> +.BR __SI_FAULT,
> +etc), which is not shown in other places.
> +.PP
> +.in +10n
> +.nf
> +struct ptrace_peeksiginfo_args {
> +	u64 off;        /* from which siginfo to start */
> +	u32 flags;
> +	s32 nr;         /* how may siginfos to take */
> +};
> +.fi
> +
> +Currently here is only one flag
> +.BR PTRACE_PEEKSIGINFO_SHARED
> +for dumping signals from process-wide queue.
> +If this flag is not set, signals are read from a per-thread queue.
> +.in
> +.PP
> +.TP
>  .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
>  Set ptrace options from
>  .IR data .

Long after the fact, I've applied this patch. I reworked the text 
somewhat as well. Could you please check that the following is correct:

       PTRACE_PEEKSIGINFO (since Linux 3.10)
              Retrieve  siginfo_t  structures without removing signals
              from a queue.  addr points to a  ptrace_peeksiginfo_args
              structure that specifies the ordinal position from which
              copying of signals should start, and the number of  sig‐
              nals  to copy.  siginfo_t structures are copied into the
              buffer pointed to by data.  The  return  value  contains
              the  number of copied signals (zero indicates that there
              is no signal  corresponding  to  the  specified  ordinal
              position).   Within the returned siginfo structures, the
              si_code   field   includes    information    (__SI_CHLD,
              __SI_FAULT,  etc.),  that  are  not otherwise exposed to
              user space.

                 struct ptrace_peeksiginfo_args {
                     u64 off;    /* Ordinal position in queue at which
                                    to start copying signals */
                     u32 flags;  /* PTRACE_PEEKSIGINFO_SHARED or 0 */
                     s32 nr;     /* Number of signals to copy */
                 };

                 Currently, there is only  one  flag,  PTRACE_PEEKSIG‐
                 INFO_SHARED,  for  dumping  signals from the process-
                 wide signal queue.  If this flag is not set,  signals
                 are  read  from the per-thread queue of the specified
                 thread.

Thanks for the patch!

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH 3/3] ptrace.2: add description for PTRACE_{GET,SET}SIGMASK

[Andrey Vagin]

These two commands allow to examine and change mask of blocked signals.

Signed-off-by: Andrey Vagin <avagin@openvz.org>
---
 man2/ptrace.2 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/man2/ptrace.2 b/man2/ptrace.2
index e74535e..08697ff 100644
--- a/man2/ptrace.2
+++ b/man2/ptrace.2
@@ -356,6 +356,21 @@ If this flag is not set, signals are read from a per-thread queue.
 .in
 .PP
 .TP
+.BR PTRACE_GETSIGMASK " (since Linux 3.11)"
+.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
+Retrieve mask of blocked signals to the address
+.I data.
+The
+.I addr
+argument contains the size of mask.
+.TP
+.BR PTRACE_SETSIGMASK " (since Linux 3.11)"
+Change mask of blocked signals from the address
+.I data.
+The
+.I addr
+argument contains the size of mask.
+.TP
 .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
 Set ptrace options from
 .IR data .
-- 
1.8.3.1

Re: [PATCH 3/3] ptrace.2: add description for PTRACE_{GET,SET}SIGMASK

[Michael Kerrisk (man-pages)]

On 07/16/2013 10:19 AM, Andrey Vagin wrote:
> These two commands allow to examine and change mask of blocked signals.

Thanks, Andrey.

Applied.

Cheers,

Michael


> Signed-off-by: Andrey Vagin <avagin@openvz.org>
> ---
>  man2/ptrace.2 | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/man2/ptrace.2 b/man2/ptrace.2
> index e74535e..08697ff 100644
> --- a/man2/ptrace.2
> +++ b/man2/ptrace.2
> @@ -356,6 +356,21 @@ If this flag is not set, signals are read from a per-thread queue.
>  .in
>  .PP
>  .TP
> +.BR PTRACE_GETSIGMASK " (since Linux 3.11)"
> +.\" commit 29000caecbe87b6b66f144f72111f0d02fbbf0c1
> +Retrieve mask of blocked signals to the address
> +.I data.
> +The
> +.I addr
> +argument contains the size of mask.
> +.TP
> +.BR PTRACE_SETSIGMASK " (since Linux 3.11)"
> +Change mask of blocked signals from the address
> +.I data.
> +The
> +.I addr
> +argument contains the size of mask.
> +.TP
>  .BR PTRACE_SETOPTIONS " (since Linux 2.4.6; see BUGS for caveats)"
>  Set ptrace options from
>  .IR data .
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/