Search UNIX Man Pages for Oracle DBA Tools with man -k

Search UNIX Man Pages for Oracle DBA Tools with man -k

Purpose

Where a web search answers most "how do I do X in UNIX" questions for a DBA today, man -k answers a narrower one — what tools this host actually has documented, and what each one does, without leaving the SSH session. Production Oracle hosts often sit in change-controlled networks with no outbound HTTP, no browser, and a tight maintenance window. man -k and its synonym apropos are the offline discovery commands that close the gap between knowing a capability exists and finding the command that delivers it.

man -k <keyword> searches the short description of every indexed man page — the one-line summary from the page's NAME section — and prints each match with its section number. It complements whereis (which locates the files for a command you already know), which (which resolves a name on the PATH), and man <name> itself (which shows one page you already know the name of).

For an Oracle DBA the practical use is simple: when a script references a tool you do not recognise, or a procedure calls for "the standard utility that does X," man -k turns a vague idea into a list of real commands documented on this host's operating system — Oracle Linux, RHEL, or Oracle Solaris.

Code

 1# Search all man page descriptions for the keyword
 2man -k <keyword>
 3
 4# Examples for an Oracle DBA
 5man -k compress              # find compression utilities
 6man -k disk                  # find disk-related tools
 7man -k schedule              # find scheduling tools
 8man -k -s 1 oracle           # restrict to section 1, user commands
 9
10# Synonym — the same search under a different command name
11apropos oracle

Code Breakdown

  • man -k <keyword> — On Linux systems with man-db, -k is documented as "equivalent to apropos": it searches the short descriptions of the indexed man pages. Output is one line per match in the form name (section) - short description. In man-db, each keyword is treated as a regular expression by default, so man -k compress also matches "compressed" and "compressor".
  • man -k compress — Lists every page whose description mentions compression. What comes back depends entirely on which packages are installed: on a host with bzip2 it includes bzip2, bunzip2, and bzcat; add the xz or zstd packages and their pages appear too. Run it before scripting a log rotation to see which compressors are really there.
  • man -k disk — A useful lesson in how the search works. It returns tools whose summary uses the word "disk", such as df ("report file system disk space usage") and fdisk ("manipulate disk partition table"). It does not return du, because du's summary reads "estimate file space usage". The search only sees the one-line summary, not the full page.
  • man -k schedule — On a Linux host this typically returns cron(8), the scheduling daemon, along with kernel scheduler pages from sections 2 and 3. at and batch only appear if the at package and its pages are installed.
  • man -k -s 1 oracle — -s limits the search to the listed sections. Section 1 is user commands; without the restriction the search also returns sections such as 5 (file formats) and 8 (administration commands). A section filter is essential when a generic word like lock would otherwise return pages from every library section.
  • apropos <keyword> — The same search under its own name. man-db documents man -k as equivalent to apropos, and Oracle Solaris documents man -k as searching the same keyword index apropos uses. Use whichever is in muscle memory.

Key Points

  • The search reads an index, not the pages. On man-db systems the index is a database cache under /var/cache/man/ built by mandb; traditional systems use a whatis text database. On Oracle Solaris 11.4 the index files live in /usr/share/man/man-index/ and are generated by an SMF service or by catman -w; the older windex file is no longer used. If the index is missing or stale, results are incomplete or empty — see Troubleshooting below.
  • Section numbers are not identical across UNIX systems. Linux and Oracle Solaris 11.4 both put user commands in section 1 and system administration commands in section 8, but section suffixes and sub-sections differ by platform (Solaris, for example, uses 3c for C library functions and 8S for SMF services). When sharing a man -k recipe across platforms, drop the -s restriction to stay portable.
  • Oracle's own tools are documented by Oracle, not the OS. sqlplus, rman, lsnrctl, and Data Pump are covered in the Oracle Database documentation, so man -k oracle mostly finds whatever operating-system pages mention Oracle — and on many hosts, nothing. Its real value is finding the surrounding OS tools a DBA script depends on.
  • The search follows the manual path. man -k only sees pages in directories on its manual path. If a tool is installed under /opt or /usr/local and its man directory is not on the path, the tool is invisible to the search. Add the directory to MANPATH in .profile, or pass it once with -M.
  • Several keywords at once. man-db's apropos accepts more than one keyword and by default shows pages that match any of them; -a (--and) shows only pages that match all of them. On Oracle Solaris, each word is considered separately and case is ignored.

Insights and Best Practices

Refresh the index after package changes

After installing a package — dnf install lsof, dnf install strace — the new command is on the PATH at once, but it may not appear in man -k results until the index is updated. Many distributions refresh the index automatically; to update it yourself on a man-db system:

1sudo mandb -q          # update the index database; -q suppresses warnings

On Oracle Solaris 11.4:

1catman -w

A staged build host that runs the same package installs as production but never refreshes the index will return misleading man -k results. Make the index refresh part of the post-install step in your Ansible, Puppet, or Chef play.

Match all keywords with -a

man -k with several keywords returns pages that match any one of them, which quickly gets noisy. To find pages that match every keyword — "every utility whose description mentions both a process and memory" — use -a:

1apropos -a process memory

On a typical Linux host this narrows the list to entries like pmap ("report memory map of a process"). On systems without -a, piping one search into grep gives the same effect: man -k process | grep -i memory.

Read the section number in the output

Three manual sections matter most for an Oracle DBA's offline lookups:

  • Section 1 — user commands (ls, find, grep, awk, sed, crontab)
  • Section 5 — file formats (passwd(5), crontab(5))
  • Section 8 — system administration commands and daemons (fdisk, mount, useradd, cron)

The same name can exist in more than one section. man 5 crontab describes the crontab file format; man 1 crontab describes the command that edits it. The section number resolves the ambiguity, and man -k crontab lists both so you can pick.

Couple with whereis and which for full discovery

man -k finds tools by purpose. whereis finds the binary, source, and man page paths for a known command. which resolves the first match on the PATH. The three together answer:

  1. man -k backup — what backup-related tools are documented on this host?
  2. whereis tar — where are the tar binary and its man page?
  3. which tar — which tar does my PATH actually invoke (where more than one tar is installed, they can take different options)?

A DBA who reaches for all three in sequence rarely needs to leave the host to answer a tooling question.

When to Run This

  • When a runbook references a tool you have not encountered on this host's distribution
  • When migrating a script from Linux to Oracle Solaris and you need the local equivalent of a missing GNU utility
  • When a vendor support note says "use the standard X utility" without naming it
  • During a change window with no outbound network access, when the man page is the only way to confirm a flag's behaviour
  • As a first pass before installing new packages — the tool may already be present under a different name

Troubleshooting Common Issues

If man -k returns "nothing appropriate" for words that should match, the index is empty or stale. On man-db systems run sudo mandb and retry. On Oracle Solaris 11.4 run catman -w to regenerate the index files.

If results are missing for a known-installed tool, check the manual path. The manpath command prints the active search list, and manpath -d prints debugging information showing how it was built. Add missing directories to MANPATH in ~/.profile if the tool was installed outside the default tree.

If apropos and man -k return different results on the same host, one of the commands is likely shadowed by a shell function or alias. Check with type apropos and type man to see what the shell actually runs.

References

Posts in this series