Работа с документацией в Unix. Утилита man

Небольшая заметка по теме мануалов. Где хранится документация в unix. Алгоритм работы утилиты man. Иерархия каталогов с документацией. Zcat и troff.

Мануал - это руководство пользователя (от англ. user guide или user manual).

На примере Debian Linux.

 

Где хранятся мануалы

Найти место хранения мануалов в вашей системе можно, используя название любой утилиты,
документацию на которую необходимой найти. Документация на каждую программу хранится в отдельном одноименном файле:

В данном случае, файл с расширением .2.gz и будет содержать текст документации, а главной директорией, в которой хранятся все основные сведения о системе будет являться /usr/share/man . В других Unix-системах, Solaris, MINIX и т.п., месторасположение каталога с документацией может немного отличаться. Теоретически, оно может отличаться даже в рамках одного бренда, но в разных версиях операционной системы. Нет ничего невозможного.

Содержимое главной директории с документацией:

Пример содержимого одного из подкаталогов:

 

Иерархия мануалов

Справочная система unix включает в себя несколько разделов. Каждому разделу присвоен собственный номер:

  1. Документация для исполняемых программ, утилит, описание команд оболочки (shell)
  2. Описание системных вызовов системы (функции, предоставляемые ядром)
  3. Документация по библиотечным вызовам (функции, предоставляемые программными библиотеками)
  4. Специальные файлы (обычно находящиеся в каталоге /dev , например, "null", "pts", "tty" и др.)
  5. Документация по форматам конфигурационных файлов, например о /etc/passwd
  6. Игры (в моем случае, эта директория вообще была пустой)
  7. Разное
  8. Документация на команды администрирования системы (запустить которые можно только с правами суперпользователя)

Пример:

Описание для каждого системного вызова, каждой утилиты размещается в отдельном файле, упакованным в gz-архив:

 

Как просмотреть документацию

Для того, чтобы просмотреть общее описание раздела, надо ввести команду:

Аргумент -S указывает номер раздела, откуда запрашивается информация.

Чтобы просмотреть документацию по определенной программе (утилите, системному вызову, функции), надо ввести команду:

где key - это название утилиты.

В случае, когда существует одноименные утилиты и системные вызовы, следует указывать номер раздела, откуда вы хотите получить информацию. По-умолчанию, man вернет вам ту страницу документации, которую первой найдет. Поиск будет осуществляться по всем доступным разделам, в заранее определенном порядке.

Например, вам надо получить информацию о sleep.

Вариант 1

Обычно в заголовке страницы с документацией, пишется название команды, например, SLEEP(1). (1) - обозначает номер раздела, где размещается найденная информация.

Вариант 2

Вариант 3

 

Как система находит эти мануалы

В Debian Linux существует конфигурационный файл /etc/manpath.config, в котором прописаны пути, по которым система может искать документацию. При необходимости, можно вручную дописать в этот файл необходимые директории.

/etc/manpath.config :

Примечание: Кроме того, в других операционных системах возможен вариант, когда необходимые пути прописаны в одной из переменных окружения.

Следует обратить внимание на утилиту manpath, которая помогает определить пути поиска справочных страниц:

Пример вывода утилиты manpath:

 

Как работает утилита man

Утилита man в unix-системах предназначена для комфортного просмотра документации.

Алгоритм работы утилиты - это конвеер, последовательное выполнение нескольких операций:

  • поиск файла с нужной страницей документации;
  • чтение и распаковка файла;
  • форматирование страницы;
  • вывод отформатированного текста для просмотра.

Описание каждой утилиты или системного вызова хранится в отдельном файле. В Debian Linux, каждая страница документации упакована в gzip-архив.

Первый этап работы man-утилиты - это поиск страницы с указанным именем последовательно во всех директориях с документацией.

На втором этапе необходимо распаковать файл. В принципе, для лучшего понимания, как работает утилита, можно распаковать файл документации вручную, и посмотреть его содержимое:

zcat - это удобная утилита, которая позволяет распаковать файл в gzip формате и вывести результат в stdout. В результате, мы видим кусок файла, для разметки которого использовался специальный формат.

Третий этап - форматирование файла. Для хранения документации в unix используется старый формат - ROFF. Он позволяет сделать разметку текста для представления в виде документа. Первые версии ROFF формата появились в 60-х годах прошлого столетия. Для чтения документа в ROFF-формате, можно использовать инструменты troff, nroff и groff.

На последнем этапе, полученный текст передается на вход утилите more или less. Конкретный выбор зависит от настроек операционной системы.

Та же самая страница при просмотре через man:

 

Полезные ссылки

intuit.ru: Утилита man

linux.yaroslavl.ru: Документация