ОБЗОР

#include <unistd.h>

---

int getopt(int argc, char * const argv[],
const char *optstring);

---

extern char *optarg;
extern int optind, opterr, optopt;

---

#include <getopt.h>

---

int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);

---

int getopt_long_only(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

getopt(): _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
getopt_long(), getopt_long_only(): _GNU_SOURCE

ОПИСАНИЕ

Функция getopt() разбирает аргументы командной строки. Её аргументы argc и argv являются счётчиком и массивом аргументов, которые передаются функции main() при запуске программы. Элемент argv, начинающийся с «-» (и не являющийся «-» или «--»), считается параметром. Символы этого элемента (не считая начального «-») являются символами параметра. При каждом повторном вызове getopt() возвращают следующий символ параметра и так для каждого следующего параметра.

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

Если getopt() встречает символ другого параметра, она возвращает этот символ, обновляя внешнюю переменную optind и статическую переменную nextchar, так что следующий вызов getopt() может продолжить проверку с символа следующего параметра или элемента argv.

Если символов параметров больше нет, то getopt() возвращает -1. При этом optind станет индексом первого элемента argv, не являющегося параметром.

Аргумент optstring является строкой, содержащей допустимые символы параметров. Если за таким символом стоит двоеточие, то параметр требует указания аргумента. При этом getopt() помещает указатель на следующий за символом параметра текст в тот же элемент argv, или на текст следующего элемента argv в optarg. Два двоеточия означают, что параметр имеет необязательный аргумент; если текущий элемент argv содержит текст (то есть в самом имени слова, например «-oarg»), то он возвращается в optarg, в противном случае optarg содержит ноль. Это является расширением GNU. Если optstring содержит W, за которой следует точка с запятой, то -W foo рассматривается как длинный параметр --foo (параметр -W зарезервирован POSIX.2 для реализации расширений). Такое поведение является расширением GNU и недоступно в библиотеках до glibc 2.

По умолчанию getopt() переставляет элементы содержимого argv в процессе поиска, так что в конечном счёте все аргументы, не являющиеся параметрами, оказываются в конце. Реализованы также два других режима. Если первым символом optstring является «+» или задана переменная окружения POSIXLY_CORRECT, то обработка параметров прерывается сразу, как только находится символ не параметра. Если первым символом optstring является «-», то каждый элемент argv, не являющийся параметром, обрабатывается так, как если бы он был аргументом параметра с символом, имеющим код 1 (это используется программами, которые требуют параметры и другие элементы argv в любом порядке и их порядок важен). Специальный аргумент «--» служит для обозначения конца параметров независимо от режима.

Если getopt() не распознал символ параметра, то он выводит в stderr сообщение об ошибке, заносит символ в optopt и возвращает «?». Вызывающая программа может предотвратить вывод сообщения об ошибке, установив нулевое значение в opterr.

Если функция getopt() обнаруживает в argv символ параметра, не включённый в optstring, или если она обнаруживает пропущенный аргумент параметра, то она возвращает «?» и заносит во внешнюю переменную optopt действительный символ параметра. Если первым символом optstring (после любого необязательного «+» или «-», описанных выше) является двоеточие («:»), то для сообщения о пропущенном аргументе параметра getopt() возвращает «:» вместо «?». Если при обнаружении ошибки первый символ optstring не является двоеточием и значение внешней переменной opterr не равно нулю (по умолчанию так и есть), то getopt() выводит сообщение об ошибке.

getopt_long() и getopt_long_only()

Функция getopt_long() работает так же, как getopt(), за исключением того, что она воспринимает и длинные параметры, начинающиеся с двух дефисов (если программа принимает только длинные параметры, то значение optstring должно быть равно пустой строке (""), не NULL). Длинные параметры можно сокращать, если сокращение сохраняет уникальность параметра или полностью совпадает с одним из определённых параметров. Длинный параметр может иметь значение вида --параметр=значение или --параметр значение.

Аргумент longopts является указателем на первый элемент массива структур struct option, объявленного в <getopt.h> следующим образом

struct option {
    const char *name;
    int         has_arg;
    int        *flag;
    int         val;
};

Значения различных полей:

name

имя длинного параметра

has_arg

может быть: no_argument (или 0), если параметр не требует значения; required_argument (или 1), если параметр требует значения; optional_argument (или 2), если параметр может иметь необязательное значение.

flag

способ возвращения результатов для длинного параметра. Если flag равен NULL, то getopt_long() возвращает val (например, вызывающая программа может назначить val эквивалентом символа короткого параметра). В противном случае getopt_long() возвращает 0, а flag указывает на переменную, устанавливаемое значение которой равно val, если параметр найден; и оставляемую без изменений, если параметр не найден.

val

значение, которое возвращается или загружается в переменную, на которую указывает flag.

Последний элемент массива должен быть заполнен нулями.

Если longindex не равен NULL, то он указывает на переменную, содержащую индекс длинного параметра в соответствии с longopts.

Функция getopt_long_only() работает так же, как getopt_long(), но в качестве указателя длинного параметра может служить не только «--», но и «-». Если параметр, начинающийся с «-» (не с «--»), не совпадает с длинным параметром, но совпадает с коротким, то он обрабатывается как короткий параметр.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Если параметр найден, то getopt() возвращает символ параметра. Если все параметры командной строки обработаны, то getopt() возвращает -1. Если getopt() находит символ, которого нет в optstring, то возвращается «?». Если getopt() находит символ с отсутствующим аргументом, то возвращаемое значение зависит от первого символа optstring: если это «:», то возвращается «:», в противном случае возвращается «?».

Функции getopt_long() и getopt_long_only() также возвращают символ параметра, если распознан короткий параметр. Для длинного параметра они возвращают val, если flag равен NULL, и 0 в противном случае. Возвращаемые ошибки и -1 имеют то же значение, что и для getopt(), кроме того, «?» возвращается при двусмысленном толковании параметра.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
getopt(), getopt_long(), getopt_long_only()	безвредность в нитях	небезопасно (MT-Unsafe race:getopt env)

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

getopt():

В POSIX.1-2001, POSIX.1-2008 и POSIX.2 описана переменная окружения POSIXLY_CORRECT. В противном случае элементы argv на самом деле не являются const, потому что мы изменяем их порядок. Мы будем считать их const в прототипах для совместимости этих прототипов с другими операционными системами.

Использование «+» и «-» в optstring является расширением GNU.

В некоторых старых реализациях getopt() объявлялась в <stdio.h>. В SUSv1 разрешено её объявлять в <unistd.h> или <stdio.h>. В POSIX.1-2001 отмечено, что использование <stdio.h> УСТАРЕЛО. В POSIX.1-2001 запрещено объявлять эту функцию в <stdio.h>.

getopt_long() и getopt_long_only():

Эти функции являются расширениями GNU.

ЗАМЕЧАНИЯ

В программе, где анализируется несколько векторов параметров, или разбирается один вектор более одного раза и нужно использовать расширения GNU «+» и «-» в начале optstring или изменять значение POSIXLY_CORRECT между разборами, должна повторно инициализировать getopt() сбрасывая optind в 0, а не в обычное значение 1 (сброс в 0 вызывает принудительный вызов внутренней процедуры, повторно проверяющей POSIXLY_CORRECT и расширения GNU в optstring).

ПРИМЕР

getopt()

В приведённом ниже пример программы getopt() используется два параметра программы: -n без значения и -t значение со значением.

#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
int
main(int argc, char *argv[])
{
    int flags, opt;
    int nsecs, tfnd;
    nsecs = 0;
    tfnd = 0;
    flags = 0;
    while ((opt = getopt(argc, argv, "nt:")) != -1) {
        switch (opt) {
        case 'n':
            flags = 1;
            break;
        case 't':
            nsecs = atoi(optarg);
            tfnd = 1;
            break;
        default: /* '?' */
            fprintf(stderr, "Использование: %s [-t nsecs] [-n] имя\n",
                    argv[0]);
            exit(EXIT_FAILURE);
        }
    }
    printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\n",
            flags, tfnd, nsecs, optind);
    if (optind >= argc) {
        fprintf(stderr, "После параметра требуется значение\n");
        exit(EXIT_FAILURE);
    }
    printf("параметр = %s\n", argv[optind]);
    /* остальной код не показан */
    exit(EXIT_SUCCESS);
}

