INET_NET_PTON(3)

ИМЯ
inet_net_pton, inet_net_ntop - преобразует номер сети Интернета

ОБЗОР
#include <arpa/inet.h>

int inet_net_pton(int af, const char *pres,
                  void *netp, size_t nsize);
char *inet_net_ntop(int af, const void *netp, int bits,
                    char *pres, size_t psize);

Компонуется при указании параметра -lresolv.

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

inet_net_pton(), inet_net_ntop():
    Начиная с glibc 2.20:
        _DEFAULT_SOURCE
    До glibc 2.20:
        _BSD_SOURCE || _SVID_SOURCE

ОПИСАНИЕ
Эти функции преобразуют номера сетей, представленных в сетевом формате (т. е. двоичном), в представленческий формат (т. е., печатаемый) и обратно.

В обоих функциях в af задаётся адресное семейство для преобразования; поддерживается только значение AF_INET.

  inet_net_pton()
Функция inet_net_pton() преобразует pres, строку с null в конце, содержащую номер сети Интернета в представленческом формате, в сетевой формат. Результат преобразования с сетевым порядком байт помещается в буфер, указанный в net (аргумент netp, обычно, указывает на структуру in_addr). В аргументе nsize задаётся количество доступных байт в netp.

При успешном выполнении inet_net_pton() возвращает количество бит в поле номера сети результата, помещённого в netp. Обсуждение входного представленческого формата и возвращаемое значение смотрите в ЗАМЕЧАНИЯХ.

Замечание: буфер, указанный в netp, должен быть заполнен нулями до вызова inet_net_pton(), так как вызов изменяет только байты, необходимые для номера сети (или сколько явно указано в pres), что может быть меньше, чем байт в полном адресе сети.

  inet_net_ntop()
Функция inet_net_ntop() преобразует номер сети в буфере, указанном в netp, в представленческий формат; значение *netp рассматривается в сетевом порядке байт. В аргументе bits задаётся количество бит в номере сети из *netp.

Строка в представленческом формате с null в конце помещается в буфер, на который указывает pres. В аргументе psize задаётся количество байт, доступных в pres. Представленческая строка имеет формат CIDR: адрес сети в виде чисел, разделённых точками, затем косая черта и размер сети в битах.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении inet_net_pton() возвращает количество бит в номере сети. При ошибке возвращается -1, а в errno содержится код ошибки.

При успешном выполнении inet_net_ntop() возвращается pres. При ошибке возвращается NULL, а в errno содержится код ошибки.

ОШИБКИ

EAFNOSUPPORT
    В af указано значение, отличное от AF_INET.

EMSGSIZE
    Размер буфера результата недостаточен.

ENOENT
    (inet_net_pton()) Значение pres имеет некорректный представленческий формат.

СООТВЕТСТВИЕ СТАНДАРТАМ
Функции inet_net_pton() и inet_net_ntop() являются нестандартными, но широко распространены.

ЗАМЕЧАНИЯ

  Представленческий формат входных данных inet_net_pton()
Номер сети может задаваться в виде шестнадцатеричного значения или в точечно-десятичной форме.

Шестнадцатеричное значение определяется по начальному «0x» или «0X». Шестнадцатеричные цифры заполняют полубайты (половина октета) номера сети слева направо в сетевом порядке байт.

В точечно-десятичной форме указываются, максимум, первые четыре октета, с помощью десятичных чисел и точек. То есть можно использовать следующие форматы:

    a.b.c.d
    a.b.c
    a.b
    a

Каждая часть — это число от 0 до 255, которое заполняет один байт получаемого номера сети; заполнение производится слева направо, в сетевом порядке байт (от старшего к младшему). Если часть пропущена, то байт результата в номере сети равно нулю.

В шестнадцатеричном или точечно-десятичном формате номер сети может содержать косую черту и число от 0 до 32, которое задаёт размер сети в битах.

  Возвращаемое значение inet_net_pton()
Возвращаемым значением inet_net_pton() является количество бит поля номера сети. Если входная строка представленческих данных заканчивается косой чертой и явным значением размера, то это значение является результатом inet_net_pton(). В противном случае возвращаемое значение, bits, определяется следующим образом:

*   Если наиболее значимый байт номер сети больше или равен 240, то bits равно 32.

*   Или же, если наиболее значимый байт номер сети больше или равен 224, то bits равно 4.

