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: Navigational corrections
Hi Michael, On 2020-10-03 10:00, Michael Kerrisk (man-pages) wrote: > 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'm fine with removing them. I only added them because while I was adding [u]intN_t, they were in the same page, and I just took them too. No problem with removing them. To be clear, I should remove [u]int_*astN_t, right? > > I don't think 'void' belongs in this page. Nor basic types > such as int, long, etc. Fine. > > 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 ar
Re: Navigational corrections
Hi Alex, > > > > 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), > > Actually, not. > Its good to have you tell me what is good for the man and what's not. > Otherwise, I wouldn't know. > I keep a branch with all of the rejected patches, > just to have an idea of what I should not send you :-) > > > 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. > > Well, I didn't have a clear roadmap. > I had some types which I clearly wanted to document, > and they were ptrdiff_t, and ssize_t, > which I documented in the first patches, > and then I was finding related types, > and also tended to document about types which I knew very well too, > to have something useful to add to the description. > > I may now start writing about off_t and related types, > which were the ones that made me want this page. off_t would be great. In case you are looking for some other candidates, some others that I would be interested to see go into the page would be fd_set clock_t clockid_t and probably dev_t 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 0/2] Document void *
Hi Jonathan! On 10/2/20 3:19 PM, Jonathan Wakely wrote: > On Thu, 1 Oct 2020 at 16:51, Alejandro Colomar via Gcc > wrote: >> >> Hi Michael, >> >> On 2020-10-01 17:34, Michael Kerrisk (man-pages) wrote: >>> Hello Alex, >>> >>> On 10/1/20 5:06 PM, Alejandro Colomar wrote: Hello Michael, This type is very special, so I will probably have missed some details about it. >>> >>> I do wonder if we actually need this in page at all, and given: >> >> >> I think it should be. >> I would also document 'void', even if it's a bit weird... >> They are very useful, so why not document them? > > Because the man-pages are not a tutorial for the C language. > > "The Linux man-pages project documents the Linux kernel and C library > interfaces that are employed by user-space programs." > > void and void* are not APIs. Agreed, but the rationale of the page is to document topics that are helpful when using the APIs. And, as I noted already stuff like 'void *' is borerline, but I think it's helpful to have some info summarized in one place. And, additionally, POSIX adds a detail to the C standard (casting between void * and function pointer). By the way, thanks for all of your input so far. Among other things, it made me realize that some navigational corrections were needed. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Copyright assignment form
Hello. I'd like a copyright assignment form for all my future contributions to gcc. Thanks.
gcc-10-20201003 is now available
Snapshot gcc-10-20201003 is now available on https://gcc.gnu.org/pub/gcc/snapshots/10-20201003/ and on various mirrors, see http://gcc.gnu.org/mirrors.html for details. This snapshot has been generated from the GCC 10 git branch with the following options: git://gcc.gnu.org/git/gcc.git branch releases/gcc-10 revision 7e31dbb706934374ab2f709035dc43aaafe444dd You'll find: gcc-10-20201003.tar.xz Complete GCC SHA256=800ec6fb41dd74269724ff6bb318785bc803cd73104f837130b29bb694cce052 SHA1=e8d18b1d455e01eb7ea61fd33012e761dac296b8 Diffs from 10-20200926 are available in the diffs/ subdirectory. When a particular snapshot is ready for public consumption the LATEST-10 link is updated and a message is sent to the gcc list. Please do not use a snapshot before it has been announced that way.
