Проект OpenNet: MAN uri (7) Макропакеты и соглашения (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

uri (7)

>> uri (7) ( Русские man: Макропакеты и соглашения )

uri (7) ( Linux man: Макропакеты и соглашения )

НАЗВАНИЕ

uri, url, urn - единый идентификатор ресурса (URI), содержащий URL или URN

СИНТАКСИС


URI = [ absoluteURI | relativeURI ] [ "#" fragment ]
absoluteURI = scheme ":" ( hierarchical_part | opaque_part )
relativeURI = ( net_path | absolute_path | relative_path ) [ "?" query ]

scheme = "http" | "ftp" | "gopher" | "mailto" | "news" | "telnet" | "file" | "man" | "info" | "whatis" | "ldap" | "wais" | ...
hierarchical_part = ( net_path | absolute_path ) [ "?" query ]

net_path = "//" authority [ absolute_path ]
absolute_path = "/"  path_segments
relative_path = relative_segment [ absolute_path ]

ОПИСАНИЕ

Единый идентификатор ресурса (Uniform Resource Identifier (URI)) - это строка символов, идентифицирующая абстрактный или физический ресурс (например, веб-страницу). Единый указатель местоположения ресурса (Uniform Resource Locator (URL))- это URI, который идентифицирует ресурс по способу доступа к нему (например, его "местонахождению в сети") вместо того, чтобы идентифицировать его по названию или другим атрибутам этого ресурса. Единое название ресурса (Uniform Resource Name (URN)) - это URI, который должен быть уникальным и неизменным даже в том случае, когда ресурс уже не существует или недоступен.

URI являются стандартными способами для создания конечных адресов гипертекстовых ссылок на такие инструменты, как веб-броузеры. Строка "http://www.kernelnotes.org" является URL (значит, и URI тоже). Многие используют термин URL неправильно, как синоним URI (технически, URL являются частью URI).

URI может быть абсолютным или относительным. Абсолютный идентификатор ссылается на ресурс, не зависимый от контекста, в то время как относительный идентификатор ссылается на ресурс, описывая его с помощью контекста. В строке ссылки относительного идентификатора прописываются все части пути. Знаки "." и ".." имеют специальные значения: "текущий иерархический уровень" и "уровень выше текущего иерархического уровня" соответственно, что аналогично делается в системах, похожих на Unix. Участок пути, содержащий двоеточие, не может быть использован как первая часть пути относительного URI (например, "это:то"), потому что это приведет к ошибке; перед такими частями надо ставить ./ (например, "./это:то"). Заметим, что производные MS-DOS (например, Microsoft Windows) заменяют двоеточия в именах устройств на вертикальную "разорванную" черту ("|") в URI, таким образом, "C:" становится "C|".

Если используется идентификатор фрагмента, то он ссылается на фрагмент ресурса с конкретным названием; после символа '#' указывает на фрагмент. URI, начинающийся с '#', и ссылается на этот фрагмент в текущем ресурсе.

ИСПОЛЬЗОВАНИЕ

Существует множество различных схем URI, каждая из которых обладает своими вспомогательными правилами и значениями, но все они созданы максимально похожими друг на друга. Например, многие схемы URL позволяют задать авторизацию следующего формата, названного здесь ip_server (квадратные скобки показывают, что он является необязательным):

ip_server = [user [ : password ] @ ] host [ : port]

Этот формат позволяет указать имя пользователя, его пароль и/или номер порта. host- это имя главного компьютера; оно может быть указано в соответствии с DNS, также может быть указан его IP-адрес. Таким образом, URI <http://fred:fredpassword@xyz.com:8080/> присоединяется к порту 8080 сервера xyz.com как пользователь fred (с помощью пароля fredpassword). Желательно не указывать пароль URI в целях безопасности. Если URL присвоено имя пользователя, но не его пароль, а серверу этот пароль требуется, то программа, обрабатывающая URL, запросит его у пользователя сама.

Далее приводятся наиболее распространенные схемы, используемые клонами Unix. Заметьте, что многие программы, использующие URI, имеют внутренние схемы или специализированные схемы; поэтому советуем Вам прочитать документацию об этих схемах.

http - Веб-сервер (HTTP)

http://ip_server/path

http://ip_server/path?query

Это URL для доступа к веб-серверу (HTTP). По умолчанию он осуществляется через порт 80. Если путь указывает на каталог, то веб-сервер выберет, что необходимо загрузить; обычно, если есть файл "index.html" или "index.htm", то загружается его содержимое, в ином случае загружается список файлов в каталоге. Например, <http://lwn.net>.

Запрос может быть послан в старом формате "isindex", состоящем из слова или фразы и не содержащем знак равенства (=). Запрос в виде одной или нескольких записей также может быть послан в формате "GET". Запись может иметь следующую форму: key=value, разделенную символом (&). Не забудьте, что key может повторяться, поэтому сервер и программы приложения должны определить, действительно ли это необходимо. Существуют совпадения формата HTML/XML/SGML и формата запроса GET; когда такие URI с несколькими ключами встречаются в документах SGML/XML (включая HTML), символ "&" должен быть записан в форме &. Не все запросы используют этот формат; длинные формы не могут быть сохранены как URI, поэтому данные запросы используют различные механизмы взаимодействия (называемые POST), которые не включают в URI данные. Для получения разъяснений этого вопроса прочтите документацию

Gateway Interface; она находится по адресу: <http://www.w3.org/CGI>.

ftp - протокол передачи файлов (FTP)

ftp://ip_server/path

Это URL, получающий доступ к файлу с помощью протокола FTP. Устанавливаемый номер порта по умолчанию равен 21. Если не используется имя пользователя, то пишется слово "anonymous", и в этом случае многие клиенты используют посылаемые им сообщения как пароль. Например, <ftp://ftp.is.co.za/rfc/rfc1808.txt>.

gopher - сервер Gopher

gopher://ip_server/gophertype selector
gopher://ip_server/gophertype selector%09search
gopher://ip_server/gophertype selector%09search%09gopher+_string

По умолчанию работает порт 70. gophertype - это поле для одного символа. Оно используется для указания типа ресурса Gopher, на который ссылается URL. Путь может и не указываться; в этом случае знак "/" тоже является необязательным, а устанавливаемое значение gophertype равно "1".

selector - это строка селектора в Gopher. В протоколе Gopher строки селектора могут содержать любые байты, кроме шестнадцатеричных 09 (US-ASCII HT или tab), 0A (US-ASCII-символ LF) и 0D (US-ASCII-символ CR).

mailto - электронный адрес

mailto:электронный@адрес.ru

Это электронный адрес, обычно имеющий форму name@hostname. Для получения более подробной информации о форматах электронных адресов прочтите mailaddr(7). Замечание: любой символ % должен быть записан как %25. Пример: <mailto:dwheeler@dwheeler.com>.

news - группы новостей и новости

news:название.группы.новостей
news:message-id

A название.группы.новостей - это иерархическое имя, разделенное точками, например, "comp.infosystems.www.misc". Если <название.группы.новостей> - "*" (как в <новости:*>), то это используется для обращения ко "всем возможным группам новостей". Пример: <news:comp.lang.ada>.

A message-id соответствует идентификатору сообщений IETF RFC 1036; при заключении в "<" и ">"; приобретает форму уникальное@полное_имя_домена. Идентификатор сообщения может быть определен из названия группы новостей с находящимся в названии символом "@".

telnet - Удаленный вход

telnet://ip_server/

Схема URL для Telnet используется для определения интерактивных текстовых сервисов, которые могут быть использованы протоколом Telnet. Последний символ "/" может быть опущен. По умолчанию запущен порт 23. Пример: <telnet://melvyl.ucop.edu/>.

file - Обычный файл

file://ip_server/path_segments
file:path_segments

Представляет собой файл или каталог, доступный в этой машине. В некоторых случаях host может представлять собой строку "localhost" или быть пустой строкой; буквально это означает: `машина, с которой отправляется URL'. Если путь указывает на каталог, то программа просмотра представит содержимое каталога с ссылками на каждый пункт содержания, что выполняется не всеми программами. KDE поддерживает генерируемые файлы с помощью URL <file:/cgi-bin>. Если данный файл не найден, то обозреватель может попробовать расширить имя файла при помощи функции glob (см.: glob(7) и glob(3)).

Второй формат (например, <file:/etc/passwd>) существует для ссылки на локальные файлы. Более старые стандарты не допускали этот формат и некоторые программы не воспринимают его как URI. В этих случаях можно использовать следующий синтаксис: пустая строка вместо имени сервера, например, <file:///etc/passwd>; эта форма выполняет те же самые действия и легко распознается более старыми программами как URI. Заметьте, если Вы хотите задать команду "начать с этого места", то не используйте схему вообще, рекомендуется использовать относительный адрес, например, <../test.txt>, который имеет побочный эффект: он не зависит от схемы. Примером такой схемы может послужить: <file:///etc/passwd>.

man - Страницы руководства Man

man:имя_команды
man:имя_команды(номерглавы)

Это ссылка на страницы локального руководства (man). За командой может следовать номер главы в круглых скобках; для получения более подробной информации о главах прочтите man(7). Схема URI для систем клонов Unix является уникальной и до сих пор не зарегистрирована в IETF. Пример: <man:ls(1)>.

info - Страница документации Info

info:имя_виртуального_файла
info:имя_виртуального_файла#имя_узла
info:(имя_виртуального_файла)
info:(имя_виртуального_файла)имя_узла

Эта схема ссылается на интерактивную информационную систему (созданную с помощью файлов texinfo), эта форма документации используется такими программами, как GNU tools. Схема URI для систем клонов Unix является уникальной и до сих пор не зарегистрирована в IETF. Синтаксисы URI у GNOME и KDE разные, поэтому они не воспринимают синтаксис друг друга. Первые два формата для GNOME: в именах узлов все пробелы заменены подчеркиванием. Следующие два формата подходят для KDE: пробелы в названиях узлов остаются пробелами, даже если это запрещено стандартами URI. Это делалось в надежде на то, что в будущем все программы будут принимать все эти форматы и будут считать подчеркивания как пробелы. В GNOME и KDE, если используется форма без названия узла, то названием по умолчанию считается "Top". Пример формата GNOME: <info:gcc> и <info:gcc#G++_and_GCC>. Пример формата КDE: <info:(gcc)> и <info:(gcc)G++ and GCC>.

whatis - Поиск документации

whatis:строка

Эта схема просматривает базу описаний однострочных команд и возвращает список описаний, содержащих эту строку. Возвращаются только полные совпадения. За более полной информацией обращайтесь к whatis(1). Схема URI для систем клонов Unix является уникальной и до сих пор не зарегистрирована в IETF.

ghelp - документация о GNOME

ghelp:название-приложения

Схема помогает загрузить документацию GNOME, где описывается данное приложение. Замечание: пока в документации не описаны все приложения в этом формате.

ldap - Простой протокол доступа к каталогам (Lightweight Directory Access Protocol)

ldap://машинапорт
ldap://машинапорт/
ldap://машинапорт/имякаталога
ldap://машинапорт/имякаталога?атрибуты
ldap://машинапорт/имякаталога?атрибуты?областьпоиска
ldap://машинапорт/имякаталога?атрибуты?областьпоиска?фильтр
ldap://машинапорт/имякаталога?атрибуты?областьпоиска?фильтр?расширения

Эта схема поддерживает: запросы, направляемые LDAP; протокол, опрашивающий один или несколько серверов для получения иерархически упорядоченной информации (например, ресурсы компьютеров). Более подробную информацию о LDAP URL можно получить по адресу: RFC 2255. Компонентами этого URL являются:

машинапорт: запрашиваемого сервера LDAP, указанного как имя машины, и, по возможности, номер порта после двоеточия. Для LDAP по умолчанию включается TCP-порт 389. Если параметр не указан, то клиент сам определяет, какой из LDAP-серверов запрашивать.
имякаталога: - уникальное имя LDAP, которое идентифицирует объект поиска (прочтите главу #3 RFC 2253 ). Компонент
атрибуты: возвращает список атрибутов, разделенных запятой; прочтите RFC 2251, главу 4.1.5. Если данный параметр не задан, то возвращаются все атрибуты.
областьпоиска: указывает на область поиска, которая может быть "базовой" (для базового поиска), "уровневой" (для поиска на одном уровне), или поиск может вестись по ветвям. Если область поиска не указывается, то по умолчанию используется "базовая".
фильтр: указывает на фильтр поиска (набор возвращаемых записей). Если параметр не задан, то возвращаются все записи. Прочтите главу #4 RFC 2254
расширения: список пар тип=значение, где часть =значение (в случаях, когда это не требуется) может не употребляться. Расширение с приставкой '!' обязательно; если этот значок отсутствует, то необязательно.

Приведем примеры запросов LDAP. Запрос к ldap.itd.umich.edu насчет информации о Мичиганском университете США (University of Michigan in the U.S.):

: ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US

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

: ldap://ldap.itd.umich.edu/o=University%20of%20Michigan,c=US?postalAddress

Для того, чтобы запросить у host.com (порт 6666) информацию о человеке по имени "Babs Jensen" в University of Michigan, введите строку:

: ldap://host.com:6666/o=University%20of%20Michigan,c=US??sub?(cn=Babs%20Jensen)

wais - глобальная сеть информационных серверов (Wide Area Information Servers)

wais://машинапорт/базаданных
wais://машинапорт/базаданных?поиск
wais://машинапорт/базаданных/тип/путь

Эта схема описывает базу данных WAIS, поиск или документ (для получения более подробной информации о WAIS прочтите IETF RFC 1625 ). Машинапорт - это название машины, в некоторых случаях сопровождающееся номером порта (после двоеточия). Используемый по умолчанию порт - 210.

Первая форма определяет базу данных WAIS для поиска. Вторая форма - это поиск в определенной базе данных WAIS базаданных. Третья форма - для поиска конкретного документа в базе данных WAIS. тип - это обозначение типа объекта в WAIS, а путь - это идентификатор документа в WAIS.

другие схемы

Существует множество других схем URI. Большинство программ, использующих URI, поддерживают свои собственные схемы URI (например, Mozilla имеет схему about: для получения внутренней информации; броузер помощи в GNOME имеет схему toc: для работы с разными разделами. Среди них есть схемы, которые в данный момент не распространены (например, prospero). Схема news предпочтительнее схемы nntp. URN поддерживаются схемой urn (например, urn:ietf:... означает документы IETF); в настоящее время URN широко не используются. Не все приложения поддерживают все схемы.

КОДИРОВКА

URI использует ограниченый набор символов.

Следующие символы имеют свое назначение в URI (они зарезервированы):

: ; / ? : @ & = + $ ,

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

: - _ . ! ~ * ' ( )

Не следует употреблять в работе другие символы. Управляющие восьмеричные значения кодируются тремя символами, один из которых - символ процента "%", два других - это шестнадцатеричные числа, представляющие собой код восьмеричного числа (Вы можете использовать буквы верхнего и нижнего регистров для ввода шестнадцатеричных чисел). Например, пробел обозначается как "%20", символ табуляции (tab) обозначается как "%09", а "&" как "%26". Символ "%" имеет зарезервированное значение, и сам символ будет всегда обозначаться только как "%25". Обычно в запросах пробел заменяют знаком плюс (+); этот способ не определен в RFC (где рекомендуется использовать %20), но любое приложение, принимающее запросы URI, должно его воспринимать.

Незарезервированные символы могут быть использованы без изменения синтаксиса URI, но это нельзя делать в случаях, когда URI используется в контексте, не допускающем появления незарезервированных символов. Например, "%7e" иногда используется как "~" в пути http URL, хотя оба они воспринимаются одинаково в http URL.

Для URI, обрабатывающих символы, не входящих в набор US-ASCII. в главе В.2 документации по HTML 4.01 и в главе 2.2.5 IETF RFC 2718 приводится рекомендуемое рациональное решение:

1.: Переводить последовательность символов в кодировку UTF-8 (IETF RFC 2279) - см. utf-8(7) и затем
2.: использовать повторно кодированные URI, то есть, использовать конвертацию %HH для ненадежных восьмеричных чисел.

СОЗДАНИЕ URI

При их написании URI должны быть заключены в кавычки (например, "http://www.kernelnotes.org"), скобки (например, <http://lwn.net>) или занимать целую строку. Примечание для тех, кто использует кавычки: никогда не вводите "посторонние" пунктуационные знаки (например, точку, заканчивающую предложение, или запятую при перечислении) внутри URI, так как это изменит значение URI. Вместо этого рекомендуется использовать скобки или применять систему цитирования, которая никогда не заключает "посторонние" пунктуационные знаки в кавычки. Эта система, названная 'новой' (или 'логической') системой цитирования, разработанная на основе "Hart's Rules" и "Oxford Dictionary for Writers and Editors", используется во всем мире. Прочтите главу Jargon File о Hacker Writing Style Ранние документы предлагали ставить приставку "URL:" перед URI, но это никогда не применялось на практике.

Так как URI стали использоваться повсеместно, традиционные средства массовой информации (телевидение, радио, газеты и т.д.) стали применять сокращенные ссылки URI, состоящие из названия домена и пути к конкретному ресурсу (например, <www.w3.org/Addressing>). Такие ссылки больше предназначены для человеческого восприятия, а не для считывания машиной. Так как сокращенные URI имеют тот же синтаксис, что и путь относительных URL, сокращенные URI не могут быть использованы в тех случаях, где используются относительные URI. Не используйте сокращенные URI как гипертекстовые ссылки в документах, используйте стандартный формат, как описано в данном документе.

ЗАМЕЧАНИЯ

Любое приложение, использующее URI (например, веб-обозреватель) в Linux, должно поддерживать (непосредственно или косвенно) все схемы, описанные здесь, включая схемы man и info. Поддержка другой программы с помощью этого вызова тоже допускается.

Для получения информации о том, как включить URI (вместе с URL) в формат данных, прочтите соответствующую документацию. HTML использует формат <A HREF="uri"> text </A>. Файлы texinfo используют формат @uref{uri}. Man и mdoc имеют недавно добавленный макрос UR или просто включают URI в текст (программы просмотра должны распознавать :// как часть URI).

Для man pages GNOME использует <toc:man>, KDE использует <man:(index)>, а для info pages GNOME использует <toc:info>, в то время как KDE использует <info:(dir)>. В общем, KDE использует <file:/cgi-bin/> как приставку к набору созданных файлов. KDE предпочитает просматривать документы HTML с помощью <file:/cgi-bin/helpindex>. GNOME предпочитает использовать схему ghelp для хранения и нахождения информации. Ни один обозреватель в момент написания этого документа не поддерживал схему ссылок на каталоги file. Как говорилось ранее, эти среды различаются по способу поддержки схемы info. В перспективе GNOME и KDE должны прийти к единому формату URI, и будущая версия системы этих документов опишет получившийся результат.

БЕЗОПАСНОСТЬ

Сам по себе URI не создает никакой угрозы безопасности. Но нет никакой гарантии, что URL, который однажды указал на конкретный ресурс, в дальнейшем будет делать то же самое. Так же нет никаких гарантий, что этот же URL позднее не будет ссылаться на совершенно другой ресурс. Такие гарантии можно получить лишь от лица, ответственного за эти ресурсы.

Существует возможность составить URL таким образом, что попытка произвести обыкновенную, "безобидную" операцию, такую, как получить информацию с определенного ресурса, возможно, вызовет сбой в ее выполнении. "Небезопасный" URL обычно прописывается следующим образом: в запросе указывается номер порта, не совпадающий с номером зарезервированного порта для протокола сети. Клиент заходит в сайт, который использует другой протокол. URL имеет команды, которые при их считывании (в соответствии с другим протоколом) производят непредвиденную операцию. Примером может послужить использование gopher URL для создания ненужного и безадресного сообщения, которое предполагалось послать через сервер SMTP.

Предупреждение должно стоять при использовании любого URL, который указывает номер порта, отличного от стандартного порта для протокола, в особенности, если этот номер находится в зарезервированной области.

Надо быть очень внимательным и в тех случаях, когда URI содержит разделители данного протокола (например, символы CR и LF для протокола telnet). Любая неосторожность может нарушить привычную схему протокола и привести к выполнению непредвиденных и не совсем "безобидных" операций.

Также довольно непредусмотрительно использовать пароль в URI.

СООТВЕТСТВИЕ СТАНДАРТАМ

IETF RFC 2396, HTML 4.0.

НАЙДЕННЫЕ ОШИБКИ

Документация может быть расположена в различных местах, поэтому не существует схемы URI для просмотра документации в различных форматах. Ссылки типа <file:///usr/doc/ZZZ> не работают по причине различных требований дистрибутивов и установочных требований, согласно которым документация может быть размещена где угодно (она может быть в /usr/doc, /usr/local/doc, /usr/share или где-нибудь еще). К тому же, содержимое каталога ZZZ обычно изменяется с каждой версией. А людям, которые получают документацию по интернет (вместо того, чтобы хранить ее в своей системе), схема file вообще ничем не будет полезной.

Многие программы и форматы файлов не считывают URI, поэтому с помощью URI невозможно создавать ссылки.

Так как не все программы поддерживают различные форматы URI, то должен существовать стандартный механизм загрузки URI, который определит пользовательскую среду (например, текстовую, графическую или рабочую), установки и запущенные приложения и запускает нужное приложение для любого URI.