From patchwork Wed Jun 3 12:28:50 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 39434 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 402F6383F868; Wed, 3 Jun 2020 12:29:02 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 402F6383F868 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1591187342; bh=d1z9jBYZqvYwNMWYa6VAqojlEgHnZOudRZ2/clHDGHM=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=iD/fwzizbFMUKKLvJiPx+jVhHU3qom6y7uKhMnv+bRrAfz9ca3eh9kb57JBxv7pPi QvC79EJKcQ3ICIRiSdnmLBvIuSUrcFu6Q/j349WgflpCvsN05jsF1+g3e9e84IfFZo yPBCcvq6vYG2x7FuRTpiaB/iEYgJfttzSFDw0B3A= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [205.139.110.61]) by sourceware.org (Postfix) with ESMTP id 64B2D3851C12 for ; Wed, 3 Jun 2020 12:29:00 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 64B2D3851C12 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-94-_Agl5HGhMd2Aj9ttAddTfg-1; Wed, 03 Jun 2020 08:28:56 -0400 X-MC-Unique: _Agl5HGhMd2Aj9ttAddTfg-1 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 749E0872FE0; Wed, 3 Jun 2020 12:28:55 +0000 (UTC) Received: from oldenburg2.str.redhat.com (ovpn-112-181.ams2.redhat.com [10.36.112.181]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 99E5A9323; Wed, 3 Jun 2020 12:28:51 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH v3] manual: Add pthread_attr_setsigmask_np, pthread_attr_getsigmask_np Date: Wed, 03 Jun 2020 14:28:50 +0200 Message-ID: <87v9k8wcxp.fsf@oldenburg2.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-13.3 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H2, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Cc: Michael Kerrisk Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" And the PTHREAD_ATTR_NO_SIGMASK_NP constant. --- manual/threads.texi | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/manual/threads.texi b/manual/threads.texi index a425635179..bb7a42c655 100644 --- a/manual/threads.texi +++ b/manual/threads.texi @@ -625,6 +625,7 @@ the standard. @menu * Default Thread Attributes:: Setting default attributes for threads in a process. +* Initial Thread Signal Mask:: Setting the initial mask of threads. * Waiting with Explicit Clocks:: Functions for waiting with an explicit clock specification. @end menu @@ -671,6 +672,77 @@ The system does not have sufficient memory. @end table @end deftypefun +@node Initial Thread Signal Mask +@subsubsection Controlling the Initial Signal Mask of a New Thread + +@Theglibc{} provides a way to specify the initial signal mask of a +thread created using @code{pthread_create}, passing a thread attribute +object configured for this purpose. + +@deftypefun int pthread_attr_setsigmask_np (pthread_attr_t *@var{attr}, const sigset_t *@var{sigmask}) +@standards{GNU, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +Change the initial signal mask specified by @var{attr}. If +@var{sigmask} is not @code{NULL}, the initial signal mask for new +threads created with @var{attr} is set to @code{*@var{sigmask}}. If +@var{sigmask} is @code{NULL}, @var{attr} will no longer specify an +explicit signal mask, so that the initial signal mask of the new +thread is inherited from the thread that calls @code{pthread_create}. + +This function returns zero on success, and @code{ENOMEM} on memory +allocation failure. +@end deftypefun + +@deftypefun int pthread_attr_getsigmask_np (const pthread_attr_t *@var{attr}, sigset_t *@var{sigmask}) +@standards{GNU, pthread.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +Retrieve the signal mask stored in @var{attr} and copy it to +@code{*@var{sigmask}}. If the signal mask has not been set, return +the special constant @code{PTHREAD_ATTR_NO_SIGMASK_NP}, otherwise +return zero. + +@c Move this to the documentation of pthread_getattr_np once it exists. +Obtaining the signal mask only works if it has been previously stored +by @code{pthread_attr_setsigmask_np}. For example, the +@code{pthread_getattr_np} function does not obtain the current signal +mask of the specified thread, and @code{pthread_attr_getsigmask_np} +will subsequently report the signal mask as unset. +@end deftypefun + +@deftypevr Macro int PTHREAD_ATTR_NO_SIGMASK_NP +The special value returned by @code{pthread_attr_setsigmask_np} to +indicate that no signal mask has been set for the attribute. +@end deftypevr + +It is possible to create a new thread with a specific signal mask +without using these functions. On the thread that calls +@code{pthread_create}, the required steps for the general case are: + +@enumerate 1 +@item +Mask all signals, and save the old signal mask, using +@code{pthread_sigmask}. This ensures that the new thread will be +created with all signals masked, so that no signals can be delivered +to the thread until the desired signal mask is set. + +@item +Call @code{pthread_create} to create the new thread, passing the +desired signal mask to the thread start routine (which could be a +wrapper function for the actual thread start routine). It may be +necessary to make a copy of the desired signal mask on the heap, so +that the life-time of the copy extends to the point when the start +routine needs to access the signal mask. + +@item +Restore the thread's signal mask, to the set that was saved in the +first step. +@end enumerate + +The start routine for the created thread needs to locate the desired +signal mask and use @code{pthread_sigmask} to apply it to the thread. +If the signal mask was copied to a heap allocation, the copy should be +freed. + @node Waiting with Explicit Clocks @subsubsection Functions for Waiting According to a Specific Clock