[IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

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 at gmail.com> 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/