Man page aliases

Question

Some man pages document multiple commands/functions in a single page while the man command usually presents the right man page for each one.

Example: the man page for malloc/free/calloc/realloc on many systems

What are the mechanisms man uses for such lookups?

So far I've encountered:

• symlinks under /usr/share/man/manX
• alias man pages that just contain a .so manX/foo source directive

Of course, thinkable are also hardlinks and copies of man pages.

Are there any other mechanisms supported by man commands?

For example a central index file where such aliases are defined?

Answer 1

On OpenBSD, each man directory (e.g. /usr/share/man for manual relating to the base system) contains a mandoc.db database created by a weekly cron job running makewhatis.

These databases are created by parsing the various manual sources (roff source files) for particular strings and they are used by the man utility. One of the things that is indexed is the strings referred to by the .Nm ("name") macro in the .Sh NAME section of the manuals typeset using OpenBSD's mdoc macros.

For example, a part of the very start of the source of the malloc(3) manual in /usr/share/man/man3/malloc.3 looks like this:

.Dd $Mdocdate: May 19 2019 $
.Dt MALLOC 3
.Os
.Sh NAME
.Nm malloc ,
.Nm calloc ,
.Nm realloc ,
.Nm free ,
.Nm reallocarray ,
.Nm recallocarray ,
.Nm freezero ,
.Nm aligned_alloc ,
.Nm malloc_conceal ,
.Nm calloc_conceal
.Nd memory allocation and deallocation
.Sh SYNOPSIS

The makewhatis tool will index each .Nm value and the man command will show the rendered version of the malloc.3 source when a user asks for the manual of any of the listed functions (e.g. man free).

Manuals not relating to the OpenBSD base system (i.e. 3rd party manuals under /usr/local/man) are also parsed by makewhatis, but since these often use roff markup that is not mdoc (usually written for Linux which uses another macro package), it indexes the values used by other macros (the .TH title macro).

Some 3rd party programs seems to distribute a separate manual or for each separate tool or function, even though this means duplicating manuals and just giving them different names. Using symbolic and/or hard links is also a common solution.

Others are a bit smarter. This is the complete manual source of zzip_fread(3) (part of the zziplib package):

.so man3/zzip_read.3

I.e., it contains a macro that makes the parser read another file.