New: man pages for C structs
https://bugzilla.kernel.org/show_bug.cgi?id=57181
Summary: man pages for C structs
Product: Documentation
Version: unspecified
Platform: All
OS/Version: Linux
Tree: Mainline
Status: NEW
Severity: enhancement
Priority: P1
Component: man-pages
AssignedTo: documentation_man-pages-ztI5WcYan/[email protected]
ReportedBy: serge+bugzilla.kernel.org-mibDF1kqFMcdnm+yROfE0A@public.gmane.org
Regression: No
It would be useful to be able to search for the name of a C struct to get its definition with an explanation of its fields.
If having separate pages for each struct is undesirable, these could simply be troff includes ('.so') of a page which actually describes the struct. i.e. "man timeval" (or maybe "man 'struct timeval'") could bring up the page for 'gettimeofday'.
Signature · 7 lines
Configure bugmail: https://bugzilla.kernel.org/userprefs.cgi?tab=email ------- You are receiving this mail because: ------- You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): bug-57181-11311-3bo0kxnWaOQUvHkbgXJLS5sdmw4N0Rt+2LY78lusg7I@public.gmane.org/
[Bug 57181] man pages for C structs
https://bugzilla.kernel.org/show_bug.cgi?id=57181
Michael Kerrisk <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
CC| |[email protected]
--- Comment #1 from Michael Kerrisk <[email protected]> --- Serge,
I'm undecided about this idea. I'd like to see it fleshed out a little. FOr example, list a few more structs and (existing) pages that could be linked with .so.
Thanks,
Michael
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 57181] man pages for C structs
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=57181
--- Comment #2 from Serge van den Boom <serge+bugzilla.kernel.org-mibDF1kqFMcdnm+yROfE0A@public.gmane.org> --- Ok, how is this for a start:
timeval -> ctime(3)
timespec -> nanosleep(2)
sockaddr -> bind(2)sockaddr_in -> ip(7)in_addr -> inet(3)in_addr -> ip(7)in_addr_t -> inet(3)sockaddr_in6 -> ipv6(7)in6_addr -> ipv6(7)
addrinfo -> getaddrinfo(3)
iovec -> recv(2)
msghdr -> send(2) / recv(2)
cmsghd -> cmsg(3)
dirent -> readdir(3)
pollfd -> poll(2)epoll_event -> epoll_ctl(2)
rlimit -> getrlimit(2)
To further illustrate why this would be useful, consider the following
situation: you are coding in C and want to use sendmsg(). Before you write that line, you would define a struct msghdr, and fill its fields. But you don't recall what exactly the fields of struct msghdr should contain. Right now, you'd go through the following steps:
1. Where would I find the definition of msghdr? I want to use it in 'sendmesg', so that's probably where it is.
2. 'man sendmesg'
3. search for msghdr
With separate pages per struct, you would be able to skip steps 1 and 2. In fact, if you use Vim, you would just enter 'K' when the cursor is on 'msghdr'. With redirects, you'd still have step 3, but you wouldn't have the (distracting) step of deciding where you'd expect to find it.
(Also, 'struct mesghdr' includes a field of type 'struct iovec', which is not defined in send(2). This is probably a separate issue though.)
For structures like sockaddr_in, step 1 is even harder, as there is no clue to where to find a page on its definition. You would have to know somehow that it can be found in ip(7).
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 57181] man pages for C structs
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=57181
--- Comment #3 from Michael Kerrisk <[email protected]> --- (In reply to Serge van den Boom from comment #2)
Quoted 4 lines
Ok, how is this for a start:
timeval -> ctime(3)
timespec -> nanosleep(2)
So here's an example of ptroblem. 'struct timespec' is in 15 pages. Why point to this one in particular. I can see it's not a bad page to point to. But, if you are using one of the other APIs, then laning on nanosleep(2) would be confusing.
Quoted 31 lines
sockaddr -> bind(2)
sockaddr_in-> ip(7)in_addr-> inet(3)in_addr-> ip(7)in_addr_t-> inet(3)sockaddr_in6-> ipv6(7)in6_addr-> ipv6(7)
addrinfo -> getaddrinfo(3)
iovec -> recv(2)
msghdr -> send(2) / recv(2)
cmsghd -> cmsg(3)
dirent -> readdir(3)
pollfd -> poll(2)epoll_event->epoll_ctl(2)
rlimit -> getrlimit(2)To further illustrate why this would be useful, consider the following
situation: you are coding in C and want to usesendmsg(). Before you write that line, you would define a struct msghdr, and fill its fields. But you don't recall what exactly the fields of struct msghdr should contain. Right now, you'd go through the following steps:
1. Where would I find the definition of msghdr? I want to use it in 'sendmesg', so that's probably where it is.
2. 'man sendmesg'
3. search for msghdr
With separate pages per struct, you would be able to skip steps 1 and 2. In fact, if you use Vim, you would just enter 'K' when the cursor is on 'msghdr'.
With redirects, you'd still have step 3, but you wouldn't have the (distracting) step of deciding where you'd expect to find it.
Quoted 6 lines
(Also, 'struct mesghdr' includes a field of type 'struct iovec', which is not defined in send(2). This is probably a separate issue though.)
For structures like
sockaddr_in, step 1 is even harder, as there is no clue to where to find a page on its definition. You would have to know somehow that it can be found in ip(7).
I don't really buy this reasoning. If I'm using sendmsg(), then I'm probably on that page already before step 1.
So, I don't think this approach (llinks as described above) is really helpful.
Now, whether there should be separate pages for a few structures is something to think about more, but I'd need to see a good reason in each case. (sigevent(7) had a good reason, for example.)
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 57181] man pages for C structs
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=57181
--- Comment #4 from Serge van den Boom <serge+bugzilla.kernel.org-mibDF1kqFMcdnm+yROfE0A@public.gmane.org> ---
Quoted 4 lines
So here's an example of ptroblem. 'struct timespec' is in 15 pages. Why point to this one in particular. I can see it's not a bad page to point to. But, if you are using one of the other APIs, then laning on nanosleep(2) would be confusing.
I am not singling out 'struct timespec'. In my opinion, we would benefit from being able to use *any* structure name as a keyword to man. My list was intended to show the wide variety of non-trivial structures which one might want to look up.
You are right that if you are using one of the other functions, that landing up on another one than the one which you are actually using, might sometimes be confusing. And in fact, I would prefer to have a separate page for each structure. However, even if you sometimes end up on a page of another function which uses the same structure, this is better than having no match at all. At the very least, it gives you a starting point for subsequent searches. And often, you *will* end up at the right page. Or even if it is the wrong page, the structure description will be usable.
For me, being able to press 'K' in Vim on some structure name to find out what fields it has, is reason enough to want the structure name to lead somewhere.
Quoted 3 lines
Quoted 1 line
[...]
I don't really buy this reasoning. If I'm using
sendmsg(), then I'm probably on that page already before step 1.
Ok, this may not be the most realistic example, but the idea holds for any of the structures. Maybe sockaddr_in works better for this example.
Also, having structures as man keywords doesn't just help with writing code, but also with reading someone else's code. If you read code in the order in which it occurs, you'll see the structure being filled before it is passed to some syscall or C library function. In fact, the actual call may be in another (user) function altogether. If you want to know more about what exactly those values being assigned to the various fields mean, you just want to lookup the structure name, instead of first having to figure out in what function it might be used.
And I sometimes use these standard structures in my own code (why reinvent the wheel?). In one real-life example, I needed to have some structure to store a time period in, and I know that various standard types exist (struct timeval, struct timespec, time_t), but I couldn't recall the details of each type. So to find out which would be the most suitable, I would have had to think of various standard functions which would use these types. (Though I might have ended up grepping in /usr/include instead; I don't recall exactly. Maybe both even.)
But even though I'm now trying to think up all sorts of past and hypothetical situations where it would be useful to be able to look up a structure by its name, the reason why I originally took the time to write the bug report (and the follow-ups now, a year later), is because I have in fact (on multiple occasions) felt the need to perform such lookups. And if I have, so will have others.
Quoted 1 line
Now, whether there should be separate pages for a few structures is something to think about more, but I'd need to see a good reason in each case. (sigevent(7) had a good reason, for example.)
I personally would like to be able to search for *every* standard structure, and for typedefs too actually. Even if the resulting pages just contain a reference to the pages of functions which actually use the type, this would be of value. But ideally, the specifics of the fields would be explained there as well.
I understand that this might be too much work to actually implement, but I do think that the value is real. Maybe I'll even submit a patch myself one day, if this is the situation.
Regards,
Serge
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 57181] man pages for C structs
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=57181
--- Comment #5 from Michael Kerrisk <[email protected]> --- So, here's an idea...
A man page, called (say) structures.7, with suitable .so links to it, that lists the structures, optionally explains them, and has links to the APIs that use the structures. Doesn't need to be done for all structures to start with, but could be implemented incrementally over time. Do you want to start writing such a page, Serge? As a proof-of-concept, I'd suggest starting with just one or two structures on the page.
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 57181] man pages for C structs
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=57181
Mike Frysinger <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
CC| |[email protected]
--- Comment #6 from Mike Frysinger <[email protected]> --- is there a reason man -K 'struct rlimit' isn't acceptable ? seems a lot easier than trying to hand maintain a page of links. unless you wrote a script that grepped all the current man pages and generated the main content on the fly.
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
[Bug 57181] man pages for C structs
In reply to a message not in the archivehttps://bugzilla.kernel.org/show_bug.cgi?id=57181
Michael Kerrisk <[email protected]> changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |RESOLVED
Resolution|--- |WILL_NOT_FIX--- Comment #7 from Michael Kerrisk <[email protected]> --- No suitable solution proposed here, so I'm closing this.
Signature · 6 lines
You are receiving this mail because: You are watching the assignee of the bug. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html