From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mailbackend.panix.com (mailbackend.panix.com [166.84.1.89]) by sourceware.org (Postfix) with ESMTPS id 22F473848413 for ; Tue, 4 May 2021 20:33:37 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 22F473848413 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=panix.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=zackw@panix.com Received: from mail-yb1-f177.google.com (mail-yb1-f177.google.com [209.85.219.177]) by mailbackend.panix.com (Postfix) with ESMTPSA id 4FZWl45Hzvz2DPq for ; Tue, 4 May 2021 16:33:36 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=panix.com; s=panix; t=1620160416; bh=lTZ/lVLMWtbFhPZP+g/je+yhXr5csjuHDqGr9x80lZQ=; h=References:In-Reply-To:From:Date:Subject:To:Cc; b=TOYQrncra9Gnai/6or0hMCaDdLiTTZVrchRI7b7/0OP3QLRNckNBLOC3mqGk0yVh/ fpBjmeXlvO8qwocHeviveyO0X52e7YyDj5z9Saytbxb0iXUtSnIsglEKlHB/SfmvD2 Q0TDnF3fYi+GLQJWEYF2jfBuZacxObVTCVfb48T4= Received: by mail-yb1-f177.google.com with SMTP id i4so13953817ybe.2 for ; Tue, 04 May 2021 13:33:36 -0700 (PDT) X-Gm-Message-State: AOAM531JAOhKB4x+Phw2e2VcpjaRaK4Dt/bevSj4C4EomqROJ6WdRZIL qNK+nZESP3BlWpUjReoOOvdfjJoyM68eK5tgvEw= X-Google-Smtp-Source: ABdhPJzSu8AkpmhEIsw2NZgdeS4gQHrnZSlUQHP1cTKF3tAM8qwY6+MVc74w6j2O70No9S/0WKrHfYU44V3uQtTuV70= X-Received: by 2002:a25:348f:: with SMTP id b137mr37826198yba.248.1620160416247; Tue, 04 May 2021 13:33:36 -0700 (PDT) MIME-Version: 1.0 References: <20210423230609.13519-1-alx.manpages@gmail.com> <20210504110519.16097-1-alx.manpages@gmail.com> <69fb22e0-84bd-47fb-35b5-537a7d39c692@gmail.com> <6740a229-842e-b368-86eb-defc786b3658@gmail.com> <8a184afe-14b7-ed15-eb6a-960ea05251d1@iogearbox.net> In-Reply-To: <8a184afe-14b7-ed15-eb6a-960ea05251d1@iogearbox.net> From: Zack Weinberg Date: Tue, 4 May 2021 16:33:24 -0400 X-Gmail-Original-Message-ID: Message-ID: Subject: Re: [RFC v2] bpf.2: Use standard types and attributes To: Daniel Borkmann Cc: "Alejandro Colomar (man-pages)" , Greg KH , Alexei Starovoitov , "Michael Kerrisk (man-pages)" , linux-man , LKML , glibc , GCC , bpf , Joseph Myers , David Laight , David Miller Content-Type: text/plain; charset="UTF-8" X-Spam-Status: No, score=-1.6 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, JMQ_SPF_NEUTRAL, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 04 May 2021 20:33:38 -0000 On Tue, May 4, 2021 at 4:06 PM Daniel Borkmann wrote: > > I'm trying to clarify the manual pages as much as possible, by using standard conventions and similar structure all around the pages. Not everyone understands kernel conventions. Basically, Zack said very much what I had in mind with this patch. > > But then are you also converting, for example, __{le,be}{16,32,64} to plain > uint{16,32,64}_t in the man pages and thus removing contextual information > (or inventing new equivalent types)? > > What about other types exposed to user space like __sum16, __wsum, or __poll_t > when they are part of a man page, etc? Fields that are specifically in some endianness that isn't (necessarily) the CPU's _should_ be documented as such in the manpage, but I dunno if __{le,be}{16,32,64} as a type name is the ideal way to do it. There is no off-the-shelf notation for this as far as I know. I do not know what __sum16, __wsum, and __poll_t are used for, but I want to remind everyone again that the kernel's concerns are not necessarily user space's concerns and the information that should appear in the manpages is the information that is most relevant to user space programmers. zw