inet_net_pton(3)

НАИМЕНОВАНИЕ
inet_net_pton, inet_net_ntop - преобразует номер сети Интернета

БИБЛИОТЕКА
Resolver library (libresolv, -lresolv)

СИНТАКСИС
#include <arpa/inet.h>

int inet_net_pton(size_t nsize;
                  int af, const char *pres,
                  void netp[nsize], size_t nsize);
char *inet_net_ntop(int bits, size_t psize;
                  int af,
                  const void netp[(bits - CHAR_BIT + 1) / CHAR_BIT],
                  int bits,
                  char pres[psize], size_t psize);

    Требования макроса тестирования свойств для 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()
The inet_net_pton() function converts pres, a null-terminated string containing an Internet network number in presentation format to network format. The result of the conversion, which is in network byte order, is placed in the buffer pointed to by netp. (The netp argument typically points to an in_addr structure.) The nsize argument specifies the number of bytes available in 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: адрес сети в виде чисел, разделённых точками, затем косая черта и размер сети в битах.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
On success, inet_net_pton() returns the number of bits in the network number. On error, it returns -1, and errno is set to indicate the error.

On success, inet_net_ntop() returns pres. On error, it returns NULL, and errno is set to indicate the error.

ОШИБКИ

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

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

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

СТАНДАРТЫ
Отсутствуют.

ПРИМЕЧАНИЯ

  Представленческий формат входных данных 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() returned: 24
    inet_net_ntop() yielded:  193.168.0/24
    Raw address:              c1a80000

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

    $ ./a.out 193.168 0xffffffff;
    inet_net_pton() returned: 24
    inet_net_ntop() yielded:  193.168.0/24
    Raw address:              c1a800ff

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

    $ ./a.out 193.168.1.128;
    inet_net_pton() returned: 32
    inet_net_ntop() yielded:  193.168.1.128/32
    Raw address:              c1a80180

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

    $ ./a.out 193.168.1.128/24;
    inet_net_pton() returned: 24
    inet_net_ntop() yielded:  193.168.1/24
    Raw address:              c1a80180

  Исходный код программы
    /* Link with "-lresolv" */

    #include <arpa/inet.h>
    #include <err.h>
    #include <stdio.h>
    #include <stdlib.h>

    int
    main(int argc, char *argv[])
    {
        char buf[100];
        struct in_addr addr;
        int bits;

        if (argc < 2) {
            fprintf(stderr,
                    "Usage: %s presentation-form [addr-init-value]\n",
                    argv[0]);
            exit(EXIT_FAILURE);
        }

        /* If argv[2] is supplied (a numeric value), use it to initialize
           the output buffer given to inet_net_pton(), so that we can see
           that inet_net_pton() initializes only those bytes needed for
           the network number.  If argv[2] is not supplied, then initialize
           the buffer to zero (as is recommended practice).  */

        addr.s_addr = (argc > 2) ? strtod(argv[2], NULL) : 0;

        /* Convert presentation network number in argv[1] to binary.  */

        bits = inet_net_pton(AF_INET, argv[1], &addr, sizeof(addr));
        if (bits == -1)
            err(EXIT_FAILURE, "inet_net_ntop");

        printf("inet_net_pton() returned: %d\n", bits);

        /* Convert binary format back to presentation, using 'bits'
           returned by inet_net_pton().  */

        if (inet_net_ntop(AF_INET, &addr, bits, buf, sizeof(buf)) == NULL)
            err(EXIT_FAILURE, "inet_net_ntop");

        printf("inet_net_ntop() yielded:  %s\n", buf);

        /* Display 'addr' in raw form (in network byte order), so we can
           see bytes not displayed by inet_net_ntop(); some of those bytes
           may not have been touched by inet_net_ntop(), and so will still
           have any initial value that was specified in argv[2].  */

        printf("Raw address:              %x\n", htonl(addr.s_addr));

        exit(EXIT_SUCCESS);
    }

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

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (debian-l10n-russian@lists.debian.org).