From: "Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>
To: Daniel Borkmann <daniel@iogearbox.net>,
Zack Weinberg <zackw@panix.com>,
Greg KH <gregkh@linuxfoundation.org>
Cc: Alexei Starovoitov <alexei.starovoitov@gmail.com>,
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>,
linux-man <linux-man@vger.kernel.org>,
LKML <linux-kernel@vger.kernel.org>,
glibc <libc-alpha@sourceware.org>, GCC <gcc-patches@gcc.gnu.org>,
bpf <bpf@vger.kernel.org>, Joseph Myers <joseph@codesourcery.com>,
David Laight <David.Laight@aculab.com>,
davem@davemloft.net
Subject: Re: [RFC v2] bpf.2: Use standard types and attributes
Date: Tue, 4 May 2021 22:16:22 +0200 [thread overview]
Message-ID: <6ad5b5e3-1f9b-2302-84e5-8141d95fc142@gmail.com> (raw)
In-Reply-To: <8a184afe-14b7-ed15-eb6a-960ea05251d1@iogearbox.net>
Hi Daniel,
On 5/4/21 10:06 PM, Daniel Borkmann wrote:
>>
>> On 5/4/21 6:08 PM, Daniel Borkmann wrote:
>> >
>> > But what /problem/ is this really solving? Why bother to change
>> this /now/
>> > after so many years?! I think this is causing more confusion than
>> solving
>> > anything, really. Moreover, what are you doing with all the
>> > __{le,be}{16,32,64}
>> > types in uapi? Anyway, NAK for bpf.2 specifically, and the idea
>> generally..
>>
>> 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?
Sorry, I forgot to address that part in my answer. If there's no
standard way of naming a type without losing information, we can use the
kernel naming. I have no objection to that.
These are the only pages that seem to be using those:
$ grep -Enr '\b__[a-z][a-z]+[0-9]+' man?
man2/clone.2:44:clone, __clone2, clone3 \- create a child process
man2/clone.2:1694:.BI "int __clone2(int (*" "fn" ")(void *),"
man2/clone.2:1717:.BR __clone2 ()
man7/sock_diag.7:362: __be16 idiag_sport;
man7/sock_diag.7:363: __be16 idiag_dport;
man7/sock_diag.7:364: __be32 idiag_src[4];
man7/sock_diag.7:365: __be32 idiag_dst[4];
man7/bpf-helpers.7:514:.B \fBlong bpf_skb_vlan_push(struct sk_buff
*\fP\fIskb\fP\fB, __be16\fP \fIvlan_proto\fP\fB, u16\fP
\fIvlan_tci\fP\fB)\fP
man7/bpf-helpers.7:878:.B \fBs64 bpf_csum_diff(__be32 *\fP\fIfrom\fP\fB,
u32\fP \fIfrom_size\fP\fB, __be32 *\fP\fIto\fP\fB, u32\fP
\fIto_size\fP\fB, __wsum\fP \fIseed\fP\fB)\fP
man7/bpf-helpers.7:949:.B \fBlong bpf_skb_change_proto(struct sk_buff
*\fP\fIskb\fP\fB, __be16\fP \fIproto\fP\fB, u64\fP \fIflags\fP\fB)\fP
man7/system_data_types.7:473:.I __int128
man7/system_data_types.7:475:.I __int128
man7/system_data_types.7:1584:.I unsigned __int128
man7/system_data_types.7:1586:.I unsigned __int128
$
So sock_diag.7 and bpf-helpers.7 and only a handful of cases. Not much
of a problem. I'd keep those untouched.
Regards,
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
next prev parent reply other threads:[~2021-05-04 20:16 UTC|newest]
Thread overview: 49+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-23 23:06 [RFC] " Alejandro Colomar
2021-04-23 23:20 ` Alexei Starovoitov
2021-04-24 17:56 ` Alejandro Colomar (man-pages)
2021-04-25 16:52 ` Alexei Starovoitov
2021-04-25 19:12 ` Zack Weinberg
2021-04-24 20:43 ` David Laight
2021-04-25 19:16 ` Zack Weinberg
2021-04-25 21:09 ` David Laight
2021-04-26 17:19 ` Joseph Myers
2021-04-26 17:46 ` Alejandro Colomar (man-pages)
2021-05-04 11:05 ` [RFC v2] " Alejandro Colomar
2021-05-04 14:12 ` Alexei Starovoitov
2021-05-04 14:24 ` Greg KH
2021-05-04 15:53 ` Alejandro Colomar (man-pages)
2021-05-04 16:06 ` Greg KH
2021-05-04 18:37 ` Zack Weinberg
2021-05-04 18:54 ` Alejandro Colomar (man-pages)
2021-05-04 19:45 ` Florian Weimer
2021-05-04 19:59 ` Alejandro Colomar (man-pages)
2021-05-05 8:23 ` David Laight
2021-05-05 22:22 ` Joseph Myers
2021-05-04 20:06 ` Daniel Borkmann
2021-05-04 20:16 ` Alejandro Colomar (man-pages) [this message]
2021-05-04 20:33 ` Zack Weinberg
2021-05-04 21:23 ` Alexei Starovoitov
2021-05-15 19:01 ` [PATCH v3] " Alejandro Colomar
2021-05-16 9:16 ` Alejandro Colomar (man-pages)
2021-05-17 18:56 ` Daniel Borkmann
2021-05-21 11:12 ` Alejandro Colomar
2021-05-04 16:08 ` [RFC v2] " Daniel Borkmann
2022-08-24 18:55 ` [PATCH v3] Many pages: Document fixed-width types with ISO C naming Alejandro Colomar
2022-08-24 22:40 ` Alexei Starovoitov
2022-08-24 23:36 ` Alejandro Colomar
2022-08-25 0:52 ` Linus Torvalds
2022-08-25 7:20 ` Alejandro Colomar
2022-08-25 7:28 ` Xi Ruoyao
2022-08-25 7:48 ` Alejandro Colomar
2022-08-25 8:09 ` Xi Ruoyao
2022-08-25 7:42 ` Linus Torvalds
2022-08-25 7:59 ` Alejandro Colomar
2022-08-25 5:57 ` Greg Kroah-Hartman
2022-08-25 6:41 ` Florian Weimer
2022-08-25 7:27 ` Linus Torvalds
2022-08-25 14:38 ` Joseph Myers
2022-08-25 15:01 ` David Laight
2022-08-25 15:37 ` Joseph Myers
2022-08-25 16:43 ` Linus Torvalds
2022-08-25 7:44 ` Alejandro Colomar
2022-08-25 8:04 ` Alejandro Colomar
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=6ad5b5e3-1f9b-2302-84e5-8141d95fc142@gmail.com \
--to=alx.manpages@gmail.com \
--cc=David.Laight@aculab.com \
--cc=alexei.starovoitov@gmail.com \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=davem@davemloft.net \
--cc=gcc-patches@gcc.gnu.org \
--cc=gregkh@linuxfoundation.org \
--cc=joseph@codesourcery.com \
--cc=libc-alpha@sourceware.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-man@vger.kernel.org \
--cc=mtk.manpages@gmail.com \
--cc=zackw@panix.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).