Небольшая заметка по теме мануалов. Где хранится документация в unix. Алгоритм работы утилиты man. Иерархия каталогов с документацией. Zcat и troff.
Мануал — это руководство пользователя (от англ. user guide или user manual).
На примере Debian Linux.
Где хранятся мануалы
Найти место хранения мануалов в вашей системе можно, используя название любой утилиты,
документацию на которую необходимой найти. Документация на каждую программу хранится в отдельном одноименном файле:
|
1 2 3 4 |
# find / -name "alarm*" /usr/lib/perl/5.14.2/auto/POSIX/alarm.al /usr/share/doc/gawk/examples/prog/alarm.awk /usr/share/man/man2/alarm.2.gz |
В данном случае, файл с расширением .2.gz и будет содержать текст документации, а главной директорией, в которой хранятся все основные сведения о системе будет являться /usr/share/man . В других Unix-системах, Solaris, MINIX и т.п., месторасположение каталога с документацией может немного отличаться. Теоретически, оно может отличаться даже в рамках одного бренда, но в разных версиях операционной системы. Нет ничего невозможного.
Содержимое главной директории с документацией:
|
1 2 3 |
# ls /usr/share/man/ cs de fi hu it ko man2 man4 man6 man8 pl pt_BR sl sv zh_CN da es fr id ja man1 man3 man5 man7 nl pt ru sr tr zh_TW |
Пример содержимого одного из подкаталогов:
|
1 2 |
# ls /usr/share/man/ru/ man1 man5 man8 |
Иерархия мануалов
Справочная система unix включает в себя несколько разделов. Каждому разделу присвоен собственный номер:
- Документация для исполняемых программ, утилит, описание команд оболочки (shell)
- Описание системных вызовов системы (функции, предоставляемые ядром)
- Документация по библиотечным вызовам (функции, предоставляемые программными библиотеками)
- Специальные файлы (обычно находящиеся в каталоге /dev , например, «null», «pts», «tty» и др.)
- Документация по форматам конфигурационных файлов, например о /etc/passwd
- Игры (в моем случае, эта директория вообще была пустой)
- Разное
- Документация на команды администрирования системы (запустить которые можно только с правами суперпользователя)
Пример:
|
1 2 3 |
# ls /usr/share/man/ cs de fi hu it ko man2 man4 man6 man8 pl pt_BR sl sv zh_CN da es fr id ja man1 man3 man5 man7 nl pt ru sr tr zh_TW |
Описание для каждого системного вызова, каждой утилиты размещается в отдельном файле, упакованным в gz-архив:
|
1 2 3 4 5 6 7 8 9 |
# ls /usr/share/man/man2/ accept.2.gz getpriority.2.gz outb_p.2.gz accept4.2.gz getresgid.2.gz outl.2.gz access.2.gz getresgid32.2.gz outl_p.2.gz acct.2.gz getresuid.2.gz outsb.2.gz add_key.2.gz getresuid32.2.gz outsl.2.gz adjtimex.2.gz getrlimit.2.gz outsw.2.gz afs_syscall.2.gz get_robust_list.2.gz outw.2.gz ... |
Как просмотреть документацию
Для того, чтобы просмотреть общее описание раздела, надо ввести команду:
|
1 |
# man -S 6 intro |
Аргумент -S указывает номер раздела, откуда запрашивается информация.
Чтобы просмотреть документацию по определенной программе (утилите, системному вызову, функции), надо ввести команду:
|
1 |
# man <key> |
где key — это название утилиты.
В случае, когда существует одноименные утилиты и системные вызовы, следует указывать номер раздела, откуда вы хотите получить информацию. По-умолчанию, man вернет вам ту страницу документации, которую первой найдет. Поиск будет осуществляться по всем доступным разделам, в заранее определенном порядке.
Например, вам надо получить информацию о sleep.
Вариант 1
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
# man -S 1 sleep SLEEP(1) User Commands SLEEP(1) NAME sleep - delay for a specified amount of time SYNOPSIS sleep NUMBER[SUFFIX]... sleep OPTION DESCRIPTION Pause for NUMBER seconds. SUFFIX may be `s' for seconds (the default), `m' for minutes, `h' for hours or `d' for days. Unlike most implementations that require NUMBER be an integer, here NUMBER may be an arbitrary floating point number. Given two or more arguments, pause for the amount of time specified by the sum of their values. ... |
Обычно в заголовке страницы с документацией, пишется название команды, например, SLEEP(1). (1) — обозначает номер раздела, где размещается найденная информация.
Вариант 2
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# man -S 3 sleep SLEEP(3) Linux Programmer's Manual SLEEP(3) NAME sleep - sleep for the specified number of seconds SYNOPSIS #include <unistd.h> unsigned int sleep(unsigned int seconds); ... |
Вариант 3
|
1 2 3 |
# man -S 2 sleep Нет справочной страницы для sleep Смотрите 'man 7 undocumented' в справке, если недоступны справочные страницы. |
Как система находит эти мануалы
В Debian Linux существует конфигурационный файл /etc/manpath.config, в котором прописаны пути, по которым система может искать документацию. При необходимости, можно вручную дописать в этот файл необходимые директории.
/etc/manpath.config :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
#MANDATORY_MANPATH /usr/src/pvm3/man # MANDATORY_MANPATH /usr/man MANDATORY_MANPATH /usr/share/man MANDATORY_MANPATH /usr/local/share/man #--------------------------------------------------------- # set up PATH to MANPATH mapping # ie. what man tree holds man pages for what binary directory. # # *PATH* -> *MANPATH* # MANPATH_MAP /bin /usr/share/man MANPATH_MAP /usr/bin /usr/share/man MANPATH_MAP /usr/local/bin /usr/local/man MANPATH_MAP /usr/local/bin /usr/local/share/man MANPATH_MAP /usr/X11R6/bin /usr/X11R6/man ... |
Примечание: Кроме того, в других операционных системах возможен вариант, когда необходимые пути прописаны в одной из переменных окружения.
Следует обратить внимание на утилиту manpath, которая помогает определить пути поиска справочных страниц:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
MANPATH(1) Утилиты просмотра справочных страниц MANPATH(1) НАЗВАНИЕ manpath - определяет путь поиска справочных страниц СИНТАКСИС manpath [-qgdchV] [-m система[,...]] [-C файл] ОПИСАНИЕ Если установлена переменная окружения $MANPATH, то manpath просто покажет её значение и выдаст предупреждение. Если нет, то manpath определит подходящий путь поиска иерархии справочных страниц и отобразит результаты. Список путей поиска (через двоеточие) определяется по данным файла настройки man-db (/etc/manpath.config) и пользовательского окружения. ... |
Пример вывода утилиты manpath:
|
1 2 |
# manpath /usr/local/man:/usr/local/share/man:/usr/share/man |
Как работает утилита man
Утилита man в unix-системах предназначена для комфортного просмотра документации.
Алгоритм работы утилиты — это конвеер, последовательное выполнение нескольких операций:
- поиск файла с нужной страницей документации;
- чтение и распаковка файла;
- форматирование страницы;
- вывод отформатированного текста для просмотра.
Описание каждой утилиты или системного вызова хранится в отдельном файле. В Debian Linux, каждая страница документации упакована в gzip-архив.
Первый этап работы man-утилиты — это поиск страницы с указанным именем последовательно во всех директориях с документацией.
На втором этапе необходимо распаковать файл. В принципе, для лучшего понимания, как работает утилита, можно распаковать файл документации вручную, и посмотреть его содержимое:
|
1 2 3 4 5 6 7 8 9 |
# zcat /usr/share/man/man2/alarm.2.gz ... .TH ALARM 2 2008-06-12 "Linux" "Linux Programmer's Manual" .SH NAME alarm \- set an alarm clock for delivery of a signal .SH SYNOPSIS .nf .B #include <unistd.h> ... |
zcat — это удобная утилита, которая позволяет распаковать файл в gzip формате и вывести результат в stdout. В результате, мы видим кусок файла, для разметки которого использовался специальный формат.
Третий этап — форматирование файла. Для хранения документации в unix используется старый формат — ROFF. Он позволяет сделать разметку текста для представления в виде документа. Первые версии ROFF формата появились в 60-х годах прошлого столетия. Для чтения документа в ROFF-формате, можно использовать инструменты troff, nroff и groff.
|
1 2 3 4 5 |
# zcat /usr/share/man/man2/alarm.2.gz | troff -a <beginning of page> alarm <-> set an alarm clock for delivery of a signal arranges for a signal to be delivered to the calling process in seconds. ... |
На последнем этапе, полученный текст передается на вход утилите more или less. Конкретный выбор зависит от настроек операционной системы.
Та же самая страница при просмотре через man:
|
1 2 3 4 5 6 7 8 9 |
# man -S 2 alarm ALARM(2) Linux Programmer's Manual ALARM(2) NAME alarm - set an alarm clock for delivery of a signal SYNOPSIS #include <unistd.h> ... |