Команда man: использование и опции, номера разделов и поиск через man -k

Чтобы посмотреть на сервере Linux, как используется команда или файл конфигурации, страницу руководства открывают командой man, а когда название неизвестно, ищут по кратким описаниям через man -k. При поиске страницы passwd на серверах AlmaLinux 9 и Debian 12 оказалось, что в Debian 12 есть и страница команды в разделе 1, и страница формата файла в разделе 5, а в AlmaLinux 9 страницы в разделе 5 нет.

Вывод ниже получен на сервере AlmaLinux 9.8 под учётной записью root и на сервере Debian 12 под обычной учётной записью. Имя хоста и адрес подключения в симуляторе — примерные значения.

1️⃣ Основы использования команды man

Если после man указать имя команды, откроется страница руководства этой команды. man передаёт страницу программе-пейджеру, которая выводит её по одному экрану, поэтому после запуска приглашение возвращается не сразу. Пейджер задаётся переменной окружения MANPAGER или PAGER, а если обе пусты, используется less.

Если передать вывод в конвейер, выводится только текст, без пейджера. В первых 12 строках [man ls], полученных через head, в первой строке стояло LS(1), а дальше по порядку шли секции NAME, SYNOPSIS и DESCRIPTION.

man ls | head -n 12

LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about  the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci-
       fied.

Цифра 1 в скобках в LS(1) в первой строке — это номер раздела, в котором находится страница.

Внутри страницы [Space] показывает следующий экран, а [/слово] и Enter ищет слово. [n] переходит к следующему месту, где встречается то же слово, а [q] завершает man.

Если указать несуществующее имя, появляется ошибка [No manual entry for], а код завершения был равен 16.

man no-such-cmd9

No manual entry for no-such-cmd9

echo $?

16

Секция EXIT STATUS страницы man описывает 16 как значение для случая, когда не найдена хотя бы одна из страниц, файлов или слов. Ошибка использования даёт 1, поэтому в скрипте эти два случая можно обрабатывать отдельно.

2️⃣ Номера разделов man

Если страницы с одним именем есть в нескольких разделах, man ищет по разделам в заданном порядке и открывает только первую найденную страницу. Разделы имеют номера от 1 до 9, а при работе с сервером чаще всего открывают раздел 1 с командами, раздел 5 с форматами файлов и раздел 8 с командами администрирования.

У crontab есть страницы в двух разделах, потому что команда и формат файла конфигурации называются одинаково. При проверке через [man -f crontab] строки разделов 1 и 5 вывелись вместе.

man -f crontab

crontab (1)          - maintains crontab files for individual users
crontab (5)          - files used to schedule the execution of programs

Если запустить [man crontab] без номера раздела, откроется страница команды crontab из раздела 1. Чтобы посмотреть формат файла с расписанием заданий, перед именем указывают 5.

man 5 crontab | head -n 4

CRONTAB(5)                       File Formats                       CRONTAB(5)

NAME
       crontab - files used to schedule the execution of programs

Первая строка сменилась на CRONTAB(5) и File Formats, а в строке NAME вместо описания команды появилось описание файла с расписанием заданий.

Если в указанном разделе нет страницы с таким именем, появляется ошибка. На сервере AlmaLinux 9.8 запуск [man 5 passwd] ради формата файла /etc/passwd выдал ошибку о том, что в разделе 5 страницы нет.

man 5 passwd

No manual entry for passwd in section 5

На сервере Debian 12 [man -f passwd] вывела и строку passwd из раздела 5. В каких разделах есть страница, зависит от установленных на сервере руководств, поэтому перед тем как указывать номер раздела, стоит сначала проверить через [man -f].

man -f passwd

passwd (1)           - change user password
passwd (1ssl)        - OpenSSL application commands
passwd (5)           - the password file

В разделе 8 находятся команды администрирования, которые запускает в основном учётная запись root, например useradd для создания учётных записей.

man -f useradd

useradd (8)          - create a new user or update default new user information

3️⃣ Опции команды man и поиск через -k и -f

[man -f] выводит однострочное описание страниц с тем же именем и работает так же, как whatis. На сервере AlmaLinux 9.8 [man -f passwd] и [whatis passwd] вывели одни и те же две строки.

man -f passwd

passwd (1)           - update user's authentication tokens
passwd (1ossl)       - OpenSSL application commands

Строка 1ossl — это страница команды OpenSSL, которая тоже называется passwd.

Когда название неизвестно, [man -k] ищет по именам страниц и кратким описаниям. Она работает так же, как apropos, а слово читается как регулярное выражение.

