swapon/swapoff help summary unclear on long options

[Daniel Richard G.]

Binary package hint: mount

This concerns mount 2.17.2-0ubuntu1 in Ubuntu Lucid.

If I do "man swapoff", one of the options I see is

       -e, --ifexists
              Silently skip devices that do not exist.

Which leaves me a bit confused when I then see this:

# swapoff --ifexists /dev/hdb5
swapoff: unrecognized option '--ifexists'

Usage:
 swapoff -a [-v] disable all swaps
 swapoff [-v] <special> disable given swap
 swapoff -h display help
 swapoff -V display version

The <special> parameter:
 {-L label | LABEL=label} LABEL of device to be used
 {-U uuid | UUID=uuid} UUID of device to be used
 <device> name of device to be used
 <file> name of file to be used

The man page appears to describe a different version/implementation of swapon/swapoff than the one I have installed.

[T L R (tlr)]

Hello Daniel,

I am running Ubuntu 10.04 and my swappoff man page is also telling me that the -e option exists.

But, like yourself, I cannot use it.

[Firas Kraïem (firas)]

-e (or --ifexists) is an option to swapon only and must be used in conjunction with -a, in wich case it tells swapon to skip devices that have a "swap" line in /etc/fstab but don't exist (without it swapon will throw an error if there is a "swap" line in /etc/fstab for a nonexistent device).

[David Tomaschik (matir)]

Most of the options documented in the man page apply only to swapon. The SYNOPSIS section shows which options apply to each command. The documentation could probably be more verbose, but this does not seem like a bug.

[Daniel Richard G. (skunk)]

Firas, I see what you mean. The lack of mention of long options in the usage summary and man-page synopsis threw me off the trail.

My use case was to pass in a laundry list of devices on the command line, and have swapoff(8) do its thing while ignoring invalid-device errors (rather than stick a "2>/dev/null || true" afterward), so the clarification of what -e/--ifexists does is appreciated as well.

I'll change this to a wishlist-type bug, requesting more clarity on the man page (flesh out description of -e/--ifexists to what you wrote) and usage summary (mention long options).

[Daniel Richard G. (skunk)]

David, I agree; can you mark as wishlist? A better man page would be a nice-to-have, but it's bad form for the --help text to omit the long options.

[David Tomaschik (matir)]

Unfortunately, only Bug Control can set importance, but I've set it back to Confirmed in hopes that it will be setup correctly as a wishlist bug for better documentation.