From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.1 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,MAILING_LIST_MULTI, SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id A72FF1F55B for ; Sat, 16 May 2020 10:18:43 +0000 (UTC) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id B752238708FF; Sat, 16 May 2020 10:18:42 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org B752238708FF DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1589624322; bh=f7+4VRnIHW/cyMsQnblKABcnLPqjLeEuquvcO3RLxAU=; h=References:In-Reply-To:Date:Subject:To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=pp2ndZ8Xkl5xFH4Ka3haysHdzbB9MCsieNyekoRdTA0dChFpU85Q3yFWEeTV64O+I +YpovakoaEEsdziG4DH4vixBByD1u9rZ/+TpPe/0Ocfp9CGxPOvpO8kx14sw+cGnbK dt4asds1iKtlGtYPUJS7JT/zVBbsujcqP2oYrmls= Received: from mail-ej1-x641.google.com (mail-ej1-x641.google.com [IPv6:2a00:1450:4864:20::641]) by sourceware.org (Postfix) with ESMTPS id 2D3933851C2D for ; Sat, 16 May 2020 10:18:40 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 2D3933851C2D Received: by mail-ej1-x641.google.com with SMTP id yc10so4392850ejb.12 for ; Sat, 16 May 2020 03:18:40 -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:reply-to :from:date:message-id:subject:to:cc:content-transfer-encoding; bh=f7+4VRnIHW/cyMsQnblKABcnLPqjLeEuquvcO3RLxAU=; b=Z7+COOD7coHUT4/cY8NfFkLPS4ekXkCFJB+3/cS9msurd2Skm0cggImc3dkNLv3zVK FB6wFEhvuiwAp5zbrkUAa5VzKVv4QCjnQmNb1Hlofo0pb6FluocxJyDe5CkjWGB9PHjG yT0dXZS5+LfrAb/o/eRlMIlR9CqrDeHOw9/UwV8tfuiDxYi64zHeha5m1UBMja9dV8Hm tsfdhgU3zTZQAAMtJ6S9snfinzzaHQs4WMxtM5cXbOtjlhgsfkEq8XA2yFROn5SOvGUS cniKycu8G9QPqzVofsCJ4IR3ag14XKAs14lu6pED/6+n2a3lMhMIXcCOCLMHOQjVGywf F1uw== X-Gm-Message-State: AOAM5332jBt/PTCwIWtxIOzurIqOLOoON1IvrFKXhZhcS8s1BV6FV+Cg nRpvKcUo2akNGSuxeMurGIfO5e70jZdO8hhdRy1c6oRb X-Google-Smtp-Source: ABdhPJzgSOPzLG/l1TBAxpdKSaIs24IdIcUsns4XFNrRKAMdsW4GxoeBfY8G8XPy+veWZTF2U2GpDBOQYs8z0QcqKNY= X-Received: by 2002:a17:906:da1e:: with SMTP id fi30mr6554925ejb.80.1589624319127; Sat, 16 May 2020 03:18:39 -0700 (PDT) MIME-Version: 1.0 References: <87h7zfn6rm.fsf@oldenburg2.str.redhat.com> <87sgg0jkp0.fsf@oldenburg2.str.redhat.com> <87a728jiww.fsf@oldenburg2.str.redhat.com> In-Reply-To: <87a728jiww.fsf@oldenburg2.str.redhat.com> Date: Sat, 16 May 2020 12:18:27 +0200 Message-ID: Subject: Re: [PATCH] manual: Document the System V sigpause function To: Florian Weimer Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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: , From: "Michael Kerrisk \(man-pages\) via Libc-alpha" Reply-To: mtk.manpages@gmail.com Cc: libc-alpha Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" Hi Florian, On Sat, 16 May 2020 at 12:03, Florian Weimer wrote: > > * Michael Kerrisk: > > > Hi Florian, > > > > On Sat, 16 May 2020 at 11:25, Florian Weimer wrote= : > >> > >> * Michael Kerrisk: > >> > >> >> +@deftypefun int sigpause (int @var{signal}) > >> >> +@standards{XOPEN, signal.h} > >> >> +@safety{@prelim{}@mtunsafe{@mtasurace{:sigprocmask}}@asunsafe{@asu= lock{/hurd}}@acunsafe{@aculock{/hurd}}} > >> >> +This deprecated function is a precursor to the @code{sigsuspend} > >> >> +function (@pxref{Waiting for a Signal}): it removes @var{signal} f= rom > >> >> +the thread's signal mask, and waits for a signal to arrive. On re= turn > >> >> +the previous set of blocked signals is restored. > >> > > >> > s/previous set of blocked signals is restored/thread's previous sign= al > >> > mask is restored/ ? > >> > >> =E2=80=9CSet of blocked signals=E2=80=9D is the term preferred by the = rest of the > >> manual. > > > > Maybe so, but: > > * "set of blocked signals" is clunky and a bit imprecise (POSIX uses > > the term mask) > > Yes, using non-standard terms has its problems. So, maybe best fix it. Currently the manual uses a mixture of the terms "signal mask" and "set of blocked signals". I think the fix should be to uniformly use the POSIX terminology. But I won't say more on this, beyond this mail; of course it's good that you document these interfaces, even if not exactly they way I would do it :-). > > * In the very preceding line, you yourself wrote "thread's signal mask"= ... > > That's a good point. Let me change that as well. Yes, but now your text is less precise: +the set of blocked signals, and waits for a signal to arrive. On +return the previous set of blocked signals is restored. The reader is perhaps left puzzled because you've now removed all mention of "trhead" or "process". Whose/what set of blocked signals? > > Maybe the rest of the manual should be fixed? > > Maybe, but I was explictly told not to use =E2=80=9Cpathname=E2=80=9D not= too long ago. Yes, but apparently there's a specific GNU guideline about the term. I'm guessing that there is not a specific guideline pertaining to the current discussion. > The other issue is that it is not clear that the term =E2=80=9Cprocess si= gnal > mask=E2=80=9D (which is already used in a few places) does not reflect th= e > situatio non Linux. The double negative there makes it hard for me to deduce your point. Thanks, Michael --=20 Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/