*   Или же, если наиболее значимый байт номер сети больше или равен 192, то bits равно 24.

*   Или же, если наиболее значимый байт номер сети больше или равен 128, то bits равно 16.

*   В противном случае bits равно 8.

Если значение результата bits после определения больше или равно 8, но количество октетов, указанных в номере сети, превышает bits/8, то bits присваивается 8 кратное количество октетов, указанных на самом деле.

ПРИМЕР
Программа, представленная далее, показывает использование inet_net_pton() и inet_net_ntop(). В ней используется inet_net_pton() для преобразования адреса сети из значения в представленческом формате, переданном в первом аргументе командной строки, в двоичную форму; выводится полученное из inet_net_pton() значение. Затем используется inet_net_ntop() для преобразования двоичной формы обратно в представленческий формат, и выводится полученная строка.

Чтобы продемонстрировать, что inet_net_pton() может не записывать все байты аргумента netp, программе можно передать в командной строке необязательный второй аргумент — число, используемое для заполнения буфера перед вызовом inet_net_pton(). В строке результата программа показывает все байты буфера, возвращаемого inet_net_pton(), позволяя пользователю увидеть какие байты не изменялись inet_net_pton().

Пример работы, показывающий, как inet_net_pton() прогнозирует количество бит в номере сети:

    $ ./a.out 193.168
    inet_net_pton() вернула: 24
    inet_net_ntop() выдала:  193.168.0/24
    Необработанный адрес:              c1a80000

Демонстрируется, как inet_net_pton() не обнуляет неиспользованные байты в буфере результата:

    $ ./a.out 193.168 0xffffffff
    inet_net_pton() вернула: 24
    inet_net_ntop() выдала:  193.168.0/24
    Необработанный адрес:              c1a800ff

Демонстрируется, как inet_net_pton() расширяет прогнозируемый размер номера сети, если полученное количество байт в представленческой строке превышает прогнозируемое значение:

    $ ./a.out 193.168.1.128
    inet_net_pton() вернула: 32
    inet_net_ntop() выдала:  193.168.1.128/32
    Необработанный адрес:              c1a80180

Явно указанный размер номера сети заменяет любой прогнозируемый (но все дополнительные байты, указанные явно, всё равно будут использованы inet_net_pton() для заполнения буфера результата):

    $ ./a.out 193.168.1.128/24
    inet_net_pton() вернула: 24
    inet_net_ntop() выдала:  193.168.1/24
    Необработанный адрес:              c1a80180

  Исходный код программы
    /* Компоновать с «-lresolv» */
    #include <arpa/inet.h>
    #include <stdio.h>
    #include <stdlib.h>
    #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                            } while (0)
    int
    main(int argc, char *argv[])
    {
        char buf[100];
        struct in_addr addr;
        int bits;
        if (argc < 2) {
            fprintf(stderr,
                    "Использование: %s представленческая-форма \
                                       [начальное-значение-адреса]\n",
                    argv[0]);
            exit(EXIT_FAILURE);
        }
        /* Если указан argv[2] (число), то использовать его для инициализации
           буфера результата, передаваемого inet_net_pton() для того, чтобы
           мы могли увидеть, что inet_net_pton() инициализирует только те
           байты, которые нужны для номера сети. Если argv[2] не указан, то
           буфер инициализируется нулями (как рекомендуется). */
        addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;
        /* Преобразование представленческого формата номера сети
           из argv[1] в двоичный */
        bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
        if (bits == -1)
            errExit("inet_net_ntop");
        printf("inet_net_pton() вернула: %d\n", bits);
        /* Преобразование двоичного формата обратно в представленческий,
           используя значение «bits», возвращённое inet_net_pton() */
        if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
            errExit("inet_net_ntop");
        printf("inet_net_ntop() выдала:  %s\n", buf);
        /* Показать «addr» в необработанном виде (в сетевом порядке байт)
           для того, чтобы мы могли увидеть байты, не отображаемые
           inet_net_ntop(); некоторые из этих байт могут быть не изменены
           inet_net_ntop(), и поэтому будут содержать любое начальное
           значение, которое было задано в argv[2]. */
        printf("Необработанный адрес:            %x\n", htonl(addr.s_addr));
        exit(EXIT_SUCCESS);
    }

СМОТРИТЕ ТАКЖЕ
inet(3), networks(5)