[PATCH man] kcmp: Add KCMP_EPOLL_TFD description

[PATCH man] kcmp: Add KCMP_EPOLL_TFD description

[Cyrill Gorcunov]

       KCMP_EPOLL_TFD
              Check whether the file descriptor idx1 of process pid1 present in epoll(7)
              instance described by idx2 of process  pid2.   The  argument  idx2  is  an
              address of structure where the target file is described.

                  struct kcmp_epoll_slot {
                       __u32 efd;
                       __u32 tfd;
                       __u64 toff;
                  };

              where  efd  is  epoll  file descriptor from epoll_create(2) call, tfd is a
              target file number, toff is a target file offset counted from zero.   Sev‐
              eral  different  targets  may  be registered with the same file descriptor
              number and setting specific offset helps to investigate each of them.

Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
---
 man2/kcmp.2 |   48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

Index: man-pages/man2/kcmp.2
===================================================================
--- man-pages.orig/man2/kcmp.2
+++ man-pages/man2/kcmp.2
@@ -156,6 +156,44 @@ See the discussion of the
 .BR CLONE_VM
 flag in
 .BR clone (2).
+.TP
+.BR KCMP_EPOLL_TFD
+Check whether the file descriptor
+.I idx1
+of the process
+.I pid1
+present in
+.BR epoll (7)
+instance described by
+.I idx2
+of the process
+.IR pid2 .
+The argument
+.I idx2
+is an address of a structure where the target file is described.
+.in +4n
+.nf
+.sp
+struct kcmp_epoll_slot {
+	__u32 efd;
+	__u32 tfd;
+	__u64 toff;
+};
+.fi
+.in
+.sp
+where
+.I efd
+is epoll file descriptor from
+.BR epoll_create (2)
+call,
+.I tfd
+is a target file number,
+.I toff
+is a target file offset counted from zero.
+Several different targets may be registered with
+the same file descriptor number and setting specific
+offset helps to investigate each of them.
 .PP
 Note the
 .BR kcmp ()
@@ -246,6 +284,16 @@ Process
 or
 .I pid2
 does not exist.
+.TP
+.B EFAULT
+The epoll slot addressed by
+.I idx2
+is outside of the user's address space.
+.TP
+.B ENOENT
+The target file is not present in
+.BR epoll ()
+instance.
 .SH VERSIONS
 The
 .BR kcmp ()

Re: [PATCH man] kcmp: Add KCMP_EPOLL_TFD description

[Michael Kerrisk (man-pages)]

Hello Cyril,


On 08/06/2017 09:38 AM, Cyrill Gorcunov wrote:
>        KCMP_EPOLL_TFD
>               Check whether the file descriptor idx1 of process pid1 present in epoll(7)
>               instance described by idx2 of process  pid2.   The  argument  idx2  is  an
>               address of structure where the target file is described.
> 
>                   struct kcmp_epoll_slot {
>                        __u32 efd;
>                        __u32 tfd;
>                        __u64 toff;
>                   };
> 
>               where  efd  is  epoll  file descriptor from epoll_create(2) call, tfd is a
>               target file number, toff is a target file offset counted from zero.   Sev‐
>               eral  different  targets  may  be registered with the same file descriptor
>               number and setting specific offset helps to investigate each of them.

Thanks. I've applied this patch. Is there some example program that
demonstrates the use of this feature?

Cheers,

Michael


> Signed-off-by: Cyrill Gorcunov <gorcunov-GEFAQzZX7r8dnm+yROfE0A@public.gmane.org>
> ---
>  man2/kcmp.2 |   48 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
> 
> Index: man-pages/man2/kcmp.2
> ===================================================================
> --- man-pages.orig/man2/kcmp.2
> +++ man-pages/man2/kcmp.2
> @@ -156,6 +156,44 @@ See the discussion of the
>  .BR CLONE_VM
>  flag in
>  .BR clone (2).
> +.TP
> +.BR KCMP_EPOLL_TFD
> +Check whether the file descriptor
> +.I idx1
> +of the process
> +.I pid1
> +present in
> +.BR epoll (7)
> +instance described by
> +.I idx2
> +of the process
> +.IR pid2 .
> +The argument
> +.I idx2
> +is an address of a structure where the target file is described.
> +.in +4n
> +.nf
> +.sp
> +struct kcmp_epoll_slot {
> +	__u32 efd;
> +	__u32 tfd;
> +	__u64 toff;
> +};
> +.fi
> +.in
> +.sp
> +where
> +.I efd
> +is epoll file descriptor from
> +.BR epoll_create (2)
> +call,
> +.I tfd
> +is a target file number,
> +.I toff
> +is a target file offset counted from zero.
> +Several different targets may be registered with
> +the same file descriptor number and setting specific
> +offset helps to investigate each of them.
>  .PP
>  Note the
>  .BR kcmp ()
> @@ -246,6 +284,16 @@ Process
>  or
>  .I pid2
>  does not exist.
> +.TP
> +.B EFAULT
> +The epoll slot addressed by
> +.I idx2
> +is outside of the user's address space.
> +.TP
> +.B ENOENT
> +The target file is not present in
> +.BR epoll ()
> +instance.
>  .SH VERSIONS
>  The
>  .BR kcmp ()
> 


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

Re: [PATCH man] kcmp: Add KCMP_EPOLL_TFD description

[Cyrill Gorcunov]

On Tue, Aug 15, 2017 at 09:49:47PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Cyril,
> 
> 
> On 08/06/2017 09:38 AM, Cyrill Gorcunov wrote:
> >        KCMP_EPOLL_TFD
> >               Check whether the file descriptor idx1 of process pid1 present in epoll(7)
> >               instance described by idx2 of process  pid2.   The  argument  idx2  is  an
> >               address of structure where the target file is described.
> > 
> >                   struct kcmp_epoll_slot {
> >                        __u32 efd;
> >                        __u32 tfd;
> >                        __u64 toff;
> >                   };
> > 
> >               where  efd  is  epoll  file descriptor from epoll_create(2) call, tfd is a
> >               target file number, toff is a target file offset counted from zero.   Sev‐
> >               eral  different  targets  may  be registered with the same file descriptor
> >               number and setting specific offset helps to investigate each of them.
> 
> Thanks. I've applied this patch. Is there some example program that
> demonstrates the use of this feature?

Well, not as its own. There are a series floating around for CRIU not merged
yet since I need to rebase it on new CRIU release and resend, but there is
a sample https://lists.openvz.org/pipermail/criu/2017-February/036041.html
- the file added into epoll, then dup'ed and original is closed, so kcmp
with dup'ed instance should match kcmp call.

If you can wait I'll try to find some time on the week and rather update
kernel selftests for this new kcmp mode and CC you on the patch. Sounds OK?