---

   getopt - optopt

---

---

ОБЗОР

#include <unistd.h>

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

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

---

ОПИСАНИЕ

Переменная 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()

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

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

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

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

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

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

---

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

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

ОКРУЖЕНИЕ

POSIXLY_CORRECT Если установлена эта переменная, то обработка параметров прерывается на первом аргументе, не являющемся параметром.

_<PID>_GNU_nonoption_argv_flags_ Эта переменная использовалась bash(1) 2.0 для связи с glibc, аргументы которой являются результатом раскрытия шаблонов и, таким образом, не должны рассматриваться как параметры. Такое поведение было удалено из bash(1) версии 2.01, но поддержка осталась в glibc.

---

АТРИБУТЫ

Интерфейс Атрибут Значение
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.

---

ЗАМЕЧАНИЯ

---

ПРИМЕР

getopt()

#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()

#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);
}