getaddrinfo(3)

НАЗВАНИЕ
getaddrinfo - преобразует сетевой адрес и сервис

СИНТАКСИС
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>

int getaddrinfo(const char *node, const char *service,
                const struct addrinfo *hints,
                struct addrinfo **res);

void freeaddrinfo(struct addrinfo *res);

const char *gai_strerror(int errcode);

ОПИСАНИЕ
Функция getaddrinfo(3) объединяет действия функций getipnodebyname(3), getipnodebyaddr(3), getservbyname(3) и getservbyport(3) в одном интерфейсе. Функция getaddrinfo(3) создает одну или несколько структур адресов сокета, которые в дальнейшем могут быть использованы в вызовах функций bind(3) или connect(3) для создания сокета клиента или сервера. Функция может быть использована с подпроцессами.

Область применения функции getaddrinfo(3) не ограничивается структурами адреса сокета IPv4; если имеется поддержка IPv6, то также могут быть созданы структуры адреса сокета IPv6. Эти структуры адреса сокета могут быть непосредственно использованы bind(3) или connect(3) для подготовки сокета клиента или сервера к работе.

Структура addrinfo, используемая этой функцией, содержит следующие поля:

struct addrinfo {
    int     ai_flags;
    int     ai_family;
    int     ai_socktype;
    int     ai_protocol;
    size_t  ai_addrlen;
    struct sockaddr *ai_addr;
    char   *ai_canonname;
    struct addrinfo *ai_next;
};

getaddrinfo(3) устанавливает значение res для указания на выделяемый динамически связанный список структур addrinfo, связанных компонентом ai_next. Существует несколько причин того, почему связанный список может содержать более одной структуры addrinfo, включая: сетевой хост, имеющий несколько адресов; службу, доступную несколькии сокетным протоколам (например, один ее адрес - это SOCK_STREAM, а второй адрес - SOCK_DGRAM).

Поля ai_family, ai_socktype и ai_protocol имеют то же значение, что и соответствующие им параметры вызова функции socket(2). Функция getaddrinfo(3) возвращает адреса сокетов семейства IPv4 либо семейства IPv6 (ai_family будет содержать либо PF_INET, либо PF_INET6).

Параметр hints указывает на предпочтительный тип сокета или протокол. Нулевое значение hints указывает, что для работы возможен любой сетевой адрес или протокол. Если этот параметр не равен NULL, то он является указателем на структуру addrinfo, поля ai_family, ai_socktype и ai_protocol которой указывают на предпочтительный тип сокета. PF_UNSPEC в ai_family указывает на произвольное семейство протоколов (например, IPv4 либо IPv6). 0 в ai_socktype или ai_protocol указывает, что для работы возможен любой тип сокета и любой протокол соответственно. Поле ai_flags указывает на дополнительные опции, описанные ниже. Hесколько флагов указываются путем их логического сложения (OR). Все другие поля параметра hints должны содержать либо 0, либо "пустой" указатель.

Нулевое значение может принимать либо параметр node, либо service, но не оба одновременно. node указывает на сетевой адрес или в числовом виде (десятично-точечный формат для IPv4, шестнадцатеричный для IPv6), или в виде сетевого имени машины, поиск и разрешение адреса которой будут затем произведены. Если поле ai_flags параметра hints содержит флаг AI_NUMERICHOST, то параметр node должен быть числовым сетевым адресом. Флаг AI_NUMERICHOST запрещает любой потенциально долгий поиск сетевого адреса машины.

Функция getaddrinfo(3) создает связанный список структур addrinfo, по одной на каждый сетевой адрес, с учетом ограничений, наложенных параметром hints. Если в ai_flags параметра hints выставлен флаг AI_CANONNAME, то в ai_canonname устанавливается указатель официального имени машины. ai_family, ai_socktype и ai_protocol указывают на параметры создания сокета. Указатель на адрес сокета помещается в поле ai_addr, а длина адреса сокета (в байтах) помещается в член структуры ai_addrlen.

Если node равно NULL, то сетевой адрес в каждой сокетной структуре инициализируется в соответствии с флагом AI_PASSIVE, устанавливаемым в поле ai_flags параметра hints. Если установлен флаг AI_PASSIVE, то сетевой адрес каждой структуры не будет указан. Это используется серверными приложениями, предназначенными для приема соединений клиентов, имеющих любой сетевой адрес. Если флаг AI_PASSIVE сброшен, то сетевой адрес будет вписан в адрес интерфейса обратной петли. Это используется клиентскими приложениями, желающими установить соединение с сервером, запущенным в той же машине.

service вписывает номер порта в сетевой адрес каждой сокетной структуры. Если service равно NULL, то номер порта останется неинициализированным.

Функция freeaddrinfo(3) освобождает память, предназначенную для динамически выделяемого связанного списка res.

ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
getaddrinfo(3) возвращает 0 в случае успешного вызова или один из следующих ненулевых кодов ошибок:

EAI_FAMILY
    Запрошенное семейство адресов не поддерживается вообще.

EAI_SOCKTYPE
    Запрошенный тип сокета не поддерживается вообще.

EAI_BADFLAGS
    ai_flags содержит неверные флаги.

EAI_NONAME
    node или service неизвестны. Это ошибка возвращается также, если и node, и service равны NULL.

EAI_SERVICE
    Запрошенная служба недоступна для запрошенного типа сокета. Она может быть доступна через другой тип сокета.

EAI_ADDRFAMILY
    Указанная сетевая машина не имеет сетевых адресов в запрошенном семействе адресов.

EAI_NODATA
    Запрошенная сетевая машина существует, но не имеет определенных сетевых адресов.

EAI_MEMORY
    Hе хватает памяти.

EAI_FAIL
    Сервер имен вернул сообщение о постоянном отказе.

EAI_AGAIN
    Сервер имен вернул сообщение о временном отказе. Повторите попытку позже.

EAI_SYSTEM
    Другая системная ошибка, проверьте errno.

Функция gai_strerror(3) переводит эти коды в удобные для чтения строки, пригодные для вывода сообщений об ошибках.

СМ. ТАКЖЕ
getipnodebyname(3), getipnodebyaddr(3)