linux-kernel - Re: [PATCH 1/2] Add kcmp.2 manpage

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <CAKgNAkj-=wLEM+SjA_S8GUp0+0o5R4NuDH4fL-8H-pKCKdLryA@mail.gmail.com>
Date:	Tue, 18 Dec 2012 17:54:49 +0100
From:	"Michael Kerrisk (man-pages)" <mtk.manpages@...il.com>
To:	Cyrill Gorcunov <gorcunov@...nvz.org>
Cc:	linux-man@...r.kernel.org, linux-kernel@...r.kernel.org,
	"Eric W. Biederman" <ebiederm@...ssion.com>,
	"H. Peter Anvin" <hpa@...or.com>,
	Pavel Emelyanov <xemul@...allels.com>,
	Al Viro <viro@...iv.linux.org.uk>
Subject: Re: [PATCH 1/2] Add kcmp.2 manpage

Hello Cyrill,

On Mon, Jul 23, 2012 at 12:15 AM, Cyrill Gorcunov <gorcunov@...nvz.org> wrote:
> NAME
>        kcmp - compare if two processes do share a particular kernel resource

Very late follow up on this page, sorry. You didn't provide a
copyright or license for this page. Could you please supply that
information. See http://www.kernel.org/doc/man-pages/licenses.html .

Cheers,

Michael

> SYNOPSIS
>        #define _GNU_SOURCE         /* See feature_test_macros(7) */
>        #include <unistd.h>
>        #include <linux/kcmp.h>
>        #include <sys/syscall.h>   /* For SYS_xxx definitions */
>
>        int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);
>
> DESCRIPTION
>        kcmp() allows to find out if two processes identified by pid1 and pid2
>        share kernel resources such as virtual memory, file descriptors, file system etc.
>
>        The comparison type is one of the following
>
>        KCMP_FILE determines whether a file descriptor idx1 in the first process
>        is the same as another descriptor idx2 in the second process
>
>        KCMP_VM compares whether processes share address space
>
>        KCMP_FILES compares the file descriptor arrays to see whether the processes
>        share all files
>
>        KCMP_FS compares whether processes share the file system information (the current
>        umask, working directory, namespace root, etc)
>
>        KCMP_SIGHAND compares whether processes share a signal handlers table
>
>        KCMP_IO compares whether processes do share I/O context, used mainly for
>        block I/O scheduling
>
>        KCMP_SYSVSEM compares the list of undo operations associated with SYSV semaphores
>
>        Note  the  kcmp() is not protected against false positives which may have
>        place if tasks are running.  Which means one should stop tasks being inspected
>        with this syscall to obtain meaningful results.
>
> RETURN VALUE
>        kcmp was designed to return values suitable for sorting.  This is particularly handy
>        when one have to compare a large number of file descriptors.
>
>        The return value is merely a result of simple arithmetic comparison of kernel pointers
>        (when kernel compares resources, it uses their memory addresses).
>
>        The  easiest way to explain is to consider an example.  Lets say v1 and v2 are the
>        addresses of appropriate resources, then the return value is one of the following
>
>        0 - v1 is equal to v2 , in other words we have a shared resource here
>        1 - v1 is less than v2
>        2 - v1 is greater than v2
>        3 - v1 is not equal to but ordering information is unavailble.
>
>        On error, -1 is returned, and errno is set appropriately.
>
> Signed-off-by: Cyrill Gorcunov <gorcunov@...nvz.org>
> CC: "Eric W. Biederman" <ebiederm@...ssion.com>
> CC: "H. Peter Anvin" <hpa@...or.com>
> CC: Pavel Emelyanov <xemul@...allels.com>
> CC: Al Viro <viro@...IV.linux.org.uk>
> Signed-off-by: Cyrill Gorcunov <gorcunov@...nvz.org>
> ---
>  man2/kcmp.2 |  113 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 113 insertions(+), 0 deletions(-)
>  create mode 100644 man2/kcmp.2
>
> diff --git a/man2/kcmp.2 b/man2/kcmp.2
> new file mode 100644
> index 0000000..5d2e9a3
> --- /dev/null
> +++ b/man2/kcmp.2
> @@ -0,0 +1,113 @@
> +.TH KCMP 2 2012-02-01 "Linux" "Linux Programmer's Manual"
> +
> +.SH NAME
> +kcmp \- compare if two processes do share a particular kernel resource
> +
> +.SH SYNOPSIS
> +.nf
> +.BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
> +.B #include <unistd.h>
> +.B #include <linux/kcmp.h>
> +.BR "#include <sys/syscall.h>   "  "/* For SYS_xxx definitions */"
> +
> +.BI "int syscall(__NR_kcmp, pid1, pid2, type, idx1, idx2);"
> +.fi
> +
> +.SH DESCRIPTION
> +
> +.BR kcmp ()
> +allows to find out if two processes identified by
> +.I pid1
> +and
> +.I pid2
> +share kernel resources such as virtual memory, file descriptors, file system etc.
> +
> +The comparison
> +.I type
> +is one of the following
> +
> +.BR KCMP_FILE
> +determines whether a file descriptor
> +.I idx1
> +in the first process is the same as another descriptor
> +.I idx2
> +in the second process
> +
> +.BR KCMP_VM
> +compares whether processes share address space
> +
> +.BR KCMP_FILES
> +compares the file descriptor arrays to see whether the processes share all files
> +
> +.BR KCMP_FS
> +compares whether processes share the file system information (the current umask,
> +working directory, namespace root, etc)
> +
> +.BR KCMP_SIGHAND
> +compares whether processes share a signal handlers table
> +
> +.BR KCMP_IO
> +compares whether processes do share I/O context,
> +used mainly for block I/O scheduling
> +
> +.BR KCMP_SYSVSEM
> +compares the list of undo operations associated with SYSV semaphores
> +
> +Note the
> +.BR kcmp ()
> +is not protected against false positives which may have place if tasks are
> +running.
> +Which means one should stop tasks being inspected with this syscall to obtain
> +meaningful results.
> +
> +.SH "RETURN VALUE"
> +.B kcmp
> +was designed to return values suitable for sorting.
> +This is particularly handy when one have to compare
> +a large number of file descriptors.
> +
> +The return value is merely a result of simple arithmetic comparison
> +of kernel pointers (when kernel compares resources, it uses their
> +memory addresses).
> +
> +The easiest way to explain is to consider an example.
> +Lets say
> +.I v1
> +and
> +.I v2
> +are the addresses of appropriate resources, then the return value
> +is one of the following
> +
> +.B 0
> +\-
> +.I v1
> +is equal to
> +.IR v2 ,
> +in other words we have a shared resource here
> +
> +.B 1
> +\-
> +.I v1
> +is less than
> +.I v2
> +
> +.B 2
> +\-
> +.I v1
> +is greater than
> +.I v2
> +
> +.B 3
> +\-
> +.I v1
> +is not equal to
> +.IR v2 ,
> +but ordering information is unavailable.
> +
> +On error, \-1 is returned, and errno is set appropriately.
> +
> +.SH "CONFORMING TO"
> +.BR kcmp ()
> +is Linux specific and should not be used in programs intended to be portable.
> +.SH "SEE ALSO"
> +.BR clone (2)
> --
> 1.7.7.6
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/