gethostbyname(3)

НАИМЕНОВАНИЕ
gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r - получение записи о сетевом узле

БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)

ОБЗОР
#include <netdb.h>

void sethostent(int stayopen);
void endhostent(void);

[[deprecated]] extern int h_errno;

[[deprecated]] struct hostent *gethostbyname(const char *name);
[[deprecated]] struct hostent *gethostbyaddr(const void addr[.len],
                                             socklen_t len, int type);

[[deprecated]] void herror(const char *s);
[[deprecated]] const char *hstrerror(int err);

/* расширение System V/POSIX */
struct hostent *gethostent(void);

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

int gethostent_r(struct hostent *restrict ret,
                 char buf[restrict .buflen], size_t buflen,
                 struct hostent **restrict result,
                 int *restrict h_errnop);

[[deprecated]]
int gethostbyaddr_r(const void addr[restrict .len], socklen_t len,
                 int type,
                 struct hostent *restrict ret,
                 char buf[restrict .buflen], size_t buflen,
                 struct hostent **restrict result,
                 int *restrict h_errnop);
[[deprecated]]
int gethostbyname_r(const char *restrict name,
                 struct hostent *restrict ret,
                 char buf[restrict .buflen], size_t buflen,
                 struct hostent **restrict result,
                 int *restrict h_errnop);
[[deprecated]]
int gethostbyname2_r(const char *restrict name, int af,
                 struct hostent *restrict ret,
                 char buf[restrict .buflen], size_t buflen,
                 struct hostent **restrict result,
                 int *restrict h_errnop);

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

gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r():
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc up to and including 2.19:
        _BSD_SOURCE || _SVID_SOURCE

herror(), hstrerror():
    Since glibc 2.19:
        _DEFAULT_SOURCE
    glibc 2.8 to glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE
    Before glibc 2.8:
        none

h_errno:
    Since glibc 2.19
        _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L
    glibc 2.12 to glibc 2.19:
        _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
    Before glibc 2.12:
        none

ОПИСАНИЕ
Функции gethostbyname*(), gethostbyaddr*(), herror() и hstrerror() являются устаревшими. Вместо них в приложениях следует использовать getaddrinfo(3), getnameinfo(3) и gai_strerror(3).

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

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

Функция gethostbyname() возвращает структуру типа hostent для узла name. Значением name может быть или имя узла, или адрес IPv4 в стандартной точечной записи (как в inet_addr(3)). Если name — адрес IPv4, то поиск не выполняется и gethostbyname() просто копирует name в поле h_name, а его эквивалент struct in_addr — в поле h_addr_list[0] возвращаемой структуры hostent Если name не оканчивается точкой и установлена переменная окружения HOSTALIASES, то name сначала ищется в файле псевдонимов, указанном в HOSTALIASES (формат файла описан в hostname(7)). Если name не оканчивается точкой, то поиск производится с текущем доменом и его предками.

The gethostbyaddr() function returns a structure of type hostent for the given host address addr of length len and address type type. Valid address types are AF_INET and AF_INET6 (defined in <sys/socket.h>). The host address argument is a pointer to a struct of a type depending on the address type, for example a struct in_addr * (probably obtained via a call to inet_addr(3)) for address type AF_INET.

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

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

The domain name queries carried out by gethostbyname() and gethostbyaddr() rely on the Name Service Switch (nsswitch.conf(5)) configured sources or a local name server (named(8)). The default action is to query the Name Service Switch (nsswitch.conf(5)) configured sources, failing that, a local name server (named(8)).

  Историческая справка
Современным способом управления порядком поиска узлов является файл nsswitch.conf(5).

В glibc 2.4 и старее, ключевое слово order использовалось для управления порядком поиска узла в /etc/host.conf (host.conf(5)).

Структура hostent определена в <netdb.h> таким образом:

    struct hostent {
        char  *h_name;            /* официальное имя узла */
        char **h_aliases;         /* список псевдонимов */
        int    h_addrtype;        /* тип адреса узла */
        int    h_length;          /* длина адреса */
        char **h_addr_list;       /* список адресов */
    }
    #define h_addr h_addr_list[0] /* для обратной совместимости */

Члены структуры hostent:

h_name
    Официальное имя узла.

h_aliases
    Массив альтернативных имён узла, заканчивается указателем null.

h_addrtype
    Тип адреса; AF_INET или AF_INET6.

h_length
    Длина адреса в байтах.

