Hi Alex, On 9/13/20 2:53 PM, Alejandro Colomar wrote: > 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: [...] >>> 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; Here I would *not* show these kinds of typedefs. The point is that these types should be treated as being somewhat unknown (e.g., for casts in printf()). Here, I think instead maybe we just have a statement that POSIX makes no specific requirements for the representation of this type. > 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, ...? See the above comment. [...] >>> 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? Offhand, I can't think of any such conflicts. Many of the data types have names suffixed with "_t", and there should be no conflicts there. For other types, such as timeval, timespec, etc, I don't expect there are many conflicts. One case that I can think of where there's a function and a struct with the same name is 'sigaction'. But there's not really a problem there, since, on the one hand, I don't expect that that is one of the types that should be documented in system_data_types(7), and on the other hand, currently "man sigaction" takes you to the page that documents both the function and the structure. >>> > 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. Throw in 'struct timeval' too? > Do you think there's any page that has a similar format to what we want > to base on it? I think nothing special is required. See man-pages(7) for general info on the layout of pages. I expect the types can be placed as an alphabetically ordered hanging list under DESCRIPTION. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
