ptrace.2: document PTRACE_GET_SYSCALL_INFO

PTRACE_GET_SYSCALL_INFO request was introduced by Linux kernel commit 201766a20e30f982ccfe36bebfad9602c3ff574a aka v5.3-rc1~65^2~23.

Signed-off-by Dmitry V. Levin <[email protected]>

---
 man2/ptrace.2 | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

man2/ptrace.2 +14 -0

index 8b8daf238..3b774f87b 100644
@@ -1005,6 +1005,27 @@ of the
 .IR "struct user_desc"
 is ignored; in other words,
 this ptrace operation can't be used to allocate a free TLS entry.)
+.TP
+.BR PTRACE_GET_SYSCALL_INFO " (since Linux 5.3)"
+.\" commit 201766a20e30f982ccfe36bebfad9602c3ff574a
+Retrieve information about the syscall that caused the stop.
+The information is placed into the buffer pointed by
+.I data
+argument, which should be a pointer to a buffer of type
+.IR "struct ptrace_syscall_info" .
+The
+.I addr
+argument contains the size of the buffer pointed to
+by
+.I data
+argument (i.e.,

Signed-off-by Dmitry V. Levin <[email protected]>

---
 man2/ptrace.2 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

man2/ptrace.2 +43 -1

index ff897bb19..b030247e6 100644
@@ -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 ,

Hello Dmitry,

Quoted 57 lines · Dmitry V. Levin

Signed-off-by Dmitry V. Levin <[email protected]>

---
 man2/ptrace.2 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

man2/ptrace.2 +43 -1

index ff897bb19..b030247e6 100644
@@ -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 ,

man2/ptrace.2 If the size of the data to be written by the kernel exceeds the size · line 1081

Quoted 10 lines

man2/ptrace.2 +7 -0

+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.

Quoted 73 lines · Michael Kerrisk (man-pages)

Hello Dmitry,

Quoted 57 lines · Dmitry V. Levin

Signed-off-by Dmitry V. Levin <[email protected]>

---
 man2/ptrace.2 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

man2/ptrace.2 +43 -1

index ff897bb19..b030247e6 100644
@@ -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 ,

man2/ptrace.2 If the size of the data to be written by the kernel exceeds the size · line 1081

Quoted 10 lines

man2/ptrace.2 +7 -0

+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.

Quoted 2 lines

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).

Quoted 77 lines · Dmitry V. Levin

Quoted 73 lines · Michael Kerrisk (man-pages)

Hello Dmitry,

Quoted 57 lines · Dmitry V. Levin

Signed-off-by Dmitry V. Levin <[email protected]>

---
 man2/ptrace.2 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

man2/ptrace.2 +43 -1

index ff897bb19..b030247e6 100644
@@ -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 ,

man2/ptrace.2 If the size of the data to be written by the kernel exceeds the size · line 1081

Quoted 10 lines

man2/ptrace.2 +7 -0

+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.

Quoted 2 lines

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.

Quoted 6 lines

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? */