From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr1-x436.google.com (mail-wr1-x436.google.com [IPv6:2a00:1450:4864:20::436]) by sourceware.org (Postfix) with ESMTPS id B16F8394800A for ; Sat, 24 Apr 2021 15:46:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org B16F8394800A Received: by mail-wr1-x436.google.com with SMTP id e7so42381908wrs.11 for ; Sat, 24 Apr 2021 08:46:20 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=L625xC97j4ATBRwCibmjj0QnRYeh5XUj47lANFJx3CI=; b=U911dd9hp3A29DwDjAzuDNMrfk5bpQvXB4iaWzE76ptx1Mu9ZV5TC+lGDnZPEXnG0W 1ofX/qszUWR+JHDA/b3p+hZvRxHZzfmfH/6DlLBOD9oxzMlMkRxPFwe/oWCHiFy90qfP 7AQpTa+m6WHd14YHim4RXmm4XgSk1RqdAEBqONb9hI/MUJFVOYaQBTKzS1Ia7xDf5pXT A1zSQojNCmRXqRbcUG2OzngF59FDPDZJFLxMepWhRVizcquRmPHVVpVmNiT+QE1iKU87 PjTT2uc0HF/oTid+Rv4Y79fq60wlk7LYqZ3avcnEnzm8q/36R4GHEKRR8QGM371R3n/M x/fw== X-Gm-Message-State: AOAM531jV+egO/BjIdQ0xqoUJeup0GMGroNgcEKDU5Yf/S8FIleMrp9S xG1aWrvUQIBIn9HmnmJe7aA= X-Google-Smtp-Source: ABdhPJxrQlxuRh7dW8ftDERbBmnU8rR8872eJJ4kfB6ZG3qKiyp7dX9cQmCVdXEE+eM+LkhVd5QNVQ== X-Received: by 2002:a05:6000:12cb:: with SMTP id l11mr11537696wrx.267.1619279179901; Sat, 24 Apr 2021 08:46:19 -0700 (PDT) Received: from [192.168.0.169] ([170.253.36.171]) by smtp.gmail.com with ESMTPSA id i11sm2150330wrp.56.2021.04.24.08.46.19 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 24 Apr 2021 08:46:19 -0700 (PDT) Subject: Re: [PATCH v5 00/35] SYNOPSIS: Use syscall(SYS_...); and fix '#include's To: Florian Weimer Cc: "Michael Kerrisk (man-pages) via Libc-alpha" , Jakub Wilk , "Michael Kerrisk (man-pages)" , linux-man@vger.kernel.org References: <20210403194026.102818-1-alx.manpages@gmail.com> <20210404115847.78166-1-alx.manpages@gmail.com> <4298cc3c-8f24-5a3c-3c54-b24ca804d373@gmail.com> <87y2doni1m.fsf@oldenburg.str.redhat.com> <365dc717-eb20-4549-9b6a-09eeadcfc89d@gmail.com> <87pmyoqjnw.fsf@oldenburg.str.redhat.com> From: "Alejandro Colomar (man-pages)" Message-ID: <3d6feff0-f65b-f086-aa2a-be21ff90ccfe@gmail.com> Date: Sat, 24 Apr 2021 17:46:18 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.10.0 MIME-Version: 1.0 In-Reply-To: <87pmyoqjnw.fsf@oldenburg.str.redhat.com> Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-6.0 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, NICE_REPLY_A, 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: Sat, 24 Apr 2021 15:46:22 -0000 Hi Florian, On 4/21/21 7:41 AM, Florian Weimer wrote: > * Alejandro Colomar: > >>> Or, more succinctly, put the types in comments: >>> >>> syscall(SYS_arch_prctl, /* int */ code, /* unsigned long */ addr); >> >> I'm not sure. I see the point in doing this, but I think I prefer my >> version, because it has less noise. But I might be a bit biased :) > > Not everyone is deeply familiar with C syntax. Anyone who uses the > example literally will be disappointed. I've been thinking about this for some days. Although this syntax has become very familiar to me with time, I agree that the first times I saw it, it looked somewhat weird. Each of the three variants (yours, Jakub's, and mine (which is actually not mine, but one already present in some pages)) has some good advantages and some disadvantages. But the manual pages have been using the syntax I proposed, for those cases where a constant is to be used always, so in doubt, as I'm right now, I'll opt for that one. Also, those system calls without a wrapper are probably rare enough so that people that need them probably know enough of C to understand the syntax. I, for example, first had to use one of those, membarrier(2), after around 7 years of C programming. I remember being surprised by not having the prototype and having to declare it myself (the SYNOPSIS was a bit buggy by that time). But by completely reading the page and especially the EXAMPLES section, I think one can learn how to use it. Reading syscall(2) also helps. I'll keep my proposed syntax. Nevertheless, thanks for suggesting alternatives, and giving your reasons. I'll keep thinking about it and see if I come with something better. Thanks, Alex -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ Senior SW Engineer; http://www.alejandro-colomar.es/