LinuxDoc.Rugetaddrinfo - преобразует сетевой адрес и сервис
НАЗВАНИЕgetaddrinfo - преобразует сетевой адрес и сервис
СИНТАКСИС
#include
#include
#include
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) объединяет действия функций getipn-
odebyname(3), getipnodebyaddr(3), getservbyname(3) и get-
servbyport(3) в одном интерфейсе. Функция getaddrinfo(3)
создает одну или несколько структур адресов сокета,
которые в дальнейшем могут быть использованы в вызовах
функций bind(3) или connect(3) для создания сокета клиента
или сервера. Функция может быть использована с
подпроцессами.
Область применения функции getaddrinfo(3) не
ограничивается структурами адреса сокета IPv4; если
имеется поддержка IPv6, то также могут быть созданы
структуры адреса сокета IPv6. Эти структуры адреса сокета
могут быть непосредственно использованы bind(3) или con-
nect(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_fam-
ily будет содержать либо PF_INET, либо PF_INET6).
Параметр hints указывает на предпочтительный тип сокета
или протокол. Нулевое значение hints указывает, что для
работы возможен любой сетевой адрес или протокол. Если
этот параметр не равен NULL, то он является указателем на
структуру addrinfo, поля ai_family, ai_socktype и ai_pro-
tocol которой указывают на предпочтительный тип сокета.
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_PAS-
SIVE, устанавливаемым в поле ai_flags параметра hints.
Если установлен флаг AI_PASSIVE, то сетевой адрес каждой
структуры не будет указан. Это используется серверными
приложениями, предназначенными для приема соединений
клиентов, имеющих любой сетевой адрес. Если флаг AI_PAS-
SIVE сброшен, то сетевой адрес будет вписан в адрес
интерфейса обратной петли. Это используется клиентскими
приложениями, желающими установить соединение с сервером,
запущенным в той же машине.
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) переводит эти коды в удобные для
чтения строки, пригодные для вывода сообщений об ошибках.