getopt()

Разобрать опции, переданные из командной строки

Прототип:

#include <unistd.h>
                                       
int getopt( int argc,
            char * const argv[],
            const char *optstring );
                                       
extern char *optarg;
extern int optind, opterr, optopt;

Аргументы:

argc

Число аргументов, переданных в функцию main().

argv

Массив аргументов, переданных в функцию main().

optstring

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

Библиотека:

libc

Описание:

Функция getopt() представляет собой анализатор командной строки, который может быть использован приложениями, которые следуют "Рекомендациям по синтаксису утилит", описанным ниже.

Глобальная переменная optind хранит индекс следующего элемента массива argv[], который будет обработан. Система инициализирует optind значением 1 при загрузке программы, и getopt() обновляет ее по завершению работы с каждым элементом argv[]. Сбросьте optind в 1 если вам требуется использовать getopt() для обработки дополнительных наборов аргументов.

Функция getopt() возвращает следующий символ опции из argv, который совпадает с символом в optstring, если такой существует. Если у опции есть аргумент, getopt() записывает в optarg указатель на аргумент опции:

1. Если символ опции является последним в строке, на которую указывает элемент argv, то optarg будет содержать следующий элемент argv, а значение optind увеличится на 2.

2. В противном случае optarg будет указывать на строку, за которой будет следовать символ опции в argv, и optind увеличится на 1.

Функция getopt() возвращает -1 и не изменяет optind, если:

• argv[optind] не равен NULL
• *argv[optind] не является символом '-'
• argv[optind] указывает на строку "-".

Функция возвращает -1 после инкремента optind, если:

• argv[optind] указывает на строку "--".

Если функция getopt() встречает символ опции, который отсутствует в optstring, она возвращает символ "?". Если функция getopt() не обнаруживает аргумент у опции, то она возвращает:

• двоеточие (":"), если первым символом в optstring является двоеточие
• в противном случае, вопросительный знак ("?")

и записывает в optopt символ опции, который вызвал ошибку.

Функция getopt() выводит диагностические сообщения в stderr до тех пор, пока opterr равен 0, или первым символом optstring является ':'.

Рекомендации по синтаксису утилит

Функция getopt() может быть использована приложениями, которые следуют следующим рекомендациям:

• При описании синтаксиса утилиты, опции следуют друг за другом в алфавитном порядке. Не существует связи между параметрами на основе порядка их следования, если иное не указано в разделе «Параметры», или если:
  • опции задокументированы как взаимоисключающие, и такая опция задокументирована для отмены любых несовместимых опций, предшествующих ей.
  • когда для опции повторяются аргументы опции, комбинации опции и аргументов опции интерпретируются в порядке, указанном в командной строке.

  Если опция, не имеющая аргументов, повторяется, результаты зависят от приложения.

• Имена опций, которые требуют замены фактическими значениями, могут отображаться со встроенными символами подчеркивания, или как <parameter name>. Угловые скобки используются для символической группировки фразы, представляющую одну опцию, и переносимые приложения не должны включать их в данные, передаваемые в утилиту.

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

  utility_name [-a] [-b] [-c option_argument] [-d|-e] [-foption_argument] [operand...]

  Или:

  utility_name [-ab] [-c option_argument] [-d|-e] [-foption_argument] [operand...]

  Утилиты со сложными аргументами могут быть представлены таким образом:

  utility_name [options] [operand]

• Если не указано иное, всякий раз, когда операнд или аргумент опции является числовым значением или содержит таковое:
  • число интерпретируется как десятичное целое число
  • числа в диапазоне от 0 до 2 147 483 647 синтаксически распознаются как числовые значения
  • когда в описании утилиты указано, что она принимает отрицательные числа в качестве операндов или аргументов опций, числа в диапазоне от -2 147 483 647 до 2 147 483 647 синтаксически распознаются как числовые значения.
  • допустимы диапазоны, превышающие перечисленные здесь.

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

• Аргументы или аргументы опции, заключенные в “[” и “]” не являются обязательными и могут быть опущены. Портативные приложения не должны включать символы “[” и “]” в данных, предоставляемых утилите.

• Многоточия (...) используются для обозначения того, что разрешено одно или несколько вхождений параметра или операнда. Когда опция или операнд, за которым следует многоточие, заключены в квадратные скобки, может быть указано ноль или более опций или операндов. Например:

  utility_name -f option_argument ... [operand...] utility_name [-g option_argument] ... [operand...]

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

• Если аннотация слишком длинная, чтобы ее можно было напечатать в одной строке в документации, то строки с отступом, следующие за начальной строкой, являются строками продолжения. Фактическое использование команды отображается в одной логической строке.

Возвращаемое значение:

Одно из следующих:

• следующий символ опции, заданный в командной строке
• двоеточие, если обнаружен отсутствующий аргумент, и первым символом optstring является двоеточие
• вопросительный знак, если обнаружен отсутствующий аргумент, и первый символ в optstring - не двоеточие
• вопросительный знак, если встречается символ опции, которого нет в optstring
• -1 по завершению обхода всех опций командной строки

Примеры:

#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
                                       
int main( int argc, char* argv[] )
{
    int c, errflag = 0;
                                       
    while ( (c = getopt( argc, argv, "abt:" )) != -1 )
    {
        switch( c )
        {
            case 'a': printf( "apples\n" );
                      break;
            case 'b': printf( "bananas\n" );
                      break;
            case 't': printf( "tree = %s\n", optarg );
                      break;
            case '?': ++errflag;
                      break;
        }
    }
        
    return (EXIT_SUCCESS);
}

Классификация:

POSIX 1003.1

Безопасность использования

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Нет

В потоке

Нет

Тематические ссылки:

getsubopt(), main(), stderr

Рекомендации 3, 4, 5, 6, 7, 9 и 10 в томе «Базовые определения» IEEE Std.1003.1-2001, Раздел 12.2, Рекомендации по синтаксису утилит.

Предыдущий раздел: Описание API системной библиотеки