Perspectives | Thursday, February 1, 2018

Normalizing man page section numbers in Solaris 11.4

By: Alan Coopersmith | Senior Principal Software Engineer

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

Unix Programmer's Manual Seventh Edition cover pageBy 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
    and the equivalent man -s formulations.

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.

Join the discussion

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha
 

Visit the Oracle Blog

 

Contact Us

Oracle

Integrated Cloud Applications & Platform Services