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.

http://pubs.opengroup.org/onlinepubs/7908799/xsh/sysstat.h.html — Oliver Charlesworth, Sep 19 '13 at 19:52
Also, it is the same mode bits used for [`open()`](http://linux.die.net/man/2/open). — jxh, Sep 19 '13 at 19:54
In this particular case, the modes are described more in the man page, section 2, for open. — Joshua Taylor, Sep 19 '13 at 19:55
@OliCharlesworth I understand I could open up a browser to look it up, but is there a way to navigate man pages? (is that also a man page?) — Brandon Ling, Sep 19 '13 at 19:56
[Here is a page that describes mode_t.](http://www.kneuro.net/cgi-bin/lxr/http/ident?i=mode_t). But I am not aware of if the man pages have a method of searching "data types" in general. — ryyker, Sep 19 '13 at 19:57
man pages are famously dense and hard to jump between. Try following up on the "See also section" in the man page or looking for relevant commands with the "apropos" command in your shell — 3rf, Sep 19 '13 at 19:59

Joshua Taylor · Accepted Answer · 2013-09-19T20:12:36.347

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.

That's describing the `flags` parameter. You want the 3 argument version of `open()`, where the third argument is `mode`. — jxh, Sep 19 '13 at 20:01
For me, the SEE ALSO doesn't include open(). It only says "chmod", "stat", "umask", but apparently stat is what Oli was referring to above — Brandon Ling, Sep 19 '13 at 20:01
@BrandonLing: Check again, make sure you type `man 3 mkfifo`. — jxh, Sep 19 '13 at 20:02
@jxh, it says no man page for that. Only man 2 mkfifo works for me. — Brandon Ling, Sep 19 '13 at 20:03
@jxh Yes, the manpage in section 3 for mkfifo (on Ubuntu, anyhow) includes "SEE ALSO mkfifo(1), close(2), open(2), read(2), stat(2), umask(2), write(2), mkfifoat(3), fifo(7)". — Joshua Taylor, Sep 19 '13 at 20:03
Okay, BSD flavor. So, the command you want to check is the `man 2 chmod`. — jxh, Sep 19 '13 at 20:07

score 1 · Answer 2 · answered Sep 19 '13 at 20:16

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.

Man pages: How to use arguments

2 Answers2

SEE ALSO