If you look closely at the listings for the Oracle Solaris 11.4 Reference Manuals and the previous Oracle Solaris 11.3 Reference Manuals, you might notice a change in some sections. One of our “modernization” projects for this release actually took us back to our roots, in returning to the man page section numbers used in SunOS releases before the adoption of the System V scheme in Solaris 2.0. When I proposed this change, I dug into the history a bit to explain in the PSARC case to review the switchover.
Unix man pages have been divided into numbered sections for its entire recorded history. The original sections, as seen in the Introduction to the Unix 1st Edition Manual from 1971 & the Unix 2nd Edition Manual from 1972, were:
I. Commands II. System calls III. Subroutines IV. Special files V. File formats VI. User-maintained programs VII. Miscellaneous
By Version 7, Bell Labs had switched from Roman numerals to Arabic and updated the definitions a bit:
1. Commands 2. System calls 3. Subroutines 4. Special files 5. File formats and conventions 6. Games 7. Macro packages and language conventions 8. Maintenance
Most Unix derivatives followed this section breakdown, and a very similar set is still used today on BSD, Linux, and MacOS X:
1 General commands 2 System calls 3 Library functions, covering in particular the C standard library 4 Special files (usually devices, those found in /dev) and drivers 5 File formats and conventions 6 Games and screensavers 7 Miscellanea 8 System administration commands and daemons
The Linux Filesystem Hierarchy Standard defines these sections as
- man1: User programs
- Manual pages that describe publicly accessible commands are contained in this chapter. Most program documentation that a user will need to use is located here.
- man2: System calls
- This section describes all of the system calls (requests for the kernel to perform operations).
- man3: Library functions and subroutines
- Section 3 describes program library routines that are not direct calls to kernel services. This and chapter 2 are only really of interest to programmers.
- man4: Special files
- Section 4 describes the special files, related driver functions, and networking support available in the system. Typically, this includes the device files found in /dev and the kernel interface to networking protocol support.
- man5: File formats
- The formats for many data files are documented in the section 5. This includes various include files, program output files, and system files.
- man6: Games
- This chapter documents games, demos, and generally trivial programs. Different people have various notions about how essential this is.
- man7: Miscellaneous
- Manual pages that are difficult to classify are designated as being section 7. The troff and other text processing macro packages are found here.
- man8: System administration
- Programs used by system administrators for system operation and maintenance are documented here. Some of these programs are also occasionally useful for normal users.
- The Linux man pages also include a non-FHS specified section 9 for “kernel routine documentation.”
But of course, one Unix system broke ranks and shuffled the numbering around. USL redefined the man page sections in System V to instead be:
1 General commands 1M System administration commands and daemons 2 System calls 3 C library functions 4 File formats and conventions 5 Miscellanea 7 Special files (usually devices, those found in /dev) and drivers
Most notably moving section 8 to 1M and swapping 4, 5, & 7 around.
Solaris still tried to follow the System V arrangement until now, with some extensions:
1 User Commands 1M System Administration Commands 2 System Calls 3 Library Interfaces and Headers 4 File Formats 5 Standards, Environments, and Macros 6 Games and screensavers 7 Device and Network Interfaces 9 DDI and DKI Interfaces
With Solaris 11.4, we’ve now given up the ghost of System V and declared Solaris to be back in sync with Bell Labs, BSD, and Linux numbering. Specifically, all existing Solaris man pages using these System V sections were renumbered to the listed standard section:
SysV Standard
---- --------
1m -> 8
4 -> 5
5 -> 7
7 -> 4
Sections 1, 2, 3, 6, and 9 remain as is, including the Solaris method of subdividing section 3 into per library subdirectories. The subdivisions of section 7 introduced in PSARC/1994/335 have become subdivisions of section 4 instead, for instance ioctls will now be documented in section 4I instead of 7I.
The man command was updated so that if someone specifies one of the remapped sections, it will look first in the section specified, then in any subsections of that section, then the mapped section, and then in any subsections of that section. This will assist users following references from older Solaris documentation to find the expected pages, as well as users of other platforms who don’t know our subsections.
For example:
- If a user did “man -s 4 core“, looking for the man page that was delivered as /usr/share/man/man4/core.4, and no such page was found in /usr/share/man/man4/ it would look for /usr/share/man/man5/core.5 instead.
- If a user did “man -s 3 malloc“, it would display /usr/share/man/man3/malloc.3c.
- The man page previously delivered as ip(7P), and now as ip(4P) could be found by any of:
- man ip
- man ip.4p
- man ip.4
- man ip.7p
- man ip.7
Additionally, as long as we were mucking with the sections, we defined two new sections which we plan to start using soon:
2D DTrace Providers
8S SMF Services
The resulting Solaris manual sections are thus now:
1 User Commands
2 System Calls
2D DTrace Providers
3 Library Interfaces and Headers
3* Interfaces split out by library (i.e. 3C for libc, 3M for libm,
3PAM for libpam)
4 Device and Network Interfaces
4D Device Drivers & /dev files
4FS FileSystems
4I ioctls for a class of drivers or subsystems
4M Streams Modules
4P Network Protocols
5 File Formats
6 Games and screensavers
7 Standards, Environments, Macros, Character Sets, and miscellany
8 System Administration Commands
8S SMF Services
9 DDI and DKI Interfaces
9E Driver Entry Points
9F Kernel Functions
9P Driver Properties
9S Kernel & Driver Data Structures
We hope this makes it easier for users and system administrators who have to use multiple OS’es by getting rid of one set of needless differences. It certainly helps us in delivering FOSS packages by not having to change all the manpages in the upstream sources to be different for Solaris just because USL wanted to be different 30 years ago.