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=-12.5 required=3.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED,DKIM_SIGNED,DKIM_VALID,FREEMAIL_FORGED_FROMDOMAIN, FREEMAIL_FROM,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT 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 33137C5519F for ; Sat, 14 Nov 2020 22:22:42 +0000 (UTC) Received: from merlin.infradead.org (merlin.infradead.org [205.233.59.134]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id CC4602245F for ; Sat, 14 Nov 2020 22:22:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="Yf46PJGl"; dkim=fail reason="signature verification failed" (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="hnY5QsME" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org CC4602245F Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: mail.kernel.org; spf=none smtp.mailfrom=linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=merlin.20170209; h=Sender:Content-Transfer-Encoding: Content-Type:Cc:List-Subscribe:List-Help:List-Post:List-Archive: List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To:Message-Id:Date: Subject:To:From:Reply-To:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Owner; bh=ePhQHLb4SrkPDizOfYZ558jEOrYsdzhMyYUoklvhVcI=; b=Yf46PJGlgrpqVrwL1fiwW921q GCEXRBQyzNqJriyui8f4IxrHWRTH4BAo5s4SJcFofvjVgGvhMlLvCrDqOnAWdOEI+eNEfgXDxbtze oMH0pSSlaVPwzK6XmSV7foYg1Gxv6vViNZXZisYScCFUugpIJ86HHARRBLNt+HhhIp69vbWP4TBeY JQgQwVW3YLIh+gCRQRNXny+qUURKo9okLJ3Cbc/Ef/oMJ0Axe0koqqM2eDWk8mMbOMIoQXzlBxInq g6kzlPM7qhLVmCXG78dqBgAlYdiG75NJp0/BN5UTpOr626nF/oaBMgG9brMxJV5ariHWp3lehAFYd YCSj9xDuQ==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1ke3vw-0004hP-HL; Sat, 14 Nov 2020 22:22:12 +0000 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1ke3vu-0004h1-6b for linux-arm-kernel@lists.infradead.org; Sat, 14 Nov 2020 22:22:11 +0000 Received: by mail-wm1-x32e.google.com with SMTP id a65so19971872wme.1 for ; Sat, 14 Nov 2020 14:22:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=3ssMnzK9+Tf5itgz6j0CoOgfa2ffAC9LTASibshJr7o=; b=hnY5QsMEXhC2aY5D4KCLUqThyzz7f6UwD5tvwgjGjlyXfzwk4khtvneMwXflhb1i/h o+DDeo0ocgQyx/46vED99y/hQxpNZUf+pEZ6McAYDkKk9R/K0cEFQpZNNpPW6Tz3eiVS mVNEAhuOdDS4nZcfwDd5wr+u6KQTF2EIquOb7Ka5ZLB0vKWXBionjLFBmn6fqTzlzzOK QSSRUdpOhZG+si0IXh1R0tOhx7lvONO0xsrvZgg22Del1ZrRh4AOQMPdG9xf/logGRQ+ kiUGwz3PcnVt5EzVG1/4e+FUkpLtD8tvu4ohYVHBmqKLCDuBgwz49nsPYF8GpzScF+E5 F80g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=3ssMnzK9+Tf5itgz6j0CoOgfa2ffAC9LTASibshJr7o=; b=SOgdHWjEMLCW0QjUuiT6e2CF1MGQ5KGLcYiLz/be5u3S+TzeoqbeReDNP9+anrbn5t AIwAvwPUBp9A+fzPolsykmmYDi2soAqd8DyT11LTZSrhCsnnmUZBsPNJpfLEdR8rgWX9 l8Da889826iIOe6jvq3MMJSdhVSMY9bvytetUNiQf6JZcdiB0+D0F0dhdZ0WXC3tfcO7 KdrK5yPTW+tp4ACwH5+Ii7AXkQxXdLYmMX4G+X8YBMIiBSGJ6N/btFk8G3f1HhsGLZ+0 tbsfm8+/tvODB9Tm0ymg8y7smyrJ/yX53mEVUXP9glq5GXzH9gUo3MwPN/8g7kzJwDCJ gk7g== X-Gm-Message-State: AOAM533Fju/5jHMb2yjEjx7KcOUTIwTy0nP+GbenLs4KBzlLiQlV774y xZ48GpINgCzJ7AttxmEmDIc= X-Google-Smtp-Source: ABdhPJwUusLonRJPfLhID5eqG5hv9dEooBLirv2Q0V3Al1ERtM61F/Ze8oONhADBQzsOzTKlzXYPtw== X-Received: by 2002:a1c:4302:: with SMTP id q2mr8543859wma.182.1605392528005; Sat, 14 Nov 2020 14:22:08 -0800 (PST) Received: from localhost.localdomain ([170.253.49.0]) by smtp.googlemail.com with ESMTPSA id 89sm16826357wrp.58.2020.11.14.14.22.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 14 Nov 2020 14:22:07 -0800 (PST) From: Alejandro Colomar X-Google-Original-From: Alejandro Colomar To: pcc@google.com, mtk.manpages@gmail.com Subject: [PATCH] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol Date: Sat, 14 Nov 2020 22:49:15 +0100 Message-Id: <20201114214914.177815-1-colomar.6.4.3@gmail.com> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20201114014132.2439310-1-pcc@google.com> References: <20201114014132.2439310-1-pcc@google.com> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20201114_172210_373697_4A86BE27 X-CRM114-Status: GOOD ( 17.54 ) X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-arm-kernel@lists.infradead.org, linux-man@vger.kernel.org, vincenzo.frascino@arm.com, andreyknvl@google.com, deller@gmx.de, kevin.brodsky@arm.com, oleg@redhat.com, Alejandro Colomar , James.Bottomley@hansenpartnership.com, kcc@google.com, ebiederm@xmission.com, catalin.marinas@arm.com, david.spickett@linaro.org, linux-api@vger.kernel.org, will@kernel.org, Dave.Martin@arm.com, eugenis@google.com Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org From: Peter Collingbourne Signed-off-by: Peter Collingbourne [alx: srcfix + ffix] Cowritten-by: Alejandro Colomar Signed-off-by: Alejandro Colomar --- Hi Michael, as Peter noted, this patch is not ready (code hasn't been merged into the kernel yet). And a spin-off question: How would you prefer it?: [ .B SA_* ] (there are 79 similar cases in the pages [1]) or [ .BR SA_ * ] (there are 3 similar cases in the pages [2]) Hi Peter, I improved a few minor things in your patch: - Use semantic newlines (see man-pages(7)). - Change explicit blank lines to [.PP] (see 'Formatting conventions(general)' in man-pages(7)). - Use Oxford comma. Thanks, Alex [1](grep -r "_\*" man? | wc -l) [2](grep -r "_ \*" man? | wc -l) man2/sigaction.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 22da658d0..91c46f3e3 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -251,6 +251,19 @@ This flag is meaningful only when establishing a signal handler. .\" .I sa_sigaction .\" field was added in Linux 2.1.86.) .\" +.TP +.BR SA_UNSUPPORTED " (since Linux 5.??)" +This flag bit will never be supported by the kernel. +It is used as part of the flag support detection protocol described below. +.TP +.BR SA_EXPOSE_TAGBITS " (since Linux 5.??)" +Normally, when delivering a signal, +an architecture-specific set of tag bits are cleared from the +.I si_addr +field of +.IR siginfo_t . +If this flag is set, the tag bits will be preserved in +.IR si_addr . .SS The siginfo_t argument to a SA_SIGINFO handler When the .B SA_SIGINFO @@ -834,6 +847,58 @@ Triggered by a .BR seccomp (2) filter rule. .RE +.SS Detecting flag support in sa_flags +The Linux kernel supports a mechanism for programs to +detect kernel support for +.B SA_* +flags in +.IR sa_flags . +This mechanism is quite subtle for backwards compatibility reasons +related to the historical behavior of the kernel. +.PP +Starting with Linux 5.??, +the kernel will clear any unrecognized bits from the +.I sa_flags +value returned via +.I oldact +if those bits were set when the signal handler was originally installed. +Therefore, a program that only needs to be compatible with +Linux 5.?? and above +may test for flag bit support by issuing a second call to +.BR sigaction () +and testing whether the bit remains set in +.IR oldact.sa_flags . +.PP +Prior to Linux 5.x, unrecognized flag bits were preserved in +.I oldact.sa_flags +so this protocol on its own would not be sufficient to allow a +userspace program to test for flag bit support +if it needs to be compatible with kernel versions older than 5.??. +Therefore, the +.B SA_UNSUPPORTED +flag bit was defined, +which the kernel will always consider to be unknown. +A userspace program that sets this flag bit in +.I act.sa_flags +and finds that it has been cleared in +.I oldact.sa_flags +in a subsequent call to +.BR sigaction () +may trust that any other unknown flag bits have been cleared. +.PP +A reasonably modern program may trust that the flags +.BR SA_NOCLDSTOP , +.BR SA_NOCLDWAIT , +.BR SA_SIGINFO , +.BR SA_ONSTACK , +.BR SA_RESTART , +.BR SA_NODEFER , +.BR SA_RESETHAND , +and, if defined by the architecture, +.B SA_RESTORER +are supported by the kernel, +without relying on the flag bit support detection protocol, +since these flags have all been supported since Linux 2.6. .SH RETURN VALUE .BR sigaction () returns 0 on success; on error, \-1 is returned, and -- 2.28.0 _______________________________________________ linux-arm-kernel mailing list linux-arm-kernel@lists.infradead.org http://lists.infradead.org/mailman/listinfo/linux-arm-kernel