gethostbyname, gethostbyaddr, sethostent, endhostent, herror, hstrerror - получают информацию о машине в сети

НАЗВАНИЕ
gethostbyname, gethostbyaddr, sethostent, endhostent, her-
ror, hstrerror - получают информацию о машине в сети

СИНТАКСИС
#include
extern int h_errno;

struct hostent *gethostbyname(const char *name);

#include /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr,
int len, int type);

void sethostent(int stayopen);

void endhostent(void);

void herror(const char *s);

const char *hstrerror(int err);

/* GNU extensions */
struct hostent *gethostbyname2(const char *name, int af);

int gethostbyname_r (const char *name,
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);

int gethostbyname2_r (const char *name, int af,
struct hostent *ret, char *buf, size_t buflen,
struct hostent **result, int *h_errnop);

ОПИСАНИЕ
Функция gethostbyname() возвращает структуру типа hostent
машине с именем name. В данном случае name является либо
именем машины, либо адресом IPv4 в стандартной точечной
нотации, либо адресом IPv6 в нотации с двоеточием (и,
возможно, точкой) в качестве разделителя (см. описание
адресов IPv6 в RFC 1884). Если name является адресом IPv4
или IPv6, то поиск не производится и gethostbyname()
просто копирует name в поле h_name, а его эквивалент для
структуры struct in_addr копируется в поле h_addr_list[0]
возвращаемой структуры hostent. Если name не оканчивается
точкой и установлена переменная окружения HOSTALIASES, то
в файле, на который указывает HOSTALIASES, будет
произведен поиск name (формат файла приведен в host-
name(7)). Если name не оканчивается точкой, то будет
произведен поиск в текущем домене и его родителях.

Функция gethostbyaddr() возвращает структуру типа hostent
указанному адресу машины addr, длина которого равна len, а
тип адреса равен type. В данный момент типом адреса может
быть только AF_INET.

Функция sethostent() (если значение stayopen истинно (1))
указывает, что соединенный сокет TCP должен быть
использован для отправки запросов серверу имен, а также
то, что соединение должно оставаться открытым во время
последующих запросов. В противном случае для отправки
серверу имен запросов будут использоваться датаграммы UDP.

Функция endhostent() закрывает соединение TCP для запроса
сервера имен.

Функция error() (устаревшая) выводит сообщение об ошибке,
связанное с текущим значением h_errno в стандартном потоке
вывода ошибок.

Функция hstrerror() (устаревшая) в качестве параметра
использует номер ошибки (обычно h_errno) и возвращает
соответствующую строку сообщения.

Запросы имени домена, производимые функциями gethostby-
name() и gethostbyaddr(), используют комбинацию данных
любых или всех серверов имен named(8), записи из файла
/etc/hosts и комбинацию данных сетевой информационной
службы (NIS или YP) в зависимости от порядка строк файла
/etc/host.conf (см. resolv+(8). По умолчанию
производится опрос named (8), затем /etc/hosts.

Структура hostent определена в следующим
образом:

struct hostent {
char *h_name; /* официальное имя машины */
char **h_aliases; /* список псевдонимов */
int h_addrtype; /* тип адреса машины */
int h_length; /* длина адреса */
char **h_addr_list; /* список адресов */
}

Полями структуры hostent являются:

h_name (официальное имя машины);

h_aliases
(оканчивающийся нулем массив альтернативных имен
машины);

h_addrtype
(тип адреса; в настоящее время всегда AF_INET);

h_length
(длина адреса в байтах);

h_addr_list
(оканчивающийся нулем массив сетевых адресов машины
в сетевом порядке байтов);

h_addr (первый адрес в h_addr_list определен для
совместимости с более ранними версиями).

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функции gethostbyname() и gethostbyaddr() возвращают
структуру hostent или, в случае ошибки, указатель NULL. В
последнем случае переменная h_errno содержит номер ошибки.

КОДЫ ОШИБОК
Переменная h_errno может принимать следующие значения:

HOST_NOT_FOUND
Указанный хост неизвестен.

NO_ADDRESS или NO_DATA
Запрошенное имя существует, но не имеет IP-адреса.

NO_RECOVERY
Hепоправимая ошибка сервера имен.

TRY_AGAIN
Временная ошибка на официальном сервере имен.
Повторите попытку позже.

ФАЙЛЫ
/etc/host.conf
(файл настройки системы разрешения имен);

/etc/hosts
(файл базы данных машин).

СООТВЕТСТВИЕ СТАНДАРТАМ
BSD 4.3.

ЗАМЕЧАНИЯ
Стандарт SUS-v2 содержит ошибки и обозначает тип параметра
len функции gethostbyaddr() как size_t (что является
неправильным: он должен представлять собой int, а size_t
таким типом не является). В POSIX 1003.1-2001 этот тип
равен socklen_t, что является корректным.

Функции gethostbyname() и gethostbyaddr() могут возвращать
указатели на статические данные, которые могут быть
перезаписаны более поздними вызовами. Простого копирования
структуры struct hostent недостаточно, так как эта
структура содержит указатели - небоходимо глубокое
копирование.

В glibc2 имеется также функция gethostbyname2() работающая
как gethostbyname(), но позволяющая обозначать семейство,
к которому должен принадлежать адрес.

Кроме того, glibc2 содержит реентрантные версии gethostby-
name_r() и gethostbyname2_r(). Эти функции возвращают 0
при успешном завершении и ненулевое значение при ошибке.
Результат вызова заносится в структуру с адресом ret.
После вызова *result может быть NULL при ошибке или
указывать на результат при успешном завершении.
Вспомогательные данные заносятся в буфер buf длиной
buflen. (Если буфер слишком мал, то функция вернет
ERANGE.) Глобальная переменная h_errno не изменяется, но
в h_errnop передается адрес переменной, в которую будет
занесен код ошибки.

POSIX 1003.1-2001 заменяет gethostbyaddr() на gethostby-
name().

struct hostent *getipnodebyaddr(const void *restrict addr,
socklen_t len, int type, int *restrict error_num);

struct hostent *getipnodebyname(const char *name,
int type, int flags, int *error_num);