Unix manual pages can look like an illegible mess if you're not used to them. The SYNOPSIS section at the top lists the syntax of the command; the syntax of this listing itself calls for some explanation.

Stuff inside brackets is optional. Usually these are flags.

Things with a bar between them are alternatives - they're mutually exclusive.

Underlined words that are not bold (if you're not on FreeBSD the text style might differ from what I'm saying but it'll be consistent across the system) are not to be typed literally; they're descriptions of parameters. For example, the synopsis:

dosomething [-f | -q] [-w] file

means the command is called dosomething, and it takes an argument which should be the name of a file. The command supports three flags: -w, -q, and -f; -f and -q are mutually exclusive. Exactly what each flag does will be described in the rest of the command's manual page.

... means multiple things can be put here. If the dosomething command's synopsis had said:

dosomething [-f | -q] [-w] file ...

That would mean you can pass it more than one filename and it'll do whatever it does to all of those files. (Almost all commands allow this.)

Sometimes the synopsis is also specified in multiple parts, like:

dosomething [-f | -q] [-w] file ...
dosomething -h

This would mean that the command can be used like above, or it can be used as just dosomething -h with no other flags or operands. (Usually if a command has a -h flag, it stands for 'help' and causes the command to print a short description of how to use it instead of doing anything.)

There's a web version of the FreeBSD manual pages, and it looks much nicer, but you still need to know the synopsis syntax.

Manual sections

There are manual pages on more than just usable commands. The manual is organized into a number of sections, with section 1 usually being for general commands and section 8 being for system administration commands. Section 5 is for information about file formats, sections 2, 3, 4, and 9 are for programmers, section 7 is for "miscellaneous information" (section 6 is "games" but that's a misleading name). Normally the man command will search all the sections and show you the first one that matches the argument you specify. If you want to only search for pages in a specific section, you can do something like man 1 ls to search for a page on something called ls in section 1. The -a flag will show all the matching pages found in sequence.

When we want to talk about a specific manual page by section, we might write it as ls(1) for example, to specify that we're talking about the page on ls in section 1, incase there are pages on it in other sections.



Comments

You don't need an account or anything to post. Accounts are only for email notifications on replies. Markdown formatting is supported.