From patchwork Sun Apr 4 11:58:32 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 42898 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 56C7038515E7; Sun, 4 Apr 2021 11:59:51 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 56C7038515E7 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1617537591; bh=V5uiLR+ON/9jELwFRyhOf85vS9zd2T+icii+8Xp6azA=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=JaeoPxnIU/AJJiksM7dBj8q+thZzLCEOaaJ0O4oBHlRP3Fd+sz/xoN+LHLkN+FW7E AcpaW/tQUfckeQI64OuKmpOMjogKVAfoZy8WghOoMNF6FT9728nGUK9IF6l5XzBEkj SjUlZCfMk7zYcUjNVhsw1T9JdW1hwXNJa9KLwcFg= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by sourceware.org (Postfix) with ESMTPS id 16E703860C3D for ; Sun, 4 Apr 2021 11:59:47 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 16E703860C3D Received: by mail-wr1-x42b.google.com with SMTP id v4so8574742wrp.13 for ; Sun, 04 Apr 2021 04:59:47 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=V5uiLR+ON/9jELwFRyhOf85vS9zd2T+icii+8Xp6azA=; b=intLQ8Y7egcBOMZnY+HAO4p9XVsEK3dvPOg6cjbJ6aqByLbFGaZSqQbvXXGjL4LRip Q8Y/O4PHx/PT4xo5hLFSamWY8r8UM6x5uWkDwV85SVLip8LUFT8NKIULG8K4GBj2+T8n xOSVYDflOy3mHVgMnQjYw+aA+Cal3mE76pezqhCfM+x2aeMuKcixXXTLmSfmZ2gq+nxV fKlLTQ211vCpeDiWsSbQLdD5WE2yIebzYn0DCxj2INSYHf730jj1dY/l+GUgATnGk9tk faOeuxNhGSNKcPWxrrlaMg+JiLMdgFjZdBK90jNLXaTTeiZhYa4vwmnc4IhmCtJ2NAQQ h/WQ== X-Gm-Message-State: AOAM5321cvxhOYbniDeEAM/0hYAr1K2mEysu56QFZs8EQE/ugiDIDyCk 1uwk8WuldYrWEyRM1ESVvZ8= X-Google-Smtp-Source: ABdhPJzpfASbk5Hxn5VCqFI8LgBMV6FWfOF01rtYyhUvqsThAhR8SN4RNs1L++LirA+vv8DMRRHupA== X-Received: by 2002:a5d:5586:: with SMTP id i6mr2564455wrv.372.1617537586284; Sun, 04 Apr 2021 04:59:46 -0700 (PDT) Received: from localhost.localdomain ([170.253.36.171]) by smtp.googlemail.com with ESMTPSA id u2sm23786967wrp.12.2021.04.04.04.59.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 04 Apr 2021 04:59:46 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH v5 19/35] futex.2: Use syscall(SYS_...); for system calls without a wrapper Date: Sun, 4 Apr 2021 13:58:32 +0200 Message-Id: <20210404115847.78166-20-alx.manpages@gmail.com> X-Mailer: git-send-email 2.31.0 In-Reply-To: <20210403194026.102818-1-alx.manpages@gmail.com> References: <20210403194026.102818-1-alx.manpages@gmail.com> MIME-Version: 1.0 X-Spam-Status: No, score=-12.3 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-Patchwork-Original-From: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Cc: Alejandro Colomar , linux-man@vger.kernel.org, libc-alpha@sourceware.org Errors-To: libc-alpha-bounces@sourceware.org Sender: "Libc-alpha" At the same time, document only headers that are required for calling the function, or those that are specific to the function: is required for the syscall() prototype. is required for the syscall name SYS_xxx. is specific to this syscall. However, uint32_t is generic enough that it shouldn't be documented here. The system_data_types(7) page already documents it, and is more precise about it. The same goes for timespec. As a general rule a man[23] page should document the header that includes the prototype, and all of the headers that define macros that should be used with the call. However, the information about types should be restricted to system_data_types(7) (and that page should probably be improved by adding types), except for types that are very specific to the call. Otherwise, we're duplicating info and it's then harder to maintain, and probably outdated in the future. Signed-off-by: Alejandro Colomar --- man2/futex.2 | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/man2/futex.2 b/man2/futex.2 index 389c25224..7a19e50d2 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -25,18 +25,16 @@ futex \- fast user-space locking .SH SYNOPSIS .nf .PP -.B #include -.B #include -.B #include +.BR "#include " " /* Definition of " FUTEX_* " constants */" +.BR "#include " " /* Definition of " SYS_* " constants */" +.B #include .PP -.BI "long futex(uint32_t *" uaddr ", int " futex_op ", uint32_t " val , -.BI " const struct timespec *" timeout , \ +.BI "long syscall(SYS_futex, uint32_t *" uaddr ", int " futex_op \ +", uint32_t " val , +.BI " const struct timespec *" timeout , \ " \fR /* or: \fBuint32_t \fIval2\fP */" -.BI " uint32_t *" uaddr2 ", uint32_t " val3 ); +.BI " uint32_t *" uaddr2 ", uint32_t " val3 ); .fi -.PP -.IR Note : -There is no glibc wrapper for this system call; see NOTES. .SH DESCRIPTION The .BR futex () @@ -1695,9 +1693,6 @@ and a sixth argument was added in Linux 2.6.7. .SH CONFORMING TO This system call is Linux-specific. .SH NOTES -Glibc does not provide a wrapper for this system call; call it using -.BR syscall (2). -.PP Several higher-level programming abstractions are implemented via futexes, including POSIX semaphores and various POSIX threads synchronization mechanisms