Welcome to WebmasterWorld Guest from 18.104.22.168
Forum Moderators: bakedjake
Manpages are rather important in the UNIX world. Once you figure them out, your mindset becomes warped enough that the overall UNIX picture becomes less cryptic. :)
Manpages were introduced to help programmers understand what the specific syntax of something is. As such, their main benefit is to tell you the exact usage of a command or function that you're thinking of. The sad part is that they do not answer the question of "how do I do ...?" easily (more about this later).
UNIX breaks manpages down into various sections to allow you to find specifically what you're looking for. They exist to minimize confusion, although novices often get even more confused by them.
For example, there is both a command "chown" and a kernel system call "chown". If you were writing a C-program and needed the details on chown(2), you wouldn't find the chown(1) manpage very useful.
Man is also smart enough to scan the sections when you look something up. For example, when you type "man setuid", it searches through the sections and pulls up the first match -- in this case setuid(2). The order of this search is detailed in /etc/man.conf on some flavors of UNIX (namely, the BSDs), but may be hardcoded into the man(1) binary itself.
If you notice how I wrote out "foo(#)" above, that's how we specify "look at manpage for `foo' in section #". If I ask you to look up magic(5), you'd look in section 5 for "magic". Hardcore unix geeks such as myself shortcut this usage such that "foo(3)" means "function `foo'" and "baz(8)" means "sysadmin utility `baz'." As you can imagine, some geek jokes can be had from this.
In the BSD world, the sections are broken down as follows:
(1) general commands (tools and utilities)
(2) (kernel) system calls and error numbers
(3) C libraries
(4) devices and drivers
(5) files (file formats)
(7) misc information
(8) system maintenance and operation commands
(9) kernel internals
I pulled these from NetBSD. OpenBSD is identical (since it's really NetBSD with local hacks added) and FreeBSD should be very similiar.
In the SYSV ("System Five", most commercial flavors of UNIX) world, the sections are:
(1) general commands
(1M) system maintenance commands
(2) (kernel) system calls and error numbers
(3) functions and libraries
(4) file formats
(5) misc information
(6) demonstrations and games
(7) special files
These were pulled from Solaris, other commercial flavors of UNIX (i.e. HP-UX, AIX) should be similiar.
The way to determine what you have on your particular UNIX system is to look at the "intro" manpage of each section. Most systems will take "man 1 intro", "man 2 intro", ... but Solaris requires that you use "-s <section>" as-in "man -s 1 intro". Some flavors of UNIX allow both! You can "man man" to find the syntax required, but we haven't covered that yet.
The syntax breakdown specified in manpages is effectively its own language. I can't [u]underline[/u] here, so I'll italicize the following to indicate underlines.
We'll start out with the man(1) manpage. Solaris gives me one possible use of "man" as:
man [ - ] [ -adFlrt ] [ -M [i]path[/i] ] [ -T [i]macro[/i]-[i]package[/i] ] [ -s [i]section[/i] ] [i]name[/i] ...
Some basic rules on the language used above:
* Spaces are inconsequential (as with most of UNIX) -- one space means the same as 5. Most manpages are "fill justified" (both left and right), so you'll find extra spaces littered throughout.
* Items in  are optional. Items which have no keywords are clustered within one  pair and start with a `-' -- these are independantly optional. Other items require keywords and are not included in the "bundle", but are listed afterward.
* Items underlined are keywords. Their description is covered later in the text of the manpage.
* Order is generally unimportant within s, but the general order is important, particularly when interlacing options and keywords.
* "¦" means "or"
* "..." means "one or more of these"
So, with that in mind, let's break down the syntax.
"man" (the command itself) is required, so they list it. It has to be first (as with almost all operating systems).
"-" is optional.
-a is optional
-d is optional
-F is optional
-l is optional
-r is optional
-t is optional
All of these (-a to -t) can be combined in any order, so something like "man -alft ls" would be acceptable (even though it gives the same output as "man -f").
"-M path" is optional, we expect "path" to be described in sufficient detail later in the manpage.
"-T macro-package" is optional, we expect "macro-package" to appear later in the manpage to tell us about it.
"-s section" is optional.
"name" is not optional. You must supply this to make use of the man command. "name" will show up in the text of the manpage later.
"..." means that you can supply more than one "name" (as with most UNIX commands).
[big]Other items of note within manpages[/big]
You should see a breakdown of what each of the options do. They may be a short one-line blurb, or they may be a multi-paragraph. Manpages are generally noisy enough that you have to search for the options. I use less(1) to browse the manpages ("setenv PAGER less" or "export PAGER=less") so that I can type "/-a" to search for "-a".
The FILES section towards the bottom of the manpage is often useful to see what files are related to the command/function/library you are looking up.
The "SEE ALSO" section after FILES lists manpages that are remotely related to what you are looking at. Sometimes you have to worm your way through a chain of manpages as you find them in "SEE ALSO" to get exactly what you are seeking.
NOTES and BUGS are sometimes useful, but generally don't mean much to the common user. Sometimes you'll see some humor injected by a programmer who's had a long day.
If your system is set up properly (beat on the sysadmin), you may be able to dig for commands and get a list of relevant matches with a one-line description.
Since this performs a simple search on a db-like file, looking for things like "ls" will show you everything that have the two-character sequence "ls" in them. In this respect, it isn't very useful and you'll be swamped under a lot of garbage information.
For example, if you wished to change the permission on a file, you can perform a "man -k permission" or "apropos permission" (they're the same, really), and the output would be something like...
: saturn; man -k permission
aclfrommode acltomode (3sec) - convert an ACL to or from permission bits
acltomode acltomode (3sec) - convert an ACL to or from permission bits
check-permissions check-permissions (1m) - check permissions on mail rerouting files
chmod chmod (1) - change the permissions mode of a file
chmod chmod (2) - change access permission mode of file
fbtab logindevperm (4) - login-based device permissions
fchmod chmod (2) - change access permission mode of file
logindevperm logindevperm (4) - login-based device permissions
uucheck uucheck (1m) - check the uucp directories and permissions file
XmTextFieldGetEditable XmTextFieldGetEditable (3/3x) - A TextField function that accesses the edit permission state
XmTextFieldSetEditable XmTextFieldSetEditable (3/3x) - A TextField function that sets the edit permission
XmTextGetEditable XmTextGetEditable (3/3x) - A Text function that accesses the edit permission state
XmTextSetEditable XmTextSetEditable (3/3x) - A Text function that sets the edit permission
A quick scan of this and after spotting "change the permissions mode of a file", you know that you're looking for "chmod(1)". Armed with the knowledge that (1) are commands and (2) are not, you know that chmod(2) won't give you the right information.
While novices use this to answer "how do I ...?" questions, it often fails horribly. Unfortunately, these descriptions are established by geeks with a heavy UNIX mindset. If you aren't thinking remotely like them, you'll easily get frustrated trying to find things. The adage "you must ask the right question to get the right answer" is rather important here.
I think I've covered everything related to using manpages. Any questions?
I should mention a trick I used when I was first learning unix. I went to almost ever directory listed in my path ('echo $path' to see your path) and tried to figure out what all the commands there were.
This means I spent a whole day reading man pages on everything in /usr/bin and places like that which sounded interesting. By the end of the weekend I had learned a lot of commands and forgotten even more. At least I knew that there were commands to do a lot of things I wanted, and by using "man -k" I could find them again.
It takes a lot of work to do it that way, but it really helped me find my way around unix.
After reading this tutorial I typed 'man man' and spent the last 1/2 hour reading about all the functions. I played a bit with -K (capital K) function. I got to say your tutorial was so well written that I don't have any questions at this time.