Man pages: How to use arguments

Question

Ultimately, I want to be able to know how to use a function without having to look up an example online.

For example, if I do man 2 mkfifo it displays:

NAME
     mkfifo -- make a fifo file

SYNOPSIS
     #include <sys/types.h>
     #include <sys/stat.h>

     int
     mkfifo(const char *path, mode_t mode);

DESCRIPTION
     Mkfifo() creates a new fifo file with name path.  The access permissions are specified by mode and restricted by the umask(2) of the calling process.

     The fifo's owner ID is set to the process's effective user ID.  The fifo's group ID is set to that of the parent directory in which it is created.

const char *path is pretty self-explanatory, and I would have no trouble calling mkfifo function with that argument, but my concern is more with the mode_t argument. The man pages give a small explanation as to what the mode is for, but doesn't explain how to use it in order to call the function with it.

Is there any way to navigate through man pages to understand such arguments?

I tried doing man mode_t, man mode and nothing came up.

Answer 1

The man page is assuming some familiarity with the other places that you would use a mode flag when it says:

It is modified by the process's umask in the usual way: the permissions of the created file are (mode & ~umask).

However, if you go through each of the pages in the “See Also” section:

SEE ALSO

mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2), mkfifoat(3), fifo(7)

you'll eventually get to open(2), which gives an exhaustive list of the modes that you can use. That is, the man page that you visit with man 2 open includes (while describing flags):

 O_CREAT If  the  file  does  not  exist  it will be created.  The owner (user ID) of the file is set to the effective user ID of the process.  The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and  the  mode  of  the  parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

mode  specifies  the permissions to use in case a new file is created.  This argument must be supplied when O_CREAT is specified in flags; if O_CREAT is not specified, then mode is ignored.  The effective permissions are modified by the process's umask in the usual way: The permissions of the created file are (mode & ~umask).  Note  that  this mode only applies to future accesses of the newly created file; the open() call that creates a read-only file may well return a read/write file descriptor.

The following symbolic constants are provided for mode: …

Another approach that you may find useful is to search for information about the includes that the man page specifies. For instance, Googling for sys/types.h or sys/stat.h turns up:

• a man page for sys/types.h, which is not particularly useful in this case, and
• a man page for sys/stat.h, which enumerates a bunch of symbolic constants for various modes.

I realize that this doesn't preclude having to "look up an example online". Some systems may include man pages for the headers, but others may not.

Answer 2

What you asked for already exists, it's the command info. Try:

info mkfifo

You'll get something like this:

 -- Function: int mkfifo (const char *FILENAME, mode_t MODE)
     The `mkfifo' function makes a FIFO special file with name
     FILENAME.  The MODE argument is used to set the file's
     permissions; see *note Setting Permissions::.

If you move the cursor over the *note Setting Permissions::. bit and press ENTER you'll be taken to the umask page with a fairly more detailed description of file permissions.

Also, info can read man pages when only man pages for a given topic are available. In short, you never have to use man again.