Why are there different versions of a man page in the Ubuntu Manpage Repository?

Question

Why are there two or more different versions of a manpage in http://manpages.ubuntu.com

For example, looking at the manpage of at, you can find two, one that is provided by the manpages-posix package ^[ref]. And another that is provided by the at package itself ^[ref].
The same is valid for other packages as well like ls.1 and ls.1posix and ls.1plan9.

What I understood from a quick search is that posix means that it's a standard specified by IEEE to maintain compatibility between different OS ^[ref].

So does Ubuntu has its own implementation of a program?

Answer 1

POSIX stipulates a number of commands are available (see the Shell & Utilities volume) and that they work in a certain way. Here are those commands:

admin alias ar asa at awk basename batch bc bg break c99 cal cat cd cflow chgrp chmod chown cksum cmp colon comm command compress continue cp crontab csplit ctags cut cxref date dd delta df diff dirname dot du echo ed env eval ex exec exit expand export expr false fc fg file find fold fort77 fuser gencat get getconf getopts grep hash head iconv id ipcrm ipcs jobs join kill lex link ln locale localedef logger logname lp ls m4 mailx make man mesg mkdir mkfifo more mv newgrp nice nl nm nohup od paste patch pathchk pax pr printf prs ps pwd qalter qdel qhold qmove qmsg qrerun qrls qselect qsig qstat qsub read readonly renice return rm rmdel rmdir sact sccs sed set sh shift sleep sort split strings strip stty tabs tail talk tee test time times touch tput tr trap true tsort tty type ulimit umask unalias uname uncompress unexpand unget uniq unlink unset uucp uudecode uuencode uustat uux val vi wait wc what who write xargs yacc zcat

GNU coreutils (what GNU/Linux distributions ship) contains all these commands but they have developed away from the standard POSIX base over time. Some offer better features. Some work in slightly different ways. These coretils versions are what the standard man pages cater for.

But it is still desirable to write scripts that work on many platforms. For example, if you tried to use extended coreutil functionality of grep on OSX, you'd run into syntax errors. And this is why knowing how the POSIX version works is desirable. Install manpages-posix and you know everything.

It's also essential to know this stuff if you're planning on improving GNU coreutils.

Plan9 is different yet again. It was never designed to be POSIX compatible. It strives for an amount of POSIX compatibility through a emulation layer and the man pages for it are again, there as documentation to let you know what you can use.

Answer 2

More Uses of POSIX Manpages

Besides what Oli said about writing portable scripts (and hacking on coreutils), there are two other situations where the POSIX manual pages may come in handy:

1. You've configured (more) POSIX-compliant behavior.

If you set the POSIXLY_CORRECT environment variable (to anything, it can even be blank), many GNU utilities and some other programs will behave in the fashion specified by POSIX, even when the developers saw no reason users would likely want this behavior.

This doesn't make your system behave like a truely POSIX-compliant OS. The Linux kernel, GNU libc, and many userlands tools are all deliberately designed to be POSIX-compliant only when doing so is more helpful than harmful. This is one of the reasons GNU/Linux systems like Ubuntu are widely considered not to be Unix systems.

The behavior of ls is affected by a great many things, but is not affected by whether or not POSIXLY_CORRECT is set. (You can verify this by checking the source code in, say, 13.04: ls-ls.c, ls.h, and ls.c make no reference to that environment variable.)

But some other utilities are affected. For example, the df utility prints disk usage information for all mounted devices. Normally, Ubuntu's df (privided by GNU coreutils) shows this in 1 kilobyte blocks. With POSIXLY_CORRECT set, it shows it in 512 B (i.e., half-kilobyte) blocks. That behavior is required by the POSIX standard, but probably not useful to most users, so it is not the default.

ek@Kip:~$ df
Filesystem      1K-blocks       Used Available Use% Mounted on
/dev/sda8        15481840   11816640   2878768  81% /
udev              1020748         12   1020736   1% /dev
tmpfs              412840       5156    407684   2% /run
none                 5120          0      5120   0% /run/lock
none              1032100        240   1031860   1% /run/shm
none               102400         32    102368   1% /run/user
/dev/sda6          245679     159043     73529  69% /boot
/dev/sda9        31458256   10024972  19835284  34% /home
/dev/sdd1      1922859824 1687175656 138008496  93% /media/ek/Noether
/dev/sdc1      1922859824 1700447368 124736784  94% /media/ek/Baker
/dev/sdb1      1922859824 1782944724  42239428  98% /media/ek/Spinoza

ek@Kip:~$ POSIXLY_CORRECT= df
Filesystem     512B-blocks       Used Available Use% Mounted on
/dev/sda8         30963680   23573440   5817376  81% /
udev               2041496         24   2041472   1% /dev
tmpfs               825680      10312    815368   2% /run
none                 10240          0     10240   0% /run/lock
none               2064200        480   2063720   1% /run/shm
none                204800         64    204736   1% /run/user
/dev/sda6           491358     318086    147058  69% /boot
/dev/sda9         62916512   20049944  39670568  34% /home
/dev/sdd1       3845719648 3374351312 276016992  93% /media/ek/Noether
/dev/sdc1       3845719648 3400894736 249473568  94% /media/ek/Baker
/dev/sdb1       3845719648 3565889448  84478856  98% /media/ek/Spinoza

2. There's no "regular" manpage for the command/topic you're interested in.

Sometimes the POSIX manual page is the only one available. For example, the cd command is a shell builtin only. It's provided by different shells and behaves a little bit differently from shell to shell (in that different shells sometimes make cd accept different command-line options).

The default interactive shell in Ubuntu is bash and you can get information about cd in man bash. But if you want a manual page just for cd, well, there's no cd executable (no single globally usable, shell-independent cd command).

But the cd command is a required part of the POSIX standard--shells must implement it, and the POSIX standard "knows" about what it requires. So a POSIX manpage for cd is possible, and exists.

Searching for cd on manpages.ubuntu.com shows the POSIX manual page and two others. This is another kind of example of multiple manual pages with the same name, by the way. What are the others? One is the cd command in the language Tcl. The other is a CD-ROM driver in the FreeBSD operating system. Manual pages for FreeBSD are sometimes helpful to Ubuntu users, so a whole collection of them can be installed, including man 4 cd (not one of the FreeBSD manual pages most likely to be helpful to Ubuntu users not also using FreeBSD).

Why Plan 9?

You might be wondering why there are Plan 9 manual pages in Ubuntu at all. After all, unlike Ubuntu (and many other OSes such as FreeBSD), Plan 9 is not even a Unix-style operating system, though as Oli says there are some similarities.

The reason for this is that the Plan 9 userland tools (the basic set of tools corresponding very roughly to coreutils) have been ported to Unix-like systems, so they can be run on OSes such as Ubuntu. They, and their manual pages, are provided by the 9base package.

Some (not all) of the Plan 9 tools available for Ubuntu have the same name as Ubuntu tools, and perform the same or similar functions.

One of the reasons for having the Plan 9 tools on Ubuntu is that some of them don't correspond directly to any Ubuntu tool (but may still need the tools that do, for interoperability).

Another reason is to support software that depends on Plan 9 tools. For example, the window manager wmii used to be packaged for Ubuntu (and available in official Ubuntu software sources); this wmii2 package depended on 9base.