From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.2 required=3.0 tests=HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,MENTIONS_GIT_HOSTING,SPF_HELO_NONE,SPF_PASS, USER_AGENT_SANE_1 autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id EC1D1C32755 for ; Mon, 23 Sep 2019 14:29:54 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id CCD13214DA for ; Mon, 23 Sep 2019 14:29:54 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2394395AbfIWO3y (ORCPT ); Mon, 23 Sep 2019 10:29:54 -0400 Received: from youngberry.canonical.com ([91.189.89.112]:41335 "EHLO youngberry.canonical.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2389590AbfIWO3y (ORCPT ); Mon, 23 Sep 2019 10:29:54 -0400 Received: from [172.58.27.190] (helo=wittgenstein) by youngberry.canonical.com with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.86_2) (envelope-from ) id 1iCPLW-0001df-Gy; Mon, 23 Sep 2019 14:29:47 +0000 Date: Mon, 23 Sep 2019 16:29:34 +0200 From: Christian Brauner To: "Michael Kerrisk (man-pages)" Cc: Oleg Nesterov , Christian Brauner , Jann Horn , "Eric W. Biederman" , Daniel Colascione , Joel Fernandes , linux-man , Linux API , lkml Subject: Re: For review: pidfd_send_signal(2) manual page Message-ID: <20190923142932.2gujbddnzyp4ujeu@wittgenstein> References: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: NeoMutt/20180716 Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, Sep 23, 2019 at 11:12:00AM +0200, Michael Kerrisk (man-pages) wrote: > Hello Christian and all, > > Below, I have the rendered version of the current draft of > the pidfd_send_signal(2) manual page that I have written. > The page source can be found in a Git branch at: > https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=draft_pidfd > > I would be pleased to receive corrections and notes on any > details that should be added. (For example, are there error > cases that I have missed?) > > Would you be able to review please? Michael, A big big thank you for doing this! Really appreciated. I'm happy to review this! > > Thanks, > > Michael > > > NAME > pidfd_send_signal - send a signal to a process specified by a file > descriptor > > SYNOPSIS > int pidfd_send_signal(int pidfd, int sig, siginfo_t info, > unsigned int flags); > > DESCRIPTION > The pidfd_send_signal() system call sends the signal sig to the > target process referred to by pidfd, a PID file descriptor that > refers to a process. > > If the info argument points to a siginfo_t buffer, that buffer > should be populated as described in rt_sigqueueinfo(2). > > If the info argument is a NULL pointer, this is equivalent to > specifying a pointer to a siginfo_t buffer whose fields match the > values that are implicitly supplied when a signal is sent using > kill(2): > > * si_signo is set to the signal number; > * si_errno is set to 0; > * si_code is set to SI_USER; > * si_pid is set to the caller's PID; and > * si_uid is set to the caller's real user ID. > > The calling process must either be in the same PID namespace as > the process referred to by pidfd, or be in an ancestor of that > namespace. > > The flags argument is reserved for future use; currently, this > argument must be specified as 0. > > RETURN VALUE > On success, pidfd_send_signal() returns 0. On success, -1 is This should probably be "On error, -1 is [...]". > returned and errno is set to indicate the cause of the error. > > ERRORS > EBADF pidfd is not a valid PID file descriptor. > > EINVAL sig is not a valid signal. > > EINVAL The calling process is not in a PID namespace from which it > can send a signal to the target process. > > EINVAL flags is not 0. > > EPERM The calling process does not have permission to send the > signal to the target process. > > EPERM pidfd doesn't refer to the calling process, and > info.si_code is invalid (see rt_sigqueueinfo(2)). > > ESRCH The target process does not exist. > > VERSIONS > pidfd_send_signal() first appeared in Linux 5.1. > > CONFORMING TO > pidfd_send_signal() is Linux specific. > > NOTES > Currently, there is no glibc wrapper for this system call; call it > using syscall(2). > > PID file descriptors > The pidfd argument is a PID file descriptor, a file descriptor > that refers to process. Such a file descriptor can be obtained > in any of the following ways: > > * by opening a /proc/[pid] directory; > > * using pidfd_open(2); or > > * via the PID file descriptor that is returned by a call to > clone(2) or clone3(2) that specifies the CLONE_PIDFD flag. > > The pidfd_send_signal() system call allows the avoidance of race > conditions that occur when using traditional interfaces (such as > kill(2)) to signal a process. The problem is that the traditional > interfaces specify the target process via a process ID (PID), with > the result that the sender may accidentally send a signal to the > wrong process if the originally intended target process has termi‐ > nated and its PID has been recycled for another process. By con‐ > trast, a PID file descriptor is a stable reference to a specific > process; if that process terminates, then the file descriptor > ceases to be valid and the caller of pidfd_send_signal() is > informed of this fact via an ESRCH error. > > EXAMPLE > #define _GNU_SOURCE > #include > #include > #include > #include > #include > #include > #include > #include > > #ifndef __NR_pidfd_send_signal > #define __NR_pidfd_send_signal 424 > #endif > > static > int pidfd_send_signal(int pidfd, int sig, siginfo_t *info, > unsigned int flags) > { > return syscall(__NR_pidfd_send_signal, pidfd, sig, info, flags); > } > > int > main(int argc, char *argv[]) > { > siginfo_t info; > char path[PATH_MAX]; > int pidfd, sig; > > if (argc != 3) { > fprintf(stderr, "Usage: %s \n", argv[0]); > exit(EXIT_FAILURE); > } > > sig = atoi(argv[2]); > > /* Obtain a PID file descriptor by opening the /proc/PID directory > of the target process */ > > snprintf(path, sizeof(path), "/proc/%s", argv[1]); > > pidfd = open(path, O_RDONLY); > if (pidfd == -1) { > perror("open"); > exit(EXIT_FAILURE); > } > > /* Populate a 'siginfo_t' structure for use with > pidfd_send_signal() */ > > memset(&info, 0, sizeof(info)); > info.si_code = SI_QUEUE; > info.si_signo = sig; > info.si_errno = 0; > info.si_uid = getuid(); > info.si_pid = getpid(); > info.si_value.sival_int = 1234; > > /* Send the signal */ > > if (pidfd_send_signal(pidfd, sig, &info, 0) == -1) { > perror("pidfd_send_signal"); > exit(EXIT_FAILURE); > } > > exit(EXIT_SUCCESS); > } > > SEE ALSO > clone(2), kill(2), pidfd_open(2), rt_sigqueueinfo(2), sigac‐ > tion(2), pid_namespaces(7), signal(7) >