TweetFollow Us on Twitter

Apr 02 Mac OS X

Volume Number: 18 (2002)
Issue Number: 04
Column Tag: Mac OS X

The BSD Man Pages

by Rich Morin

How to find them; how to read them.

Welcome

"Section 7", the name of this column, is also the shorthand term for the "Miscellaneous Information" section of the Berkeley Software Distribution's manual pages (known to their friends as the BSD "man pages"). This column will feature miscellaneous information on BSD-related aspects of Mac OS X, including application design, documentation, and even the politics of the developer and user communities.

Mac OS X is the most widely-disseminated version of BSD, but many Mac developers are a bit unclear on what BSD actually is. So, a word of explanation may be in order. BSD is a well-respected operating system, with a long history of solid engineering. Derived from Unix 32V, BSD is used for network servers, firewalls, and many other mission-critical applications.

Darwin (and thereby Mac OS X) is based on the FreeBSD and NetBSD distributions. As a result, it can take advantage of a well-developed operating system environment and thousands of "ported" applications from the FreeBSD Ports Collection. Clearly, BSD's solid technology and active developer community make a powerful contribution to the Mac OS X story.

Getting Started

BSD (and other Open Source) developers maintain several thousand "man pages" (manual pages), covering a wide range of topics. Because the pages are written by developers, they tend to be authoritative, consistently organized, current, detailed, and refreshingly honest. On the other hand, they also tend to be terse, tightly focused, and a bit unpolished in spots.

Consequently, reading man pages may not be the best way to approach a new and complex topic (e.g., NFS, socket programming), but it is an extremely handy way to learn about specific commands, remind yourself about forgotten details, etc. Once you've read a few man pages, I predict that you'll get addicted to their strong points; you may even (eventually) forgive their deficiencies.

Although it isn't critically necessary, you'll find it useful (and fun!) to have some Terminal windows on hand while you read this article. For one thing, you'll be able to see the actual output of the commands I'm describing; for another, you'll be able to try things out.

Using the Finder, navigate through the Applications and Utilities folders. When you find the icon for the Terminal Utility, drag it into the Dock. Now, double-click the icon twice, creating two Terminal windows. Unlike typical applications, these windows are not closely tied to each other. In fact, each Terminal window provides an independent BSD "session".

You should probably spend a few seconds arranging the windows, so that you can see them both at the same time. Also, stretch at least one of them vertically (keeping the width constant). This will let you see more of your commands' output without scrolling.

To view a particular man page, you must ask the system to run the "man" command, giving it the name of the page you want to see. We can try this out by asking for the man page that describes the "null" device:

[localhost:~] rdm% man null
NULL(4)         System Programmer's Manual           NULL(4)

NAME
     null - the null device

DESCRIPTION
     The null device accepts and reads data as any ordinary
     (and willing) file - but throws it away. The length of
     the null device is always zero.

FILES
     /dev/null

HISTORY
     A null device appeared in Version 7 AT&T UNIX.

Headings

As the example shows, each part of the man page is introduced by a descriptive heading. Some headings (e.g., NAME, DESCRIPTION) will show up on every man page; others (e.g., FILES, HISTORY) only appear when needed. Some, finally, are invented by the page's author. Here are some common headings, in the order they would normally appear on a man page:

  • NAME The following text gives the name(s) of the described item(s), followed by a terse description. In the case of commands, only one name will typically be given. In the case of library functions, however, there may be a long list of entry points.
  • SYNOPSIS The following text gives a (stylized) description of the normal usage mode for the item(s). In the case of commands, this will show the possible option flags; in the case of system calls and library functions, it will show representative declarations, etc.
  • DESCRIPTION The following text gives an extended description of the item(s), including options, usage considerations, etc. Some descriptions go on at great length.
  • RETURN VALUES The following text describes the return values for the item(s).
  • ERRORS The following text lists possible error conditions and resulting actions.
  • FILES The following text lists related files.
  • SEE ALSO The following text lists related man pages.
  • STANDARDS The following text lists applicable standards, sometimes discussing the degree to which the described item(s) comply.
  • BUGS The following text lists ways in which the command fails to meet the documentor's expectations. Some vendors find this section embarassing, so they rename or remove it. Feh!
  • NOTES The following text lists ancillary information which is not appropriate to any of the other sections.
  • HISTORY The following text tells where (i.e., in which BSD or Unix variant) the item first appeared, etc.

