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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

On 9/13/19 5:40 PM, Dmitry V. Levin wrote:
> 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).

Thanks for checking this Dmitry. I see what I missed before.
I've now changed the text here to be:

            __u8 is_error;     /* System call error flag;
                                  Boolean: does rval contain
                                  an error value (\-ERRCODE) or
                                  a nonerror return value? */

Thanks,

Michael



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