From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-ed1-x543.google.com (mail-ed1-x543.google.com [IPv6:2a00:1450:4864:20::543]) by sourceware.org (Postfix) with ESMTPS id A3F49383F842 for ; Wed, 3 Jun 2020 12:15:21 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org A3F49383F842 Received: by mail-ed1-x543.google.com with SMTP id s19so1531687edt.12 for ; Wed, 03 Jun 2020 05:15:21 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=BfnbfHo6MNEe1j4vyK3gjMBF4knwYRG3lgEYCjJ8Lm4=; b=X3MOSHalkhqdYhKUctGsiR+ZW4+OjETsOPDc2/QwiuZsrgjbabb7xxrK2u6DJVEZHC 5MtFpWUSX40lOKxKw4vUjJoWhcIgRVDrqXNAH/F87A+X135FrkN0ht/qL5uI79srV7GP ynx4IjnPZ5iiF6g0DfnAmiQtR6x5mBQ8H2Kaqnpb130Uiyg6ASyJb1xfu1VmsWtuk1gR gxNCqPNzNtSB9KHDyQeacgkY1f0sJpfHeZZB2wfsazrsDoEuJ1DIGntUp253pZ8VgFA8 mkf8x6StfuGf2nbDYg3BwfjTCUMd/nLukfTTK+VswI1Km8GEd3idsZP8L5xdPmCdAWLm Q//g== X-Gm-Message-State: AOAM533vnD4qYkxQ1KQnYBYuWP+hirB7c2DcElr4KzI5hFGWIaHhzmrN pf4Gu2+yaFmI7EF9H0GgfrBAePNqt7WESYhTzWI= X-Google-Smtp-Source: ABdhPJwi4ENweoNoxS9Vq6Q5bYnEm5wT3tKdTYzaOcEPCWHhW9pZfkfkzyJcftcTmEcZB+OZEHkj2x+4pkWHoBf4fRA= X-Received: by 2002:a05:6402:14c3:: with SMTP id f3mr11197513edx.341.1591186520747; Wed, 03 Jun 2020 05:15:20 -0700 (PDT) MIME-Version: 1.0 References: <87zh9kxzs2.fsf@oldenburg2.str.redhat.com> In-Reply-To: From: Michael Kerrisk Date: Wed, 3 Jun 2020 14:15:09 +0200 Message-ID: Subject: Re: [PATCH v2] manual: Add pthread_attr_setsigmask_np, pthread_attr_getsigmask_np To: Michael Kerrisk-manpages Cc: Florian Weimer , "libc-alpha@sourceware.org" Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-7.9 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, 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-List-Received-Date: Wed, 03 Jun 2020 12:15:23 -0000 Hi Florian, Actually, on rereading, I realize I didn't fully grok the structure of the discussion. See below. On Wed, Jun 3, 2020 at 12:27 PM Michael Kerrisk (man-pages) via Libc-alpha wrote: > > Hi Florian, > > On Wed, 3 Jun 2020 at 11:30, Florian Weimer wrote: > > > > 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..6d581a35c6 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 [I missed this piece, that the bullet list is *steps in the thread that calls pthread_create()*. Sorry about the confusion. > > +@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 signals can arrive on the > > s/signals/no signals/ > > The word "arrive" seems a bit vague to me. How about: > > [[ > This ensures that the new thread will be created with all signals > masked, so that no signals can be delivered until the desired signal > mask is set. > ]] > > > +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. > > By this point, some readers may be wondering: "which thread?". Maybe > the last sentence is better as something like: > > In the thread that called @code{pthread_create}, restore the signal > mask to the value that was saved in the first step. [Okay -- maybe that last change isn't sensible] > > +@end enumerate > > I think that this next piece could easily just be the fourth item in > the enumeration, rather than sitting after it. [And I think that last suggestion can likewise be ignored.] Thanks, Michael