From patchwork Mon May 10 17:55:10 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 1476617 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=8.43.85.97; helo=sourceware.org; envelope-from=libc-alpha-bounces@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=wnz8VMf0; dkim-atps=neutral Received: from sourceware.org (ip-8-43-85-97.sourceware.org [8.43.85.97]) (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 ozlabs.org (Postfix) with ESMTPS id 4Ff7yv1Dxfz9sWp for ; Tue, 11 May 2021 03:56:23 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2898A396C812; Mon, 10 May 2021 17:56:21 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 2898A396C812 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1620669381; bh=PyVoAYNT9D6Z7Sj/FgFphnsjcqRuTK3M36+LOKWAPbc=; 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=wnz8VMf0GAtzs+yeguFaV64f2a1CJVMAvG9b0sNqK6vaifeV1FyKqCFlFgurjUIcb +GP6OhryqJowxfu/rCQVa3euTYNu64yp8S5WQVA7s4Dk5GTYb96VC2KnWSlKjsQ+Mk 6s82HeboPSKvaPqzI7NqqCgbCfiVj3OJjFUdb6Ks= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by sourceware.org (Postfix) with ESMTPS id 822343858039 for ; Mon, 10 May 2021 17:56:18 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 822343858039 Received: by mail-wm1-x32f.google.com with SMTP id j3-20020a05600c4843b02901484662c4ebso11669618wmo.0 for ; Mon, 10 May 2021 10:56:18 -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=PyVoAYNT9D6Z7Sj/FgFphnsjcqRuTK3M36+LOKWAPbc=; b=ZJoA5nXwtZOn6w+fvLlQX4C5aecHWHqukzBNGe5Ebs+tgrraegeHV04NbxGvPeXUwh o9hSj3zyxzetZxlMYtedtdC3vQlarjU9ydagrX1zbxl9c9XFpyBUyf5tDyIvxLyG3KS4 7T/Pjluif5GfdH2z2K0XNTD6K6yR9e3Z6Yk0t4G8/W904aFCCWZXSBQWZDjRWnD4y3r+ 0lyTrYItJO7WagI5uY3W2NjqhMi3albbNtu47LZvmaoNVb3sOx6qtcJNddhX3f+xCBKP PBZURajVO2ACNLbhvCW+jrrH3uIVYzCZj/HPZ5pyNMZblNOz7zGqjXsHYVReduDfLKr/ MV/w== X-Gm-Message-State: AOAM532cHbd/pb6DE24ZepC4Q0euXpr3aCPlQ5Y9OKIaZHQbyJB7/QAI bygM/C2n2bXlVHb2DZ49WPI= X-Google-Smtp-Source: ABdhPJyi3XnFvyZbL65mzsCyIu7SLEyCdz9QCGXgBm6kBOYoica4tGpMMlQNyI3rB0PbmuuDCeekNg== X-Received: by 2002:a1c:4382:: with SMTP id q124mr27331306wma.63.1620669377667; Mon, 10 May 2021 10:56:17 -0700 (PDT) Received: from sqli.sqli.com ([195.53.121.100]) by smtp.googlemail.com with ESMTPSA id m13sm24318830wrw.86.2021.05.10.10.56.16 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 May 2021 10:56:17 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH 01/39] futex.2: Use syscall(SYS_...); for system calls without a wrapper Date: Mon, 10 May 2021 19:55:10 +0200 Message-Id: <20210510175546.28445-2-alx.manpages@gmail.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210510175546.28445-1-alx.manpages@gmail.com> References: <20210510175546.28445-1-alx.manpages@gmail.com> MIME-Version: 1.0 X-Spam-Status: No, score=-12.2 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: Florian Weimer , Jakub Wilk , Alejandro Colomar , libc-alpha@sourceware.org, linux-man@vger.kernel.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 | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/man2/futex.2 b/man2/futex.2 index 389c25224..ada96c517 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -25,18 +25,22 @@ 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. +glibc provides no wrapper for +.BR futex (), +necessitating the use of +.BR syscall (2). .SH DESCRIPTION The .BR futex () @@ -1695,9 +1699,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