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,-kis documented as "equivalent to apropos": it searches the short descriptions of the indexed man pages. Output is one line per match in the formname (section) - short description. In man-db, each keyword is treated as a regular expression by default, soman -k compressalso 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 includesbzip2,bunzip2, andbzcat; 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 asdf("report file system disk space usage") andfdisk("manipulate disk partition table"). It does not returndu, 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 returnscron(8), the scheduling daemon, along with kernel scheduler pages from sections 2 and 3.atandbatchonly appear if theatpackage and its pages are installed.man -k -s 1 oracle—-slimits 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 likelockwould otherwise return pages from every library section.apropos <keyword>— The same search under its own name. man-db documentsman -kas equivalent toapropos, and Oracle Solaris documentsman -kas searching the same keyword indexaproposuses. 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 bymandb; traditional systems use awhatistext database. On Oracle Solaris 11.4 the index files live in/usr/share/man/man-index/and are generated by an SMF service or bycatman -w; the olderwindexfile 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
3cfor C library functions and8Sfor SMF services). When sharing aman -krecipe across platforms, drop the-srestriction 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, soman -k oraclemostly 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 -konly sees pages in directories on its manual path. If a tool is installed under/optor/usr/localand itsmandirectory is not on the path, the tool is invisible to the search. Add the directory toMANPATHin.profile, or pass it once with-M. - Several keywords at once. man-db's
aproposaccepts 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:
man -k backup— what backup-related tools are documented on this host?whereis tar— where are the tar binary and its man page?which tar— whichtardoes 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
- Oracle Solaris 11.4 Reference Manual — man(1) - Oracle's reference for
man, including-k, the-ssection option, the manual section layout, and the index files generated by SMF orcatman -w - Oracle Solaris 11.4 Reference Manual — apropos(1) - Oracle's reference for
aproposkeyword lookup on Solaris, including how words and case are matched - man-db apropos(1) — Debian manual pages - The Linux man-db reference for
aproposandman -k: regular-expression matching,-ato match all keywords,-sto limit sections, and the index database files - man-db mandb(8) — Debian manual pages - How the man-db index cache under
/var/cache/man/is created and updated - shutdownabort.com — Miscellaneous Useful UNIX (Wayback, 2013-01-15) - Original source of the
man -krecipe in the DBA Quick Guides corpus
Posts in this series
- List Files Opened by an Oracle Process with lsof -p
- Delete the 500 Oldest Files in a Directory (Oracle DBA)
- Write Text Files from Oracle PLSQL with UTL_FILE Example
- Diagnose Oracle Net and RAC Interconnect Routing with netstat -r
- Unpacking Oracle Patch and Install Media with cpio
- Oracle Export Through a Named Pipe with mknod for Space-Constrained Hosts
- Recursive find and grep to Search Oracle Trace Files for Any String
- Find the Biggest Files First When an Oracle Filesystem Fills Up
- Scan Every Oracle Alert and Trace Log for ORA- Errors with grep
- vi Editor Commands Reference for Oracle DBAs
- Disable vi Autoindent Before Pasting SQL Scripts on Oracle Hosts
- Enable vi Command-Line Editing in ksh for Oracle DBA Shells
- Search UNIX Man Pages for Oracle DBA Tools with man -k
- Insert Control Characters in vi with Ctrl-V for Oracle Prompts