man -k '^passwd'

passwd (1)           - update user's authentication tokens
passwd (1ossl)       - OpenSSL application commands

^ означает начало строки, поэтому вывелись только строки, начинающиеся с passwd. Искать можно и по слову из описания: [man -k 'directory contents'] нашла вместе с ls страницы dir и vdir.

man -k 'directory contents'

dir (1)              - list directory contents
ls (1)               - list directory contents
vdir (1)             - list directory contents

[man -k] ищет только по кратким описаниям из секции NAME, поэтому по названию опции или слову из текста страницу не найти. [man -K], которая ищет и в тексте, читает все страницы по очереди и работает долго.

Если искомого слова нет, выводится [nothing appropriate], а код завершения был равен 16.

man -k no-such-word9

no-such-word9: nothing appropriate.

echo $?

16

[man -w] выводит только расположение исходного файла, не открывая страницу.

man -w ls

/usr/share/man/man1/ls.1.gz

man -w 5 crontab

/usr/share/man/man5/crontab.5.gz

Оба файла находились в папках man1 и man5 внутри /usr/share/man, а цифра в имени папки совпадала с номером раздела. Файл страницы 1ossl, найденный через [man -w 1ossl passwd], тоже лежал в папке man1, той же, что и у раздела 1.

Опции собраны на двух вкладках ниже.

🔲 Симулятор команды man

В симуляторе ниже можно открыть страницу через [man ls] и листать экраны чипами [Space], [/list], [n] и [q]. На том же виртуальном сервере можно добавить номер раздела, как в [man 5 crontab], или ввести [man -f], [man -k] и [man -w].

4️⃣ Структура страницы man

Страница man делится на секции с заголовками из заглавных букв. Когда заголовки вытащили через grep и сравнили, оказалось, что на странице ls описания опций находятся внутри DESCRIPTION, а на странице crontab есть отдельная секция OPTIONS.

man ls | grep -E '^[A-Z]+( [A-Z]+)*$'

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO

man crontab | grep -E '^[A-Z]+( [A-Z]+)*$'

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CAVEATS
SEE ALSO
FILES
STANDARDS
DIAGNOSTICS
AUTHOR

Названия секций немного различаются от страницы к странице, а самые частые приведены ниже.

Знаки в SYNOPSIS следуют правилам, которые задаёт страница man. То, что стоит в квадратных скобках, можно опустить. Опции, разделённые вертикальной чертой (|), нельзя использовать вместе, а аргумент с тремя точками (...) можно указывать несколько раз.

SYNOPSIS у ls выглядит как ls [OPTION]... [FILE]..., поэтому и опции команды, и аргументы командной строки вроде имён файлов можно все опустить или указать несколько раз.

[--help] — это краткая справка, которую выводит сама программа, поэтому она сразу попадает в терминал, без пейджера. Usage в первой строке [ls --help] имела тот же вид, что и SYNOPSIS, а весь вывод занял 121 строку — меньше, чем 245 строк [man ls].

ls --help | head -n 3

Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.

На странице man есть и секции, которых нет в [--help], например AUTHOR и SEE ALSO. Чтобы быстро посмотреть одну опцию, подойдёт [--help], а когда нужно описание, разбитое на секции, например формат файла конфигурации или коды завершения, открывают man.

🔢 FAQ & рекомендуемые материалы

🔗 Рекомендуемые материалы

Пейджер · less Как использовать команду less в Linux Статья, в которой подробно разобраны клавиши для перелистывания страниц и поиска слов на экране less, где открываются страницы man. Читать →

Планирование задач Linux: настройка crontab Как с помощью команды crontab запланировать запуск серверных заданий в заданное время. Поиск расположения Команды which, whereis и locate в Linux: 3 способа узнать расположение (путь) файла Команды, которые находят, по какому пути лежат исполняемый файл и файл руководства команды. Передача вывода Перенаправление в Linux (Redirection) Поток стандартного ввода и стандартного вывода, по которому вывод команды передаётся в файл или другой команде.

ℹ️ О партнёрских ссылках
Материалы этого сайта содержат партнёрские ссылки. Если посетитель покупает товар или услугу по такой ссылке, сайт получает комиссию от продавца. При этом сумма, которую платит покупатель ^{(при акционных скидках сумма снижается ↓)}, не увеличивается. Указанные цены, скидки и наличие актуальны на момент написания и могут отличаться, поэтому перед покупкой уточняйте их у продавца. Товары выбираются и оцениваются по нашим собственным критериям, а комиссия не влияет ни на порядок, ни на содержание обзоров.