Hi Alex, On 9/11/20 2:47 PM, Alejandro Colomar wrote: > Hello Michael, > > In the past, when I was beginning to learn C, I had a lot of trouble > with the types. > > When you want to know about a function, you just type 'man function' and > that tells you everything you need to know. > > However, when you need to use a type, such as a struct or one of those > weird POSIX types (e.g., loff_t), the only solution is to grep through > the system headers (e.g., 'cd /usr/include/; grep -rn "struct > timespec"'), unless you already know in which man page the type appears. > > I remember well when I wanted to use 'ssize_t' for the first time: it > was a nightmare to find which header I had to include to get it. > > Do you agree that it would be a good idea to write man pages for the > types, or at least write link pages that link to the page where the type > is mentioned? Your not the first to suggest this. Most recently, if I recall correctly, Florian also suggested it. The idea seems reasonable, but I wonder about the best way of doing it. I propose the desired information for each type would be * Type name * Short explanation of the type (often this mcould be just a few words, I think) * Whether the type is specified in POSIX; POSIX requirements on the type. * Header file that defines the type (in some cases, there may be more than one. This info can be discovered in the POSIX spec. (Alex, do you have a PDF of the POSIX spec?) * Cross references to manual pages of relevant APIs that use the type. There are some weird corner cases. For example, clock_t: * times(2): clock_t == clock ticks (sysconf(_SC_CLK_TCK)) * clock(3): clock_t measures in CLOCKS_PER_SEC Then, do we do one page per type? At first glance, that seems unwieldy to me. (I could be wrong.) And it seems to me that there might be benefits in having all of the information in one place rather than spread across multiple pages. (For example cantralizing the info would make it easier for the reader to get an overview.) Alternatively, we could have one big page that is a list of the types with the above information. Say "system_data_types(7)". That page might be an alphabetically ordered hanging list of entries that look like this: timer_t <time.h> or <sys/types.h> POSIX timer ID. Conforming to: POSIX.1-2008. See: timer_create(2), timer_delete(2), timer_getoverrun(2), timer_settime(2) Then of course, we'd need to have links to that page, so that people could just type 'man timer_t'. What section should the links be in? The reasonable candidates would be section 3 or 7. I'm not yet sure which is better. But the point is that we'd have files such as timer_t.3 (or timer_t.7) that are link pages containing the line: .so man7/system_data_types.7 For the moment at least, I'd favor the "one big page plus links" approach. Your thoughts? Thanks, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/