getopt_long()

Приведенный ниже пример программы иллюстрирует использование большинства возможностей getopt_long().

#include <stdio.h>     /* printf */
#include <stdlib.h>    /* exit */
#include <getopt.h>
int
main(int argc, char **argv)
{
    int c;
    int digit_optind = 0;
    while (1) {
        int this_option_optind = optind ? optind : 1;
        int option_index = 0;
        static struct option long_options[] = {
            {"add",     required_argument, 0,  0 },
            {"append",  no_argument,       0,  0 },
            {"delete",  required_argument, 0,  0 },
            {"verbose", no_argument,       0,  0 },
            {"create",  required_argument, 0, 'c'},
            {"file",    required_argument, 0,  0 },
            {0,         0,                 0,  0 }
        };
        c = getopt_long(argc, argv, "abc:d:012",
                 long_options, &option_index);
        if (c == -1)
            break;
        switch (c) {
        case 0:
            printf("параметр %s", long_options[option_index].name);
            if (optarg)
                printf(" со значением %s", optarg);
            printf("\n");
            break;
        case '0':
        case '1':
        case '2':
            if (digit_optind != 0 && digit_optind != this_option_optind)
              printf("Встречена цифра в двух различных элементах argv.\n");
            digit_optind = this_option_optind;
            printf("параметр %c\n", c);
            break;
        case 'a':
            printf("параметр a\n");
            break;
        case 'b':
            printf("параметр b\n");
            break;
        case 'c':
            printf("параметр c со значением «%s»\n", optarg);
            break;
        case 'd':
            printf("параметр d со значением «%s»\n", optarg);
            break;
        case '?':
            break;
        default:
            printf("?? getopt вернула код символа 0%o ??\n", c);
        }
    }
    if (optind < argc) {
        printf("элементы ARGV не параметры: ");
        while (optind < argc)
            printf("%s ", argv[optind++]);
        printf("\n");
    }
    exit(EXIT_SUCCESS);
}