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 常用命令分类参考中查找。

参考资料