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

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

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,

Michael

[1] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=f04534d22c69a947c3cfee82b9a683e772e913b4
[2] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=227a3682312212c8848e9e972a1f923c6a8ad531

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