Linux whatis 命令:查询手册的一行描述与节号
whatis 按手册页名称查询简短描述,适合已经知道名称、想快速确认用途时使用。它还能显示同名页面所属的不同手册节,帮助您在打开完整文档之前选对对象。
man-db 的 whatis 默认查找精确页面名称,man -f 可用于相同类型的查询。若只知道任务或描述中的关键词,应使用 apropos 关键词搜索;查询可执行文件或当前 Shell 的名称解析,则应使用 type 或 command。本文的选项和退出状态均以 man-db 为准。
whatis 命令查询什么?
手册页的 NAME 部分通常包含页面名称与简短用途。whatis 使用 man-db 的索引数据库查找匹配名称,再显示描述,不会打开整篇手册或搜索所有正文。
这里的“一行说明”指简短摘要,不保证每个名称只有一条结果,也不保证终端显示时永不换行。同名页面、多个别名和不同节号可能产生多条记录;文档包及索引的安装状态也会影响结果。
基本语法与输出字段
下面是语法示意,方括号中的内容可选,省略号表示可指定多个名称,实际运行时替换相应部分。
whatis [option] name...
例如查看 ls 的用途:
whatis ls
常见输出结构如下。该行用于说明格式,具体文字、语言和节号以本机文档为准,不应当作每台系统固定的输出。
ls (1) - list directory contents
ls 是页面名称,(1) 是手册节号,连字符后是简短描述。需要阅读完整用法时,把节号和名称传给 man:
man 1 ls
节号是文档分类,不是程序版本。查询到手册之后,仍应确认它解释的是自己要使用的程序或接口。
一次查询多个名称
可以把多个名称作为独立参数传入,一次比较相关工具的用途。
whatis ls cp mv rm
即使某个名称没有匹配,其余名称也可能产生结果。不要把一批查询中出现了若干行输出,当作每个输入都已找到;自动化需要逐项确认时,应对每个名称分别查询并检查状态。也不要把一整行带空格的多个名称放进同一对引号,否则它会变成一个参数。
同名页面出现在不同手册节
同一名称可能同时表示用户命令、库函数或文件格式。例如 passwd 常见于用户命令和账户文件格式两种文档:
whatis passwd
如果结果中同时出现 passwd(1) 与 passwd(5),可分别打开对应页面:
man 1 passwd
man 5 passwd
前者通常介绍修改密码的命令,后者介绍账户文件格式。能看到哪些节取决于文档安装情况;只出现其中一项并不一定是查询故障。命令一般在第 1 或第 8 节,配置与文件格式常在第 5 节。
正则表达式与通配模式
用 -r 匹配名称的一部分
-r 或 --regex 把输入当作正则表达式,名称的部分匹配即可返回结果。它改变的是名称匹配方式,不会把搜索范围扩展为描述正文。
whatis -r '^ssh'
whatis --regex 'printf$'
^ssh 匹配以 ssh 开头的页面名称,printf$ 匹配以 printf 结尾的名称。用引号阻止特殊字符先被 Shell 解释;引号不会取消 whatis 自己的正则表达式规则。此模式可能比直接按名称查询慢。
用 -w 匹配整个页面名称
-w 或 --wildcard 按 Shell 风格通配模式查询,模式必须覆盖整个页面名称。
whatis -w 'ssh*'
whatis --wildcard '*printf*'
ssh* 匹配 ssh 开头的名称,*printf* 匹配名称中包含 printf 的条目。星号在这里表示通配,不是正则表达式中的重复运算符;外层引号用于避免它先展开为当前目录的文件名。
按手册节号缩小查询范围
-s 或 --sections 可限定节号,排除同名但不同种类的页面。
whatis -s 1 passwd
whatis -s 5 passwd
whatis --sections=2,3 printf
| 节号 | 主要内容 |
|---|---|
1 |
普通用户命令与程序。 |
2 |
系统调用。 |
3 |
程序库函数。 |
5 |
配置文件与文件格式。 |
8 |
系统管理命令。 |
多个节号可用逗号或冒号分隔。man-db 中,简单节号 3 还包含 3perl 等扩展节;明确写 3perl 时只查询该部分。例子中的 2,3 是查询范围,不代表 printf 在每个节中都一定存在。
常用 whatis 选项
| 选项 | 作用 |
|---|---|
-r、--regex |
按正则表达式匹配名称,允许名称的部分匹配。 |
-w、--wildcard |
按 Shell 风格通配模式匹配整个名称。 |
-s 列表、--sections=列表 |
限定手册节,支持逗号或冒号分隔。 |
-l、--long |
取消按终端宽度截断描述。 |
-M 路径、--manpath=路径 |
指定另一组手册层级路径,替代 MANPATH,多个目录用冒号分隔。 |
-L 区域设置、--locale=区域设置 |
临时指定搜索所用区域设置,不会安装翻译文档。 |
默认输出宽度可能受 MANWIDTH、COLUMNS 和终端检测影响。-l 避免截断,但终端仍可能自动换行。-L 到搜索页面阶段才生效,早期帮助消息仍可能采用原来的区域设置。
whatis 与 man -f 的关系
在 man-db 环境中,man -f 用 whatis 的方式查询简短描述。下面两行可用于同一类任务:
whatis printf
man -f printf
选择容易记住的一种即可。man -f 不是打开完整手册;要进一步阅读,使用 man 加上具体节号和页面名称。
whatis、apropos 与命令类型检查的区别
| 查询方式 | 回答的问题 |
|---|---|
whatis ls |
名称为 ls 的手册页描述什么? |
apropos copy |
名称或描述中哪些手册与 copy 关键词匹配? |
type ls |
当前 Shell 如何解析 ls 这个名称? |
command -v ls |
当前 Shell 能否找到该名称,以及它以什么形式解析? |
whatis 有结果,不代表同名可执行文件位于当前 PATH 中;程序存在,也可能没有安装对应手册。type 或 command 的结果还可能是别名、函数或内建命令,不能把它们所有输出都当作磁盘上的绝对路径。
没有查询结果时如何排查?
确认名称与文档是否存在
whatis 默认查询精确页面名称,输入功能主题词时应改用 apropos。可以把文档搜索、命令解析和名称查询分开检查:
apropos archive
command -v tar
whatis tar
上例分别搜索 archive 主题、检查 tar 的解析结果、查询 tar 手册描述。只有 command 返回结果而 whatis 没有结果时,可能缺少相应文档、索引或搜索路径;仅凭这一组输出还不能确定是哪一种原因。
在确有需要时更新索引
新手册已安装但索引尚未更新时,可以由具备管理权限的用户更新系统索引:
sudo mandb
mandb 创建或更新索引缓存,不会安装缺失的手册或目标程序。系统可能已在包安装或定时任务中自动更新;先检查安装记录及命令诊断,不必对每一次无结果都重复执行。没有系统管理权限时,先核对个人手册目录和发行版配置。
核对区域设置与 MANPATH
以下分别显示区域设置、man-db 采用的搜索路径和 MANPATH 变量:
locale
manpath
printf '%s\n' "$MANPATH"
非空 MANPATH 的手动设置可能改变搜索范围。变量为空或未定义时,man-db 会根据 PATH 等设置确定默认路径,不能把空变量理解成没有手册目录。-M 应指定手册层级目录,而非可执行程序目录。
区域设置影响选择哪些已安装的描述。想看到中文摘要,必须有相应中文手册和索引,并在当前环境中被选中;单独修改语言设置不能补出缺失的翻译。
在脚本中使用查询结果
自动化时,应区分“没有匹配”和“工具执行失败”,而不是仅解析可能翻译或变化的输出文字。man-db 的 whatis 使用 0 表示成功、1 表示用法或配置等错误、2 表示运行错误、16 表示没有匹配条目;其他实现应查本机手册。
把下面完整示例保存为 check-whatis.sh,在装有 man-db 的系统上用 bash check-whatis.sh ls 执行。每次传入一个非空手册名,程序只查询文档,不执行所查命令。
if [ "$#" -ne 1 ] || [ -z "$1" ]; then
printf '%s\n' '用法:bash check-whatis.sh 手册名' >&2
exit 64
fi
if whatis -- "$1" >/dev/null; then
printf '%s\n' '找到了手册描述。'
else
status=$?
case "$status" in
16) printf '%s\n' '没有匹配的手册描述。' >&2 ;;
*) printf '查询失败:status=%d\n' "$status" >&2 ;;
esac
exit "$status"
fi
找到条目时打印“找到了手册描述。”并成功退出;无匹配时打印对应消息并以 16 退出;其他错误打印原始状态,并保留该状态退出。status=$? 在 else 开头立即保存,避免被打印操作覆盖。
脚本的参数错误使用 64,这是本例自行选择的状态,不是 whatis 的约定。-- 阻止连字符开头的名称被当作选项。只重定向普通结果,保留 whatis 自己的诊断;工具不存在时 Shell 通常返回 127,也会进入错误分支。
若要检查实际命令能否调用,应另外检查 command -v 或 type,并理解其解析结果。手册索引和可执行程序可用性是两件不同的事。
常见问题
whatis 会显示命令的实际路径吗?
不会。它显示手册名称、节号与简短描述。当前 Shell 的命令解析和类型应使用 type 或 command -v 检查。
想用描述里的词搜索,应该怎么做?
使用 apropos 关键词 或 man -k 关键词。whatis 默认按页面名称查询;即使加 -r 或 -w,主要匹配对象仍然是名称。
为什么同一个名称显示多行?
可能有不同节中的同名页面。括号内是节号而非版本,使用 man 节号 名称 选择要看的页面;文档是否齐全仍取决于本机安装。
先确认名称,再阅读完整用法
已知名称时,whatis 便于快速比较用途和辨认手册节;需要细节时,用结果中的名称与节号打开 man 完整手册。只知道任务时改用 apropos,判断当前 Shell 的调用对象时用 type 或 command。其他任务对应的工具可在Linux 常用命令分类参考中查找。




