Re: [PATCH] ptrace.2: document struct ptrace_syscall_info

["Dmitry V. Levin" <ldv@altlinux.org>]

On Thu, Sep 12, 2019 at 11:17:52AM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Dmitry,
> 
> On 9/11/19 7:38 PM, Dmitry V. Levin wrote:
> > Signed-off-by: Dmitry V. Levin <ldv@altlinux.org>
> > ---
> >  man2/ptrace.2 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
> >  1 file changed, 50 insertions(+), 1 deletion(-)
> > 
> > diff --git a/man2/ptrace.2 b/man2/ptrace.2
> > index ff897bb19..b030247e6 100644
> > --- a/man2/ptrace.2
> > +++ b/man2/ptrace.2
> > @@ -1026,7 +1026,56 @@ If the size of the data to be written by the kernel exceeds the size
> >  specified by the
> >  .I addr
> >  argument, the output data is truncated.
> > -.\" FIXME Document 'struct ptrace_syscall_info'
> > +.IP
> > +The
> > +.I ptrace_syscall_info
> > +structure contains the following fields:
> > +.IP
> > +.in
> > +.EX
> > +struct ptrace_syscall_info {
> > +    __u8 op;                    /* PTRACE_SYSCALL_INFO_* value
> > +                                   describing the kind
> > +                                   of system call stop,
> > +                                   see <linux/ptrace.h> */
> > +    __u32 arch;                 /* AUDIT_ARCH_* value,
> > +                                   see seccomp(2) */
> > +    __u64 instruction_pointer;  /* CPU instruction pointer */
> > +    __u64 stack_pointer;        /* CPU stack pointer */
> > +    union {
> > +        struct {
> > +            __u64 nr;           /* System call number */
> > +            __u64 args[6];      /* System call arguments */
> > +        } entry;                /* Information specific to
> > +                                   system call entry stops */
> > +        struct {
> > +            __s64 rval;         /* System call return value */
> > +            __u8 is_error;      /* System call error flag */
> > +        } exit;                 /* Information specific to
> > +                                   system call exit stops */
> > +        struct {
> > +            __u64 nr;           /* System call number */
> > +            __u64 args[6];      /* System call arguments */
> > +            __u32 ret_data;     /* The SECCOMP_RET_DATA portion
> > +                                   of SECCOMP_RET_TRACE return
> > +                                   value */
> > +        } seccomp;              /* Information specific to
> > +                                   PTRACE_EVENT_SECCOMP stops */
> > +    };
> > +};
> > +.EE
> > +.in
> > +.IP
> > +.IR op ,
> > +.IR arch ,
> > +.IR instruction_pointer ,
> > +and
> > +.I stack_pointer
> > +fields are defined for all kinds of ptrace system call stops.
> > +The rest of the structure is a union, one should read only those fields
> > +that are meaningful for the kind of system call stop specified by the
> > +.IR op
> > +field.
> >  .\"
> >  .SS Death under ptrace
> >  When a (possibly multithreaded) process receives a killing signal
> 
> Thanks. I've applied, and done some light editing.
> 
> I also added some pieces. Could you please take a look at commits
> f04534d22c69 [1] and 227a3682312 [2] let me know if they are okay.

Thanks.  The only thing that needs correction is
"Boolean: is rval != 0?" comment about is_error field.

In fact, is_error is a boolean that tells whether rval field
contains a non-error return value (e.g. file descriptor) or
an error value (e.g. -ERRORCODE).


-- 
ldv