getsubopt(3) анализирует подпараметры аргументов строки

ОБЗОР

#include <stdlib.h>

int getsubopt(char **optionp, char * const *tokens, char **valuep);

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

getsubopt():

_XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* начиная с glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

ОПИСАНИЕ

Функция getsubopt() анализирует список подпараметров, указываемых через запятую, заданный в optionp (такой список подпараметров, обычно, создаётся при использовании getopt(3) для разбора командной строки; например, смотрите параметр -o в mount(8)). Каждый подпараметр может содержать связанное с ним значение, которое отделяется от имени подпараметра знаком равно. Вот пример строки, которую можно передать в optionp:

ro,name=xyz

Аргумент tokens — указатель на массив (завершается NULL) указателей на токены, которые getsubopt() будет просматривать при поиске в optionp. Токены должны быть различающимися строками (завершающимися null), содержащими, как минимум, один символ и не содержащих знаков равно или запятых.

При каждом вызове getsubopt() возвращается информация о следующем необработанном подпараметре в optionp. Первый знак равно в подпараметре (если есть) считается разделителем имени и значения в этом подпараметре. Значение длится до последующей запятой или (для последнего подпараметра) до конца строки. Если имя подпараметра совпадает с известным именем из tokens, и найдено строка-значение, то getsubopt() записывает в *valuep адрес этой строки. Первая запятая в optionp перезаписывается байтом null, поэтому *valuep — точное «строка-значение» этого подпараметра.

Если подпараметр распознан, но значение строки не найдено, то *valuep присваивается NULL.

При завершении работы getsubopt() значение optionp указывает на следующий подпараметр или на байт null ('\0') в конце строки (в случае, если последний подпараметр был только что обработан).

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

Если в optionp распознан первый подпараметр, то getsubopt() возвращает индекс элемента в tokens найденного подпараметра. В противном случае возвращается -1 и значение *valuep указывает на целую строку name[=value].

Так как *optionp изменяется, первый подпараметр перед вызовом getsubopt() не (не всегда) тот же самый, что и первый подпараметр после getsubopt().

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).
ИнтерфейсАтрибутЗначение
getsubopt() безвредность в нитяхбезвредно (MT-Safe)

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

POSIX.1-2001, POSIX.1-2008.

ЗАМЕЧАНИЯ

Так как getsubopt() заменяет запятые, найденные в строке *optionp, то строка должна быть доступна на запись; она не может быть строковой константой.

ПРИМЕР

Следующая программа ожидает подпараметры после параметра «-o».

#define _XOPEN_SOURCE 500
#include <stdlib.h>
#include <assert.h>
#include <stdio.h>
int
main(int argc, char **argv)
{
    enum {
        RO_OPT = 0,
        RW_OPT,
        NAME_OPT
    };
    char *const token[] = {
        [RO_OPT]   = "ro",
        [RW_OPT]   = "rw",
        [NAME_OPT] = "name",
        NULL
    };
    char *subopts;
    char *value;
    int opt;
    int readonly = 0;
    int readwrite = 0;
    char *name = NULL;
    int errfnd = 0;
    while ((opt = getopt(argc, argv, "o:")) != -1) {
        switch (opt) {
        case 'o':
            subopts = optarg;
            while (*subopts != '\0' && !errfnd) {
            switch (getsubopt(&subopts, token, &value)) {
            case RO_OPT:
                readonly = 1;
                break;
            case RW_OPT:
                readwrite = 1;
                break;
            case NAME_OPT:
                if (value == NULL) {
                    fprintf(stderr, "Отсутствует значение для "
                            "подпараметра '%s'\n", token[NAME_OPT]);
                    errfnd = 1;
                    continue;
                }
                name = value;
                break;
            default:
                fprintf(stderr, "Совпадения не найдены "
                        "для токена: /%s/\n", value);
                errfnd = 1;
                break;
            }
        }
        if (readwrite && readonly) {
            fprintf(stderr, "Может указываться только одно из '%s' "
                    "и '%s'\n", token[RO_OPT], token[RW_OPT]);
            errfnd = 1;
        }
        break;
        default:
            errfnd = 1;
        }
    }
    if (errfnd || argc == 1) {
        fprintf(stderr, "\nИспользование: %s -o <подпараметр>\n", argv[0]);
        fprintf(stderr, "возможны подпараметры: 'ro', 'rw', "
                "и 'name=<значение>'\n");
        exit(EXIT_FAILURE);
    }
    /* Остальная часть программы… */
    exit(EXIT_SUCCESS);
}