Hi Michael, On 9/13/20 2:01 PM, Michael Kerrisk (man-pages) wrote: > Hi Alex, > > On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote: >> >> Hi Michael, >> >> On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote: >> > 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. >> >> libbsd already provides a few pages on types. Maybe we could have a >> look at them. At least I've seen 'man timespec' (which redirects to >> timeval.3bsd): >> >> https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd >> >> > >> > 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. >> >> I think that would be reasonable. >> >> No, I don't have a PDF. I usually search here: >> >> https://pubs.opengroup.org/onlinepubs/9699919799/ > > You can get a PDF by registering as a member of The Open Group. I > think the necessary info is here: > https://www.opengroup.org/austin/lists.html > (I find having everything in a single PDF is useful for searching.) Thanks. > >> > 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 >> >> That would just be 1 or 2 more lines in the explanation, I guess. > > Yes, I guess. > >> That's also similar to the typical (mis?)use of size_t as a ptrdiff_t. >> >> > 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.) >> >> I agree in that everything should be centralized, at least in the >> beginning. That would make it much easier to maintain and find the >> information. If the future requires the information to be spread >> across many pages, let the future solve that problem :) >> >> > >> > 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) >> >> I'd say here is missing the POSIX requirements on the type. > > As far as I can tell, in the case of timer_t, I think there are no > requirements in POSIX. > >> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned? > > POSIX doesn't specify, I think.> > One other thing the page should show of course is definition of the > structure types. Yes. timer_t <time.h> or <sys/types.h> POSIX timer ID. typedef void *timer_t; Conforming to: POSIX.1-2008. See: timer_create(2), timer_delete(2), timer_getoverrun(2), timer_settime(2) Like this? Should I specify somehow if the type definition is so for Linux only, or for all POSIX, ...? sources: x86_64-linux-gnu/bits/types/timer_t.h:7:typedef __timer_t timer_t; x86_64-linux-gnu/bits/types.h:171:__STD_TYPE __TIMER_T_TYPE __timer_t; x86_64-linux-gnu/bits/types.h:126:# define __STD_TYPE typedef x86_64-linux-gnu/bits/typesizes.h:70:#define __TIMER_T_TYPE void * This is so for my Debian x86-64. However, I don't know if this is the definition for all architectures. I'll start with what I can do, and if you see any type that you know has a different definition in other systems, I'll let that to you :) > >> > 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 >> >> Sure. And for the structs, I'd allow: >> >> 'man struct timespec' (For simplicity) >> 'man struct-timespec' (Similar to the git man pages) >> 'man timespec' (For compatibility with libbsd) > > Mainly, I'm interested in the last case. That's the one I think that > people would most likely use. In a follow-up mail, you expressed > concern with conflicts with libbsd pages. I'm not too worried about > that. There are already *many* conflicts between libbsd and man-pages. I wasn't concerned about conflict with libbsd; that's the form libbsd uses, and a good point for having that form would be for compatibility (people will probably like having to write 'man timespec' in any system and work). I was instead concerned that some struct tag may have the same name as some function, which I don't know for sure: Let's say there exist a function 'int foo(void)', and a 'struct foo'. If that is the case, which I ignore, you would need to either have 'foo.3' and 'foo.3t' or have 'foo.3' and 'struct-foo.3'. Your thoughts? > >> > For the moment at least, I'd favor the "one big page plus >> > links" approach. >> >> Yes. > > Would you like to take a shot at this? I'd suggest just a simple page > covering just two or three types to start with. Maybe time_t and > timer_t, or otherwise some types that seem good choices to you? Yes, I'd like to. It'll be my first page from scratch, though, so don't expect it to be soon :-} Maybe 'timer_t', 'time_t' and 'struct timespec' would be a good start. Do you think there's any page that has a similar format to what we want to base on it? > > Thanks, > > Michael > > Thanks, Alex
