In what section do descriptions of C data-structures go?

Question

I read the following answer QA about what the various sections of the man-pages represent: What do the numbers in a man page mean?

Upon reading it, I wasn't sure what section is for descriptions of C data-structures. Does it go in section 3 just like descriptions of C functions, or does it go in a different section?

What is important is that I learn what section a man-page about a C data-structure goes -- and that the answer I receive isn't specific to one specific flavor of the OS family. I need an answer that is standard across all of them.

John WH Smith · Accepted Answer · 2014-12-23T14:59:35.157

C structures are usually detailled in the man page of the feature or function they're most associated with. For instance:

The struct sockaddr structure is defined in bind(2) (system call).
The struct utmp structure is defined in utmp(5) (file formats: utmp).

It is also not specifically required from developers to provide details about their structures in man pages, since this is basically the job of nicely-commented header files (see /usr/include).

In general, if you're looking for details about a structure, have a look at the function you're using it for. For instance, if you want to know more about asctime's argument (struct tm), just have a look at asctime's man page. Most structures come with a set of functions used to manipulate them, and these usually have a man page. If there is no function associated to your structure, here are a few options:

The structure is closely related to a concept (e.g. struct sockaddr_un for UNIX sockets). Have a look at the man page associated to that concept (here, unix(7)).
The structure is associated to a file, or is used to parse this file (e.g. struct utmp) : have a look at this file's man page if it has any (here, utmp(5)).
The structure does not seem to be documented in any man page, have a look at the header file it is defined in. Here is the example of struct ifaddrs, even though it has a man page at getifaddrs(3):

File: /usr/include/ifaddrs.h

struct ifaddrs
{
   struct ifaddrs *ifa_next;     /* Pointer to the next structure.  */

   char *ifa_name;               /* Name of this network interface.  */
   unsigned int ifa_flags;       /* Flags as from SIOCGIFFLAGS ioctl.  */

   struct sockaddr *ifa_addr;    /* Network address of this interface.  */
   struct sockaddr *ifa_netmask; /* Netmask of this interface.  */

   // ...
};

Thanks. :-) Of course, the structures I am trying to document are effectively an object-type and a matching class-type - and in the class-type, the elements are all function-pointers that serve as methods. I suppose that if I have to pick a function to be the flagship-function of this structure, it should be the main object-creation function. — Sophia_ES, Dec 23 '14 at 15:23
Oh --- I perhaps should have been more clear about this in my question --- but what I was trying to learn wasn't where in the man-pages to find documentation, but rather, where in the man-pages to put documentation. I didn't mention that in my question because until I saw your answer, I didn't realize that this detail was relevant. — Sophia_ES, Dec 23 '14 at 15:57
Well, my answer still gives you some clues about it. To me, the most important thing is to document header files correctly, because they are the closest to your code. Add information about each member, and try to give details about your functions. Now, how you document the rest of your code with external tools is mostly up to you (manual pages, HTML doc, PDF doc, ...). — John WH Smith, Dec 23 '14 at 16:03

In what section do descriptions of C data-structures go?

1 Answers1