Paging

With all of this detail, some man pages can (and do :) go on for quite a while. In fact, multiple-page "man pages" are quite common. So, the man command is set up to let the reader "page" through the text. The default "pager" on Mac OS X is "more"; for a rundown on its capabilities, look at its man page!

[localhost:~] rdm% man more

Although more isn't very sophisticated, it does respond to the space bar (skip to the next page), the return key (move forward one line), "q" (quit), and a few other commands. If you want more features, try the GNU Project's "less" command (less is more, more or less):

[localhost:~] rdm% setenv PAGER less

Sections

The man pages cover a wide range of topics: administrative and user commands, C language interfaces, devices, etc. If all of the topics were simply sorted together, there would be name clashes. For instance, there is a passwd file, as well as a passwd command. To keep things straight, the man pages are divided into nine sections:

  • Section 1 (General Commands). These are commands that any user might enter from the command line or use in a "shell script". Some example commands include cd, ls, and rm.
  • Section 2 (System Calls). These are C language interfaces to kernel-provided services. Note that a system call, by definition, causes a context switch into the kernel. The application is halted until the system call completes. Some example system calls include close and open.
  • Section 3 (Library Functions). These are also C language interfaces, but the function runs (in general) with the application's context. Of course, some library functions make system calls, which do context switches, as described above. Some example library functions include fopen, scanf, and sqrt.
  • Section 4 (Devices and Device Drivers). These are the external interfaces to system devices. Some devices (e.g., /dev/null, /dev/tty) are intended for direct (command-line) use; others are only accessed by application or system-level code. Consequently, the descriptions in this section vary considerably in level and coverage.
  • Section 5 (File Formats). Many BSD activities are controlled or monitored by means of files. This section describes some of the critical files that an administrator might need to read or edit. Note, however, that Mac OS X uses different administrative mechanisms than most other BSD variants, so your mileage will definitely vary!
  • Section 6 (Games). Some BSD distributions include recreational programs; others do not. By placing these programs in a special area, the operating system eases monitoring and control of their use.
  • Section 7 (Miscellaneous Information). This section includes descriptions that are not tied to any given command, file, or function. Look here for high-level introductions, etc.
  • Section 8 (System Maintenance and Operation Commands). These are commands that the system administrator might enter from the command line or use in a "shell script". Some example commands include chown, fsck, and tunefs.
  • Section 9 (System Kernel Interfaces). These are C language interfaces to kernel-provided services. They differ from system calls in that they can only be called from inside the kernel. Thus, they are only of interest to kernel programmers. Mac OS X does not currently have this section, but FreeBSD does, so I expect it to show up eventually.

Navigation

Going back to the case of passwd, we see that the passwd command would be described in Section 1, while the passwd file would be described in Section 5. The specific man pages would normally be referred to as "passwd(1)" and "passwd(5)". By default, the man command will display the first page it finds, going in ascending order through the sections. You can make sure that you get passwd(5), however, by typing "man 5 passwd". Try it!

Unlike the hierarchical "help systems", as found on Cicso routers or operating systems such as VMS, man pages have no automated support for navigation. Some experimental variants use HTML to display man pages, turning SEE ALSO entries into hyperlinks. Most man systems, however, require that you do your own navigation.

Part of the reason for this lies in the sheer scale of the BSD command set. There are several hundred commands and thousands of functions. Trying to place them all in a meaningful hierarchy (or even defensible topical groupings) is not a trivial task! Nonetheless, some help is available.

