Navigational corrections (was: Re: [PATCH v2 1/2] system_data_types.7: Add 'void *')
Hi Alex, et al. On 10/2/20 3:51 PM, Alejandro Colomar wrote: > > Hi Jonathan, > > On 2020-10-02 15:27, Jonathan Wakely wrote: >> On Fri, 2 Oct 2020 at 14:20, Alejandro Colomar >> wrote: >>> >>> >>> >>> On 2020-10-02 15:06, Jonathan Wakely wrote: >>> > On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) >>> > wrote: >>> >> >>> >> On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely >>> wrote: >>> >>> >>> >>> On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc >>> wrote: >>> However, it might be good that someone starts a page called >>> 'type_qualifiers(7)' or something like that. >>> >>> >>> >>> Who is this for? Who is trying to learn C from man pages? Should >>> >>> somebody stop them? >>> >> >>> >> Yes, I think so. To add context, Alex has been doing a lot of work to >>> >> build up the new system_data_types(7) page [1], which I think is >>> >> especially useful for the POSIX system data types that are used with >>> >> various APIs. >>> > >>> > It's definitely useful for types like struct siginfo_t and struct >>> > timeval, which aren't in C. >>> >>> Hi Jonathan, >>> >>> But then the line is a bit diffuse. >>> Would you document 'ssize_t' and not 'size_t'? >> >> Yes. My documentation for ssize_t would mention size_t, refer to the C >> standard, and not define it. >> >>> Would you not document intN_t types? >>> Would you document stdint types, including 'intptr_t', and not 'void *'? >> >> I would document neither. >> >> I can see some small value in documenting size_t and the stdint types, >> as they are technically defined by the libc headers. But documenting >> void* seems very silly. It's one of the most fundamental built-in >> parts of the C language, not an interface provided by the system. >> >>> I guess the basic types (int, long, ...) can be left out for now, >> >> I should hope so! >> >>> and apart from 'int' those rarely are the most appropriate types >>> for most uses. >>> But other than that, I would document all of the types. >>> And even... when all of the other types are documented, >>> it will be only a little extra effort to document those, >>> so in the future I might consider that. >> >> [insert Jurassic Park meme "Your scientists were so preoccupied with >> whether or not they could, they didn't stop to think if they should." >> ] >> >> I don't see value in bloating the man-pages with information nobody >> will ever use, and which doesn't (IMHO) belong there anyway. We seem >> to fundamentally disagree about what the man pages are for. I don't >> think they are supposed to teach C programming from scratch. > > Agree in part. > I'll try to think about it again. > > In the meantime, I trust Michael to tell me when something is way off :) > > Thanks, really! > > Alex So, I think a navigational correction is needed. My vision was that system_data_types(7) would most usefully document the POSIX types, but by now there's too much of C creeping in. I have been a little slow to react to that, and I apologize for that. But I think we should not go in that direction I think it is worth having types like ssize_t and size_t in the page, simply because they turn up with so many of the POSIX APIs, and people often don't understand some details of these types (such as the necessary prinf() specifiers). So, as long as we're going to have a page about these types, it's fine by me to include size_t and ssize_t. Types like [u]intN_t are definitely on the borderline for me. But, they do appear in various APIs in the Linux interface (either explicitly, or as the similar __u32 ___64, etc.). And again many people don't understand some basic details, such as the PRI and SCN constants, so I think it is useful to have them briefly summarized in one place, and as long as they are already in the page, then let's keep them. I think __int128 etc definitely doesn't belong in this page. And I'd like to back pedal a bit. I think we really shouldn't have [u]int_fastN_t [u]int_leastN_t in the page. They are C details that have nothing to with POSIX, the kernel, or libc. Could you send me a patch to remove these from the page? And again, my apologies for not being focused enough on the big picture sooner. I don't think 'void' belongs in this page. Nor basic types such as int, long, etc. The question of 'void *' is an interesting one. It is something like a fundamental C type, and not something that comes from POSIX. But, it does appear in POSIX APIs and often details of using the type are not well understood. So, as a matter of practicality, and again since you've done the work, I am inclined to include this type in the page, just so it can be handily referred to along with all of the other types. Looking ahead (and I hope none of the above disheartens you, since you've done a lot of great work for this page), it would be good if you could provide a bit of an advance roadmap about the types that you'd like to add to the page. Thanks, Michael --
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
On 10/2/20 2:10 AM, David Laight wrote: > Also, you should > warn that because one can convert from any pointer type to void * and > then to any other pointer type, it's a deliberate hole in C's > type-checking. That isn't what the C standard says at all. What is says is that you can cast any data pointer to 'void *' and then cast it back to the same type. I was talking about compile-time checking; you're talking about run-time behavior. We're both right in our own domains. It is a tricky area, and this suggests that perhaps we shouldn't be trying to document this stuff in a libc/kernel manual.
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
Hi Jonathan, On 2020-10-02 15:27, Jonathan Wakely wrote: On Fri, 2 Oct 2020 at 14:20, Alejandro Colomar wrote: On 2020-10-02 15:06, Jonathan Wakely wrote: > On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) > wrote: >> >> On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely wrote: >>> >>> On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc wrote: However, it might be good that someone starts a page called 'type_qualifiers(7)' or something like that. >>> >>> Who is this for? Who is trying to learn C from man pages? Should >>> somebody stop them? >> >> Yes, I think so. To add context, Alex has been doing a lot of work to >> build up the new system_data_types(7) page [1], which I think is >> especially useful for the POSIX system data types that are used with >> various APIs. > > It's definitely useful for types like struct siginfo_t and struct > timeval, which aren't in C. Hi Jonathan, But then the line is a bit diffuse. Would you document 'ssize_t' and not 'size_t'? Yes. My documentation for ssize_t would mention size_t, refer to the C standard, and not define it. Would you not document intN_t types? Would you document stdint types, including 'intptr_t', and not 'void *'? I would document neither. I can see some small value in documenting size_t and the stdint types, as they are technically defined by the libc headers. But documenting void* seems very silly. It's one of the most fundamental built-in parts of the C language, not an interface provided by the system. I guess the basic types (int, long, ...) can be left out for now, I should hope so! and apart from 'int' those rarely are the most appropriate types for most uses. But other than that, I would document all of the types. And even... when all of the other types are documented, it will be only a little extra effort to document those, so in the future I might consider that. [insert Jurassic Park meme "Your scientists were so preoccupied with whether or not they could, they didn't stop to think if they should." ] I don't see value in bloating the man-pages with information nobody will ever use, and which doesn't (IMHO) belong there anyway. We seem to fundamentally disagree about what the man pages are for. I don't think they are supposed to teach C programming from scratch. Agree in part. I'll try to think about it again. In the meantime, I trust Michael to tell me when something is way off :) Thanks, really! Alex But yes, priority should probably go to Linux/POSIX-only types.
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
On Fri, 2 Oct 2020 at 14:20, Alejandro Colomar wrote: > > > > On 2020-10-02 15:06, Jonathan Wakely wrote: > > On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) > > wrote: > >> > >> On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely > wrote: > >>> > >>> On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc > wrote: > However, it might be good that someone starts a page called > 'type_qualifiers(7)' or something like that. > >>> > >>> Who is this for? Who is trying to learn C from man pages? Should > >>> somebody stop them? > >> > >> Yes, I think so. To add context, Alex has been doing a lot of work to > >> build up the new system_data_types(7) page [1], which I think is > >> especially useful for the POSIX system data types that are used with > >> various APIs. > > > > It's definitely useful for types like struct siginfo_t and struct > > timeval, which aren't in C. > > Hi Jonathan, > > But then the line is a bit diffuse. > Would you document 'ssize_t' and not 'size_t'? Yes. My documentation for ssize_t would mention size_t, refer to the C standard, and not define it. > Would you not document intN_t types? > Would you document stdint types, including 'intptr_t', and not 'void *'? I would document neither. I can see some small value in documenting size_t and the stdint types, as they are technically defined by the libc headers. But documenting void* seems very silly. It's one of the most fundamental built-in parts of the C language, not an interface provided by the system. > I guess the basic types (int, long, ...) can be left out for now, I should hope so! > and apart from 'int' those rarely are the most appropriate types > for most uses. > But other than that, I would document all of the types. > And even... when all of the other types are documented, > it will be only a little extra effort to document those, > so in the future I might consider that. [insert Jurassic Park meme "Your scientists were so preoccupied with whether or not they could, they didn't stop to think if they should." ] I don't see value in bloating the man-pages with information nobody will ever use, and which doesn't (IMHO) belong there anyway. We seem to fundamentally disagree about what the man pages are for. I don't think they are supposed to teach C programming from scratch. > But yes, priority should probably go to Linux/POSIX-only types.
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
On 2020-10-02 15:06, Jonathan Wakely wrote: > On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) > wrote: >> >> On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely wrote: >>> >>> On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc wrote: However, it might be good that someone starts a page called 'type_qualifiers(7)' or something like that. >>> >>> Who is this for? Who is trying to learn C from man pages? Should >>> somebody stop them? >> >> Yes, I think so. To add context, Alex has been doing a lot of work to >> build up the new system_data_types(7) page [1], which I think is >> especially useful for the POSIX system data types that are used with >> various APIs. > > It's definitely useful for types like struct siginfo_t and struct > timeval, which aren't in C. Hi Jonathan, But then the line is a bit diffuse. Would you document 'ssize_t' and not 'size_t'? Would you not document intN_t types? Would you document stdint types, including 'intptr_t', and not 'void *'? I guess the basic types (int, long, ...) can be left out for now, and apart from 'int' those rarely are the most appropriate types for most uses. But other than that, I would document all of the types. And even... when all of the other types are documented, it will be only a little extra effort to document those, so in the future I might consider that. But yes, priority should probably go to Linux/POSIX-only types. Thanks, Alex > > Trying to document C seems like a huge task, ill-suited for man-pages, > and not worth the effort. > > Maybe some people prefer man pages, but for everybody else > https://en.cppreference.com/w/c already exists and seems like a better > use of time. >
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
On Fri, 2 Oct 2020 at 12:31, Michael Kerrisk (man-pages) wrote: > > On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely wrote: > > > > On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc > > wrote: > > > However, it might be good that someone starts a page called > > > 'type_qualifiers(7)' or something like that. > > > > Who is this for? Who is trying to learn C from man pages? Should > > somebody stop them? > > Yes, I think so. To add context, Alex has been doing a lot of work to > build up the new system_data_types(7) page [1], which I think is > especially useful for the POSIX system data types that are used with > various APIs. It's definitely useful for types like struct siginfo_t and struct timeval, which aren't in C. Trying to document C seems like a huge task, ill-suited for man-pages, and not worth the effort. Maybe some people prefer man pages, but for everybody else https://en.cppreference.com/w/c already exists and seems like a better use of time.
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
Hi Alex, On 10/2/20 10:48 AM, Alejandro Colomar wrote: > Hi Michael, > > On 2020-10-02 10:24, Alejandro Colomar wrote: >> On 2020-10-01 19:32, Paul Eggert wrote: >> > For 'void *' you should also mention that one cannot use arithmetic on >> > void * pointers, so they're special in that way too. >> >> Good suggestion! >> >> > Also, you should >> > warn that because one can convert from any pointer type to void * and >> > then to any other pointer type, it's a deliberate hole in C's >> > type-checking. >> >> Also good. I'll talk about generic function parameters for this. > I think the patch as is now is complete enough to be added. > > So I won't rewrite it for now. > Please review the patch as is, > and I'll add more info to this type in the future. Actually, I would rather prefer one patch series, rather than patches on patches please. It also makes review of the overall 'void *' text easier if it's all one patch. So, If you could squash the patches together and resubmit, that would be helful. Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
On Fri, 2 Oct 2020 at 12:49, Jonathan Wakely wrote: > > On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc > wrote: > > However, it might be good that someone starts a page called > > 'type_qualifiers(7)' or something like that. > > Who is this for? Who is trying to learn C from man pages? Should > somebody stop them? Yes, I think so. To add context, Alex has been doing a lot of work to build up the new system_data_types(7) page [1], which I think is especially useful for the POSIX system data types that are used with various APIs. With the addition of the integer types and 'void *' things are straying somewhat from POSIX into C. I think there is value in saying something about those types, but I'm somewhat neutral about their inclusion in the page. But Alex has done the work, and I'm willing to include those types in the page. I do think that something like type_qualifiers(7) strays over the line of what should be covered in Linux man-pages, which are primarily about the kernel + libc APIs. [2] Thanks, Michael [1] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/system_data_types.7 [2] Mind you, man-pages trayed over the line already very many years ago with operators(7), because who ever remembers all of the C operator precedences. -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
On Fri, 2 Oct 2020 at 09:28, Alejandro Colomar via Gcc wrote: > However, it might be good that someone starts a page called > 'type_qualifiers(7)' or something like that. Who is this for? Who is trying to learn C from man pages? Should somebody stop them?
RE: [PATCH v2 1/2] system_data_types.7: Add 'void *'
From: Alejandro Colomar > Sent: 02 October 2020 09:25 > > For 'void *' you should also mention that one cannot use arithmetic on > > void * pointers, so they're special in that way too. > > Good suggestion! Except that is a gcc extension that is allowed in the kernel. > > Also, you should > > warn that because one can convert from any pointer type to void * and > > then to any other pointer type, it's a deliberate hole in C's > > type-checking. > > Also good. I'll talk about generic function parameters for this. That isn't what the C standard says at all. What is says is that you can cast any data pointer to 'void *' and then cast it back to the same type. This matters because the compiler will 'remember' structure alignment through 'void *' casts. So you can't use memcpy() to copy from a potentially misaligned (typed) pointer. 'void *' should only be used for structures that are 'a sequence of bytes'. (eg things that look a bit like read() or write()). David - Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK Registration No: 1397386 (Wales)
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
Hi Michael, On 2020-10-02 10:24, Alejandro Colomar wrote: On 2020-10-01 19:32, Paul Eggert wrote: > For 'void *' you should also mention that one cannot use arithmetic on > void * pointers, so they're special in that way too. Good suggestion! > Also, you should > warn that because one can convert from any pointer type to void * and > then to any other pointer type, it's a deliberate hole in C's > type-checking. Also good. I'll talk about generic function parameters for this. I think the patch as is now is complete enough to be added. So I won't rewrite it for now. Please review the patch as is, and I'll add more info to this type in the future. Thanks, Alex
Re: [PATCH v2 1/2] system_data_types.7: Add 'void *'
Hi Paul, On 2020-10-01 19:32, Paul Eggert wrote: > If you're going to document this at all, I suggest documenting 'void' as > well as 'void *', and putting both sets of documentation into the same > man page. > All the types we're documenting are in the same page: system_data_types(7). And then we have links with the name of each type. And yes, I also pretend to document 'void'. > For 'void *' you should also mention that one cannot use arithmetic on > void * pointers, so they're special in that way too. Good suggestion! > Also, you should > warn that because one can convert from any pointer type to void * and > then to any other pointer type, it's a deliberate hole in C's > type-checking. Also good. I'll talk about generic function parameters for this. > It might not also hurt to mention 'void const *', 'void > volatile *', 'void const volatile *', etc. Those are qualifiers for the type, and I don't see how any of them would apply differently to 'void *' than to any other pointer type (or any type at all), so I think they don't belong to system_data_types(7). However, it might be good that someone starts a page called 'type_qualifiers(7)' or something like that. I would love that someone documents 'volatile' correctly, as there aren't many good sources about it. If someone who knows when to use --and especially when not to use-- 'volatile', is reading this, think about it :-) I still wonder if I used it correctly in the few cases I've had to. BTW, I'll CC the LKML. > > For 'void' you can mention the usual things, such as functions returning > void, and functions declared with (void) parameters, why one would want > to cast to (void), and so forth. Yes, I was thinking about that. > > You're starting to document the C language here, and if you're going to > do that you might as well do it right. I'm trying to do so :) Thanks, Alex