Zenn
📖

Debianパッケージのマニュアルの読み方調べ方

2021/12/08に公開
Linux
Debian
tech

この記事はUMITRON Advent Calendar 2021 8日目の記事です。

まえがき

弊社では海上で動かすIoTと言うなかなか他にないプロダクトを作っており、やろうと思ったことがググって出てこないことがよくあります。また、そもそもインターネット上の情報は古かったり、間違っていたり、一部しか書かれていなかったり、正確でなかったりします。
そこで頼れるものは公式ドキュメントです。この記事ではDebianパッケージのマニュアルに絞ってどのように知りたい情報を見つけるのかをまとめます。

man コマンドで読む

Debianパッケージのマニュアルを読むには基本的に man コマンドを用います。

基本的な使い方

man <name>

man の引数に知りたいコマンドなどの名前を渡して実行すると、そのコマンドに関するドキュメントが読めます。これで読めるマニュアルにはコマンドに限らず、system callや設定ファイルなどもあります。では、そもそもどんなマニュアルがあるかをどうやったら知ることが出来るでしょうか？

name, descriptionを検索

man -k <name>

man -k に引数を渡すとマニュアルの名前・descriptionを検索して一覧を表示してくれます。

$ man -k regex
re_comp (3)          - BSD regex functions
re_exec (3)          - BSD regex functions
regcomp (3)          - POSIX regex functions
regerror (3)         - POSIX regex functions
regex (3)            - POSIX regex functions
regex (7)            - POSIX.2 regular expressions
regex_t (3)          - overview of system data types
regexec (3)          - POSIX regex functions
regfree (3)          - POSIX regex functions

sectionを指定してマニュアルを読む

man <section> <name>

上記の検索の例では検索結果の中にregexが2つあります。また man regex した場合 regex(3) の方のマニュアルが開き、 regex(7) が読めません。
この (3), (7) はsectionと呼ばれる概念でマニュアルをカテゴリ分けするものです（ (3) がライブラリの中の関数、 (7) がその他）。そして man コマンドではこのsectionを指定することができ、 regex(7) を読む場合は第一引数にsection, 第2引数に名前を渡す、つまり man 7 regex とすれば読むことが出来ます。

全文検索

man -Kw <word>

man -Kw に検索ワードを渡すとマニュアルの全文検索が出来ます。

$ man -Kw MANPATH
/usr/share/man/man1/apropos.1.gz
/usr/share/man/man1/man.1.gz
/usr/share/man/man1/manpath.1.gz
/usr/share/man/man1/whatis.1.gz
/usr/share/man/man1/whereis.1.gz
/usr/share/man/man8/catman.8.gz
/usr/share/man/man8/mandb.8.gz
/usr/share/man/man2/rename.2.gz
/usr/share/man/man2/rename.2.gz
/usr/share/man/man2/rename.2.gz
/usr/share/man/man5/manpath.5.gz
/usr/share/man/man7/environ.7.gz

ただ注意点がいくつかあります。

  • ある程度時間がかかります。
  • man で読めるドキュメントは基本的にroffというマークアップ言語で記述されており、 man -Kw ではこのレンダリング前のroffのテキストをgrepするような挙動をします。
  • これにより、複数単語の検索には向きません。Googleのように2単語含むページ、のような検索の仕方は出来ず、 man -Kw 'hoge fuga' のような検索をした場合、 hoge fuga というひとまとまりのテキストを含むページが検索されます。
  • レンダリング前のテキストが検索されるため、 man コマンドでマニュアルを見た時は hoge fuga という記述があったとしても、 roff の記述上で改行が間に入っている場合はヒットしませんし、例えば hoge がマークアップされていてboldになってたりすると前後にマークアップテキストが入っているのでヒットしません。
  • ハイフン - がroffの中では \- と記述されている場合があるため、例えば "systemd-analyze" で検索したい場合、 "systemd-analyze" と "systemd\-analyze" の2通り検索しないとすべての結果は得られません。
