* [PATCH] ptrace.2: document PTRACE_GET_SYSCALL_INFO @ 2019-09-02 12:38 Dmitry V. Levin 2019-09-10 10:51 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 7+ messages in thread From: Dmitry V. Levin @ 2019-09-02 12:38 UTC (permalink / raw) To: Michael Kerrisk; +Cc: Elvira Khabirova, linux-man 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 <ldv@altlinux.org> --- man2/ptrace.2 | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/man2/ptrace.2 b/man2/ptrace.2 index 8b8daf238..3b774f87b 100644 --- a/man2/ptrace.2 +++ b/man2/ptrace.2 @@ -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., +.IR "sizeof(struct ptrace_syscall_info)" ). +The return value contains the number of bytes available +to be written by the kernel. +If the size of data to be written by the kernel exceeds the size +specified by +.I addr +argument, the output is truncated. .\" .SS Death under ptrace When a (possibly multithreaded) process receives a killing signal -- ldv ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] ptrace.2: document PTRACE_GET_SYSCALL_INFO 2019-09-02 12:38 [PATCH] ptrace.2: document PTRACE_GET_SYSCALL_INFO Dmitry V. Levin @ 2019-09-10 10:51 ` Michael Kerrisk (man-pages) 2019-09-11 17:38 ` [PATCH] ptrace.2: document struct ptrace_syscall_info Dmitry V. Levin 0 siblings, 1 reply; 7+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-09-10 10:51 UTC (permalink / raw) To: Dmitry V. Levin; +Cc: mtk.manpages, Elvira Khabirova, linux-man Hello Dmitry, On 9/2/19 2:38 PM, Dmitry V. Levin wrote: > 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 <ldv@altlinux.org> > --- > man2/ptrace.2 | 21 +++++++++++++++++++++ > 1 file changed, 21 insertions(+) > > diff --git a/man2/ptrace.2 b/man2/ptrace.2 > index 8b8daf238..3b774f87b 100644 > --- a/man2/ptrace.2 > +++ b/man2/ptrace.2 > @@ -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., > +.IR "sizeof(struct ptrace_syscall_info)" ). > +The return value contains the number of bytes available > +to be written by the kernel. > +If the size of data to be written by the kernel exceeds the size > +specified by > +.I addr > +argument, the output is truncated. > .\" > .SS Death under ptrace > When a (possibly multithreaded) process receives a killing signal Thanks for this patch. I've applied, tweaked the wording very slightly, and pushed. However, this patch lacks an important piece: documentation of 'struct ptrace_syscall_info'. I could take a shot at this, but I see you already wrote a test program for this ptrace operation. Would you be willing to add a patch that documents the structure? Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* [PATCH] ptrace.2: document struct ptrace_syscall_info 2019-09-10 10:51 ` Michael Kerrisk (man-pages) @ 2019-09-11 17:38 ` Dmitry V. Levin 2019-09-12 9:17 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 7+ messages in thread From: Dmitry V. Levin @ 2019-09-11 17:38 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: Elvira Khabirova, linux-man 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 -- ldv ^ permalink raw reply related [flat|nested] 7+ messages in thread
* Re: [PATCH] ptrace.2: document struct ptrace_syscall_info 2019-09-11 17:38 ` [PATCH] ptrace.2: document struct ptrace_syscall_info Dmitry V. Levin @ 2019-09-12 9:17 ` Michael Kerrisk (man-pages) 2019-09-13 15:40 ` Dmitry V. Levin 0 siblings, 1 reply; 7+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-09-12 9:17 UTC (permalink / raw) To: Dmitry V. Levin; +Cc: mtk.manpages, Elvira Khabirova, linux-man 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/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] ptrace.2: document struct ptrace_syscall_info 2019-09-12 9:17 ` Michael Kerrisk (man-pages) @ 2019-09-13 15:40 ` Dmitry V. Levin 2019-09-13 18:48 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 7+ messages in thread From: Dmitry V. Levin @ 2019-09-13 15:40 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: Elvira Khabirova, linux-man 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 ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] ptrace.2: document struct ptrace_syscall_info 2019-09-13 15:40 ` Dmitry V. Levin @ 2019-09-13 18:48 ` Michael Kerrisk (man-pages) 2019-09-13 19:37 ` Dmitry V. Levin 0 siblings, 1 reply; 7+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-09-13 18:48 UTC (permalink / raw) To: Dmitry V. Levin; +Cc: mtk.manpages, Elvira Khabirova, linux-man 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/ ^ permalink raw reply [flat|nested] 7+ messages in thread
* Re: [PATCH] ptrace.2: document struct ptrace_syscall_info 2019-09-13 18:48 ` Michael Kerrisk (man-pages) @ 2019-09-13 19:37 ` Dmitry V. Levin 0 siblings, 0 replies; 7+ messages in thread From: Dmitry V. Levin @ 2019-09-13 19:37 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: Elvira Khabirova, linux-man On Fri, Sep 13, 2019 at 08:48:21PM +0200, Michael Kerrisk (man-pages) wrote: > 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? */ Yes, that's better, thanks. -- ldv ^ permalink raw reply [flat|nested] 7+ messages in thread
end of thread, other threads:[~2019-09-13 19:37 UTC | newest] Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2019-09-02 12:38 [PATCH] ptrace.2: document PTRACE_GET_SYSCALL_INFO Dmitry V. Levin 2019-09-10 10:51 ` Michael Kerrisk (man-pages) 2019-09-11 17:38 ` [PATCH] ptrace.2: document struct ptrace_syscall_info Dmitry V. Levin 2019-09-12 9:17 ` Michael Kerrisk (man-pages) 2019-09-13 15:40 ` Dmitry V. Levin 2019-09-13 18:48 ` Michael Kerrisk (man-pages) 2019-09-13 19:37 ` Dmitry V. Levin
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).