To find a man page when you don't know the exact name, use apropos(1). It displays all the "NAME" lines that contain the specified text strings. If you are trying for a text string that contains non-alphanumeric characters, be sure to enclose the string in quotes. Otherwise, you'll get all the pages that match any "word" (i.e., sequence of non-blank characters) in the string. Here are some interesting uses of the apropos command; try them out!

[localhost:~] rdm% apropos device
[localhost:~] rdm% apropos dev
[localhost:~] rdm% apropos ‘(4)'
[localhost:~] rdm% apropos ‘file system'
[localhost:~] rdm% apropos file system

Although BSD provides several hundred commands, only a few are needed for everyday use. Next month, we'll look at some basic BSD commands, as well as a smattering of shell (command line interface) syntax.


Rich Morin has been using computers since 1970, Unix since 1983, and Mac-based Unix since 1985 (when he helped Apple create A/UX 1.0). When he isn't writing this column, Rich runs Prime Time Freeware (www.ptf.com), a publisher of books and CD-ROMs for the Free and Open Source software community. Feel free to write to Rich at rdm@ptf.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Apple Security Update 2015-005 - For OS...
Apple Security Update 2015-005 is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.... Read more
Apple HP Printer Drivers 3.1 - For OS X...
Apple HP Printer Drivers includes the latest HP printing and scanning software for OS X Lion or later. For information about supported printer models, see this page. Version 3.1: The latest printing... Read more
Epson Printer Drivers 3.1 - For OS X 10....
Epson Printer Drivers installs the latest software for your EPSON printer or scanner for OS X Yosemite, OS X Mavericks, OS X Mountain Lion, and OS X Lion. For more information about printing and... Read more
Xcode 6.4 - Integrated development envir...
Xcode provides everything developers need to create great applications for Mac, iPhone, and iPad. Xcode brings user interface design, coding, testing, and debugging into a united workflow. The Xcode... Read more
OS X Yosemite 10.10.4 - Apple's lat...
OS X Yosemite is Apple's newest operating system for Mac. An elegant design that feels entirely fresh, yet inherently familiar. The apps you use every day, enhanced with new features. And a... Read more
Dash 3.0.2 - Instant search and offline...
Dash is an API Documentation Browser and Code Snippet Manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
FontExplorer X Pro 5.0 - Font management...
FontExplorer X Pro is optimized for professional use; it's the solution that gives you the power you need to manage all your fonts. Now you can more easily manage, activate and organize your... Read more
Typinator 6.6 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Arq 4.12.1 - Online backup to Google Dri...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more
Gutenprint 5.2.11-pre1 - Quality drivers...
Gutenprint is a suite of printer drivers that may be used with most common UNIX print spooling systems, including CUPS, lpr, LPRng, or others. Gutenprint currently supports over 2000 printer models.... Read more

