Добавление справочных сообщений в исполняемые файлы
usemsg [-c] [-i идентификатор[=значение]] [-f файл_информации] загружаемый_файл [файл_сообщения]
- -c
- Сообщение об использовании содержится в исходной программе C и выделено следующим образом:
#ifdef __USAGE
...
#endif
Обратите внимание на два символа подчеркивания в конструкции __USAGE.
- -f имя_файла
- Считывать имя_файла для строк, содержащих пары идентификатор=значение, импортируемых в загружаемый_файл.
- -i идентификатор=значение
- Добавить информационный тег идентификатор в загружаемый_файл с указанным значением. Для идентификаторов
DATE или NAME указывать значение не требуется. Ключи DATE и NAME добавляются автоматически при добавлении любых других ключей. идентификатор преобразуется в верхний регистр.
- -l
- Добавить указанное сообщение об использовании с помощью ldrel.
- -o
- Добавить указанное сообщение об использовании с помощью objcopy. Это поведение утилиты по умолчанию.
 | Опция -o является обязательной, если утилита usemsg выполняется в двоичном файле, где сегмент данных предшествует сегменту кода. Если опция -o не указана, утилита usemsg повредит двоичные файлы с измененным порядком. |
- -s строка
- Импортировать сообщение об использовании из раздела #ifdef строка в исходном файле C. Если строка опускается, используется
__USAGE. Если указаны несколько опций -s, usemsg выполняет их последовательный поиск и использует первый обнаруженный раздел строка.
- загружаемый_файл
- Имя исполняемой программы для извлечения или вставки сообщения об использовании. Для определения местоположения файла загружаемый_файл выполняется поиск в текущей переменной среды
PATH.
- файл_сообщения
- Текстовый файл или исходный файл C, содержащий сообщение об использовании (см. -c). Если имя файла_сообщения заканчивается на
.c, предполагается, что это исходный файл C. Если этот аргумент определен, он служит в качестве имени файла сообщений, которое вставляется в загружаемый файл. Если аргумент файл_сообщения не определен, сообщение об использовании считывается из загружаемого файла и записывается в стандартный поток вывода.
GNU/Linux, Microsoft Windows
arm, armv7, aarch64, e2k, mips, ppc, x86
Утилита usemsg позволяет проверить или изменить запись об использовании в исполняемой программе ЗОСРВ «Нейтрино». Во всех утилитах ЗОСРВ «Нейтрино» содержится сообщение об использовании с описанием их опций. Эта информация сохраняется в записи ресурсов в загружаемом файле. Поскольку этот текст об использовании не загружается в память во время выполнения программы, общий объем символов может достигать 32 КБ, на размер программы во время выполнения это не влияет.
Утилита use выводит сообщения об использовании.
$ use ls
$ use more
$ use pidin
Разработчики могут использовать утилиту usemsg для добавления сообщений об использовании в программы.
Отображение справочных сообщений в портированных исполняемых файлах
При портировании или разработке исполняемого файла, в котором уже содержится справочное сообщение, вызываемое аргументом, с помощью утилиты use существующее справочное сообщение можно просмотреть путем добавления в исполняемый файл одной дополнительной строки. Пример:
%цифра> команда аргумент
Цифра определяет место чтения вывода: 1 (стандартный поток вывода stdout) или 2 (стандартный поток ошибок stderr). Утилита use всегда выводит данные в стандартный поток вывода stdout, но исполняемые файлы могут выводить их как в стандартный поток вывода stdout, так и в стандартный поток ошибок stderr.
Например, если some_gnu_tool имеет опцию -help, отправляющую справочное сообщение в stdout, добавьте следующую строку:
%1> some_gnu_tool --help
или
%1> %C --help
В этом примере при вводе:
$ use some_gnu_tool
утилита use порождает команду:
$ some_gnu_tool --help
и отображает выходные данные.
Если выходные данные исполняемого файла отправляются в stderr, добавьте следующую строку:
%2> some_gnu_tool --help
Добавление или изменение сообщения об использовании
Существует две формы добавления сообщения об использовании в загружаемый файл. Первая форма предполагает использование простого текстового файла, а другая – наличие сообщения об использовании в исходной программе C:
$ usemsg program textfile
$ usemsg program program.c
Во второй форме исходный файл C сканируется, и используется весь текст между #ifdef __USAGE и следующим кодом #endif. В обоих случаях любое существующее сообщение об использовании заменяется новым сообщением. Обратите внимание, что данная утилита позволяет как изменять существующие сообщения об использовании, так и добавлять новые сообщения в программы, где эти сообщения отсутствуют. Исходный код программы для этого не требуется.
Утилита usemsg обеспечивает простую грамматику, позволяющую поддерживать сообщения об использовании на нескольких языках. Она также поддерживает привязку различных сообщений к имени, используемому для вызова сообщения об использовании. Например, если less и more являются ссылками на один и тот же загружаемый файл, для них в той же записи об использовании в файле может присутствовать собственное сообщение об использовании.
Грамматика данной утилиты подразумевает вставку в первом столбце специального символа %%, за которым следует символ действия:
- %%
- Один символ %.
- %-команда
- Начало сообщения об использовании определенной команды.
- %=язык
- Начало записи на новом языке.
- C (символ табуляции)
- Замена на имя команды и пробел.
- (символ табуляции)
- Вставка пробелов в количестве, на
1 превышающем длину команды.
Для извлечения всего сообщения об использовании, включая все языки и грамматические управляющие последовательности, укажите загружаемый_файл и не указывайте файл_сообщения.
Опции %%-команда и %%=язык не обязательны. Если обе они указаны, за опцией %%-команда следует одна или несколько опций %%=язык, затем еще одна опция %%-команда и еще один набор опций %%=язык. Такую вложенность можно пояснить на следующих примерах:
%C сообщение_на_одном_языке
%=english
%C сообщение_на_английском_языке
%=french
%C сообщение_на_французском_языке
%-less
%C сообщение_на_одном_языке_для_less
%-more
%C сообщение_на_одном_языке_для_more
%-less
%=english
%C сообщение_на_английском_языке_для_less
%=french
%C сообщение_на_французском_языке_для_less
%-more
%=english
%C сообщение_на_английском_языке_для_more
%=french
%C сообщение_на_французском_языке_для_more
При наличии сообщений об использовании на нескольких языках для выбора языка утилитой use используется переменная среды LANG. Если переменная среды LANG не определена или не соответствует ни одному языку в файле, выводится первое сообщение об использовании. Аналогичным образом, при наличии нескольких имен команд для выбора команды используется команда, передаваемая в качестве аргумента. Если соответствие не обнаружено, выводится первое сообщение об использовании.
Вставка сообщения об использовании из исходного файла C в myprog:
$ usemsg myprog myprog.c
Извлечение всего сообщения об использовании для pidin, правка сообщения и вставка измененного сообщения:
$ usemsg pidin > my_pinitmsg
$ vi my_pinitmsg
$ usemsg pidin my_pinitmsg
- 0
- Успешное завершение.
- ≠0
- Утилита завершилась с ошибками.
Инструментальные средства ЗОСРВ «Нейтрино»
ldrel, objcopy, use
Предыдущий раздел: Справочник по утилитам