$ man -Kw systemd-analyze
/usr/share/man/man1/systemd-analyze.1.gz
/usr/share/man/man5/systemd.exec.5.gz
/usr/share/man/man5/systemd.unit.5.gz
/usr/share/man/man7/systemd-boot.7.gz
/usr/share/man/man7/systemd-boot.7.gz
/usr/share/man/man7/systemd.directives.7.gz
/usr/share/man/man7/systemd.index.7.gz
/usr/share/man/man7/systemd.time.7.gz
$ man -Kw 'systemd\-analyze'
/usr/share/man/man1/systemd-analyze.1.gz
/usr/share/man/man1/systemd.1.gz
/usr/share/man/man5/systemd.exec.5.gz
/usr/share/man/man5/systemd.service.5.gz
/usr/share/man/man5/systemd.unit.5.gz
/usr/share/man/man7/systemd.directives.7.gz

システムにインストールされていないマニュアルを探してインストールする

例えばgrepのマニュアルを読むと以下のような記述があります。

Perl-compatible regular expressions give additional functionality, and are documented in pcresyntax(3) and pcrepattern(3), but work only if PCRE is available in the system.

ここの pcresyntax(3), pcrepattern(3) のような name(number) な表記はマニュアルを指しています。ので、pcresyntaxを参照しようとすると、

$ man pcresyntax
No manual entry for pcresyntax

そんなマニュアルはないと言われてしまいます。これはpcresyntaxというマニュアルがDebian package repositoryには存在するがシステムにインストールされていない状態です。
このマニュアルを読みたい場合、いくつか手段があると思いますが apt-file コマンドでマニュアルを探す方法を紹介します。
apt-file コマンドは特定のファイルを含むパッケージを探すコマンドです。まず、 apt-file 自体がインストールされていない場合インストールします。

sudo apt-get install apt-file

初回はその後 apt-get update して apt-file のインデックスを構築する必要があります。

sudo apt-get update

次に pcresyntax(3) のマニュアルファイルを含むパッケージを検索します。 pcresyntax(3) の実体のファイル名は pcresyntax.3 、あるいはこれに拡張子がついた名前になるので、以下のように検索します。

$ apt-file find /pcresyntax.3
libpcre3-dev: /usr/share/man/man3/pcresyntax.3.gz

これで pcresyntax(3) が libpcre3-dev パッケージに入っていることが分かりました。このパッケージをインストールすることで pcresyntax(3) を読むことが出来ます。

ウェブで読む

全文検索に関しては落とし穴がありますし、マニュアルがシステムにインストールされていないあ場合もあるので、やっぱりググった方がいいのでは？と思ったりもします。実際ググればウェブでホストされたmanpageもヒットします。しかし、バージョンが違ったり、同名の別実装のマニュアルだったりすることがあり注意が必要です。
そこでDebian公式がマニュアルをホストしている以下のサイトが利用できます。

このサイトではDebianのメジャーバージョンごとにマニュアルがホストされており、適切なDebianバージョンを選べばパッケージのバージョン違いの問題は最小限に抑えられます。
例えばbullseyeのマニュアルを "systemd-analyze" で全文検索したい場合、 "site:https://manpages.debian.org/bullseye/* systemd-analyze" でGoogle検索することで実現できます。

また全文検索ではなく名前指定でマニュアルを開きたい場合は、 https://manpages.debian.org/<debian_version_name>/<package_name> を開くことで読むことが出来ます。bullseyeのsystemd-analyzeを読みたい場合は、 https://manpages.debian.org/bullseye/systemd-analyze です。 このあたりのルールはトップページに詳細があります。

infoコマンドで読む

man とは別に info というコマンドがあります。多くの場合は man で事足りるのですが、例えば find などは info の方により詳細が載っています。その場合でもたいてい man に "より詳細はinfoを読んでね" 的なことが書いてあるので、最初から info を参照する必要はないでしょう。ただ、 info コマンドでより詳細が読める場合がある、と言うことを知っておくとそういう記述を読んだ時に混乱しなくてすみます。
また man はデフォルトでページャが less ですが、 info はEmacsライクなページャで操作感が違うので注意が必要です。

おわりに

冒頭で書いたとおり、インターネット上の情報は古かったり、間違っていたり、一部しか書かれていなかったり、正確でなかったりします。そしてこの記事も例外ではありません。間違いのないよう注意を払ってはいますが、完全であることは保証できませんし、 サボって端折った 詳細に書きすぎると逆に分かりづらくのであえて書かなかった部分もあります。そもそも10年後には正確ではなくなってるでしょう。
ぜひここに書いた知識を用いてこの記事が正しいかどうか自分の手で確認してみてください。

Discussion