Vector 2 is Officially a Thing and it...
Vector is a pretty cool parkour-driven runner that's gotten a pretty decent following since it first came out - although personally I think more people could stand to show it some love. Anyway, Nekki has announced that a sequel isofficially on its... | Read more »
This Week at 148Apps:June 22-26, 2015
June's Summer Journey Continues With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice,... | Read more »
LEGO® Minifigures Online (Games)
LEGO® Minifigures Online 1.0.1 Device: iOS iPhone Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: | Read more »
World of Tanks Blitz celebrates its firs...
Today marks the first anniversary of the launch of World of Tanks Blitz, the mobile version of the PC tank battler, World of Tanks. World of Tanks Blitz launched on iOS and Android on June 26th last year and to celebrate, Wargaming is giving all... | Read more »
Heroes and Castles 2 Has its Own Standal...
Heroes and Castles 2 is a third-person castle defense game from the same team behind Block Fortress and Bug Heroes. It's cool, it's fun, and now it has its very own free version. [Read more] | Read more »
Formula Cartoon All-Stars Lets You Race...
Ever want to pit your favorite characters from shows like Steven Universe, Adventure Time, and Regular Show against each other in a not quite death race? Well once upon a time you could, but Formula All Stars Touch N' Go doesn't exist anymore. Hope... | Read more »
Retype - Typography Photo Editor (Photo...
Retype - Typography Photo Editor 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Retype is built out of passion for great typography and it's all about adding text to photo with style... | Read more »
Hungry Shark Evolution Celebrates Shark...
Shark Week is almost here, as is Independence Day, so naturally Hungry Shark Evolution is going to get in on the action. Yes, even the fireworks. [Read more] | Read more »
The New Trivia Crack Will Feature a Musi...
It's official: iHeartMedia (you may know them from iHeartRadio) will be in charge of providing music-related questions for Trivia Crack's upcoming sequel. Also Trivia Crack is getting a sequel. [Read more] | Read more »
Toca Life: City (Education)
Toca Life: City 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Welcome to Toca Life: City, a metropolis filled with everyday fun! Customize characters, explore exciting locations and... | Read more »

Price Scanner via MacPrices.net

OtterBox Releases New Symmetry Series Metalli...
Otterbox’s new Symmetry Series of smartphone cases flaunts the best of both both street style and street smarts with their new metallic finishes and trusted OtterBox protection for iPhone 6 and... Read more
MacBook Airs on sale for up to $75 off MSRP
Save up to $75 on the purchase of a new 2015 13″ or 11″ 1.6GHz MacBook Air at the following resellers. Shipping is free with each model: 11" 128GB MSRP $899 11" 256GB... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store has Apple Certified Refurbished Mac Pros available for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more
Mac Pros on sale for up to $260 off MSRP
B&H Photo has Mac Pros on sale for up to $260 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2799, $200 off MSRP - 3.5GHz 6-core Mac Pro: $3719.99... Read more
Save up to $400 on 2014 15-inch Retina MacBoo...
B&H Photo has previous-generation 2014 15″ Retina MacBook Pros on sale for up to $400 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro... Read more
15-inch Retina MacBook Pros on sale for up to...
B&H Photo has new 2015 15″ Retina MacBook Pros on sale for up to $125 off MSRP including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $1899.99 $100 off - 15″ 2.5GHz... Read more
College Student Deals: Additional $100 off Ma...
Take an additional $100 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through July 11, 2015. Anyone with a valid .EDU email address can take advantage... Read more
Apple refurbished Time Capsules available for...
The Apple Store has certified refurbished Time Capsules available for $100 off MSRP. Apple’s one-year warranty is included with each Time Capsule, and shipping is free: - 2TB Time Capsule: $199, $100... Read more
Newsweek Launches iPhone App
The venerable weekly news magazine Newsweek, owned by IBT Media, has announced the launch of its first iPhone app. The new app is available through Apple’s App Store and will allow consumers to read... Read more

Jobs Board

*Apple* TV Live Streaming Frameworks Test En...
**Job Summary** Work and contribute towards the engineering of Apple 's state-of-the-art products involving video, audio, and graphics in Interactive Media Group (IMG) at Read more
Project Manager, WW *Apple* Fulfillment Ope...
…a senior project manager / business analyst to work within our Worldwide Apple Fulfillment Operations and the Business Process Re-engineering team. This role will work Read more
Senior Data Scientist, *Apple* Retail - Onl...
**Job Summary** Apple Retail - Online sells Apple products to customers around the world. In addition to selling Apple products with unique services such as iPad Read more
*Apple* Music Producer - Apple (United State...
**Job Summary** Apple Music seeks a Producer to help shepherd some of the most important content and editorial initiatives within the music app, with a particular focus Read more
Sr. Technical Services Consultant, *Apple*...
**Job Summary** Apple Professional Services (APS) has an opening for a senior technical position that contributes to Apple 's efforts for strategic and transactional Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.