h_addr_list
    Массив указателей сетевых адресов узла (в сетевом порядке байт), заканчивается указателем null.

h_addr
    Первый адрес из h_addr_list, для обратной совместимости.

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

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

HOST_NOT_FOUND
    Заданный узел неизвестен.

NO_DATA
    Запрашиваемое имя корректно, но не имеет IP-адреса. При другом типе запроса для этого домена сервер имён может вернуть ответ. Синонимом NO_DATA является константа NO_ADDRESS.

NO_RECOVERY
    Произошла неисправимая ошибка сервера имён.

TRY_AGAIN
    Произошла временная ошибка у авторитативного сервера имён. Попробуйте позже.

ФАЙЛЫ

/etc/host.conf
    файл с настройками резолвера

/etc/hosts
    файл базы данных узлов

/etc/nsswitch.conf
    настройки диспетчера службы имён

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
gethostbyname() | Безвредность в нитях | MT-Unsafe race:hostbyname env locale
gethostbyaddr() | Безвредность в нитях | MT-Unsafe race:hostbyaddr env locale
sethostent(), endhostent(), gethostent_r() | Безвредность в нитях | MT-Unsafe race:hostent env locale
herror(), hstrerror() | Безвредность в нитях | MT-Safe
gethostent() | Безвредность в нитях | MT-Unsafe race:hostent race:hostentbuf env locale
gethostbyname2() | Безвредность в нитях | MT-Unsafe race:hostbyname2 env locale
gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r() | Безвредность в нитях | MT-Safe env locale

In the above table, hostent in race:hostent signifies that if any of the functions sethostent(), gethostent(), gethostent_r(), or endhostent() are used in parallel in different threads of a program, then data races could occur.

СТАНДАРТЫ

sethostent()
endhostent()
gethostent()
    POSIX.1-2008.

gethostent_r()
    GNU.

Другие:
    Отсутствуют.

ИСТОРИЯ

sethostent()
endhostent()
gethostent()
    POSIX.1-2001.

gethostbyname()
gethostbyaddr()
h_errno
    Marked obsolescent in POSIX.1-2001. Removed in POSIX.1-2008, recommending the use of getaddrinfo(3) and getnameinfo(3) instead.

ПРИМЕЧАНИЯ
Функции gethostbyname() и gethostbyaddr() могут возвращать указатели на статические данные, которые могут быть перезаписаны при последующих вызовах. Копирования struct hostent недостаточно, так как она содержит указатели; требуется глубокое копирование.

В первой реализации BSD аргумент len у gethostbyname() имел тип int. Стандарт SUSv2 содержит ошибку и объявляет аргумент len у gethostbyaddr() с типом size_t (это неправильно, так как он должен быть int, а не size_t. В POSIX.1-2001 указанный тип — socklen_t, который подходит). Смотрите также accept(2).

У прототипа BSD gethostbyaddr() первый аргумент имеет тип const char *.

  Расширение System V/POSIX
В POSIX требуется вызов gethostent(), который должен возвращать следующий элемент из базы данных узлов. При использовании DNS/BIND это не имеет смысла, но допустимо, если база данных узлов — файл, который можно читать строку за строкой. На многих системах процедура с таким именем выполняет чтение из файла /etc/hosts. Она может быть доступна только когда библиотека собрана без поддержки DNS. Версия glibc игнорирует записи ipv6. Эта функция не реентерабельна; в glibc добавлена реентерабельная версия gethostent_r().

  Расширения GNU
glibc2 also has a gethostbyname2() that works like gethostbyname(), but permits to specify the address family to which the address must belong.

glibc2 also has reentrant versions gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), and gethostbyname2_r(). The caller supplies a hostent structure ret which will be filled in on success, and a temporary work buffer buf of size buflen. After the call, result will point to the result on success. In case of an error or if no entry is found result will be NULL. The functions return 0 on success and a nonzero error number on failure. In addition to the errors returned by the nonreentrant versions of these functions, if buf is too small, the functions will return ERANGE, and the call should be retried with a larger buffer. The global variable h_errno is not modified, but the address of a variable in which to store error numbers is passed in h_errnop.

ОШИБКИ
Функция gethostbyname() не работает с частями строки адреса IPv4 в точечном формате, если они записаны шестнадцатеричными числами.

СМОТРИТЕ ТАКЖЕ
getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3), resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Kirill Rekhov <krekhov.dev@gmail.com>

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

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