From patchwork Sat Nov 14 01:41:32 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Collingbourne X-Patchwork-Id: 11905273 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=-9.7 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_ADSP_CUSTOM_MED,DKIM_SIGNED,DKIM_VALID,HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH,MAILING_LIST_MULTI,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 86DDBC4742C for ; Sat, 14 Nov 2020 01:43:07 +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 25CC22225D for ; Sat, 14 Nov 2020 01:43:07 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="o2Mk5xDV"; dkim=fail reason="signature verification failed" (2048-bit key) header.d=google.com header.i=@google.com header.b="Sxa78iw0" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 25CC22225D Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=google.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:To:From:Subject:Mime-Version:Message-Id:Date: Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender :Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References:List-Owner; bh=Yjbw/ye/8lzL8cZ8hu7AW9/Fjt0Bg4yKYmvak1zBAR8=; b=o2Mk5xDVQ2/2u2zIvYNbj8PntE o1HISuwuBPktkWXVRuQ+gC1l7Y6rYffDQQuTHGY9xL76gJ72ylmQYNiCBU7Ne9lP34ACSsP/vKYMo v/3UJm2OaQbZBYJ6IT7LSrrXotyEf15UvjZdeDIrF4B47Nt+byc+t74F/jM2qbSN2wIS6rxsw9CPc JgWb7GTunrOvTsEmL6JJz5ao1QXMoMJAmCDcKdns02Vql4wV2Pq1xfhYz5BG+qKjvutLff974Hatd F+TndOuMzZVuFiFVmg4i+V+LkBReGc3h3WXJ7ZySnhtyK/r467+JdpoWMJ+z98zWP4ML9vsMEKGuN yz8UjEeQ==; Received: from localhost ([::1] helo=merlin.infradead.org) by merlin.infradead.org with esmtp (Exim 4.92.3 #3 (Red Hat Linux)) id 1kdkZd-0002c9-3i; Sat, 14 Nov 2020 01:41:53 +0000 Received: from mail-pg1-x54a.google.com ([2607:f8b0:4864:20::54a]) by merlin.infradead.org with esmtps (Exim 4.92.3 #3 (Red Hat Linux)) id 1kdkZa-0002bU-E7 for linux-arm-kernel@lists.infradead.org; Sat, 14 Nov 2020 01:41:51 +0000 Received: by mail-pg1-x54a.google.com with SMTP id u4so7446810pgg.14 for ; Fri, 13 Nov 2020 17:41:47 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20161025; h=sender:date:message-id:mime-version:subject:from:to:cc; bh=7gRXkAxv9FSHZJPu4qkNB+4GIdmBPg8D68cb6lJq7ZA=; b=Sxa78iw0YlEtV3CRU86rl3UfFmqcBLywcZKQOkIKC3UotS733oOkm+Cn/tJqRcd8gT XvQcCEy4d510dKGngdtqB5wMwMS6m28PyxLcs9a/vLaF4/1qIgxhF6GtOnuoaPoQe0d/ 6o4JwUmUcXf1KczGy9fGk0xiiULruqlE2pukgY3IC4k/RwwPOE7jkeRV3LPo9TZYHjWy Bgm0IhRc/whIIQYWvjGCxHOWDku+zZwj/lo+7s/tM30lnUCyzhUzZ4vTsoMK5DKwi84y hOIkuog3ff4gunpKiL510SwRYfhimj6ktf7bRly/DnWWhcgocXmaEVCS97wipLzfGGPk XExQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:date:message-id:mime-version:subject:from :to:cc; bh=7gRXkAxv9FSHZJPu4qkNB+4GIdmBPg8D68cb6lJq7ZA=; b=Demf0IKmY06nbsLxAMDnbktGA7KserN8Q5rYuOxGtG+saJmmzg53f1WamdbgCNEspj TY6eyjaZgMrM9OEe50YKnvkrnh0s9RgZEMKQ5WRRb4kJtpo3iO8R3IjbxIi50nQusZ09 sGxtMupXIWy0ceBCPyAEVXZQEUQ2+46Y14pHorqInHGmr/PrINlafSq8un2Br0etTu4C FVQH5fKOrFNDO0TthOAEOSgG36+yZ5KZYDP32+o6D96DsPve5osTIIOooHhSZcZGHDli SWi8lYjDZFE4ZGiaEHCfW1S5ypq+OnEmQ7IgdlBXseqRwmu8IiDSco328Bog6/5OtdFj t57A== X-Gm-Message-State: AOAM531amleMdPspUWfyW/0jkQd4aKJrkXsC94N6/Na8HmV9CyRy+59O KFnW7KMMgLkVZyPtpX6lHSdL6yc= X-Google-Smtp-Source: ABdhPJwXH636vTk98vGGJZ3D7xTHRzsIDuD+3UJjwyqN+hdtllDfwf0FWiAihLbQJfFWgfM+M3ZFqts= X-Received: from pcc-desktop.svl.corp.google.com ([2620:15c:2ce:0:7220:84ff:fe09:385a]) (user=pcc job=sendgmr) by 2002:a17:902:a9c9:b029:d6:2d8f:f7b4 with SMTP id b9-20020a170902a9c9b02900d62d8ff7b4mr4501708plr.2.1605318106075; Fri, 13 Nov 2020 17:41:46 -0800 (PST) Date: Fri, 13 Nov 2020 17:41:32 -0800 Message-Id: <20201114014132.2439310-1-pcc@google.com> Mime-Version: 1.0 X-Mailer: git-send-email 2.29.2.299.gdc1121823c-goog Subject: [PATCH] sigaction.2: Document SA_EXPOSE_TAGBITS and the flag support detection protocol From: Peter Collingbourne To: Catalin Marinas , Evgenii Stepanov , Kostya Serebryany , Vincenzo Frascino , Dave Martin , Will Deacon , Oleg Nesterov , "Eric W. Biederman" , "James E.J. Bottomley" , Michael Kerrisk X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20201113_204150_531431_F989604E X-CRM114-Status: GOOD ( 16.02 ) 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-man@vger.kernel.org, Andrey Konovalov , Helge Deller , Kevin Brodsky , linux-api@vger.kernel.org, David Spickett , Peter Collingbourne , Linux ARM Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+linux-arm-kernel=archiver.kernel.org@lists.infradead.org --- These features are implemented in this patch series: https://lore.kernel.org/linux-arm-kernel/cover.1605235762.git.pcc@google.com/ which is still under review, so the patch should not be applied yet. man2/sigaction.2 | 62 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 6a8142324..82fb69e26 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -250,6 +250,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.x)" +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.x)" +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 @@ -833,6 +846,55 @@ 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. + +Starting with Linux 5.x, 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.x +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 . + +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.x. 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. + +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 , +.B 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