Provided by: manpages-ru-dev_4.27.0-1_all 
НАИМЕНОВАНИЕ
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(), │ Безвредность в нитях │ MT-Unsafe race:hostent env locale │
│ gethostent_r() │ │ │
├─────────────────────────────┼──────────────────────┼──────────────────────────────────────────────────┤
│ herror(), hstrerror() │ Безвредность в нитях │ MT-Safe │
├─────────────────────────────┼──────────────────────┼──────────────────────────────────────────────────┤
│ gethostent() │ Безвредность в нитях │ MT-Unsafe race:hostent race:hostentbuf env │
│ │ │ locale │
├─────────────────────────────┼──────────────────────┼──────────────────────────────────────────────────┤
│ gethostbyname2() │ Безвредность в нитях │ MT-Unsafe race:hostbyname2 env locale │
├─────────────────────────────┼──────────────────────┼──────────────────────────────────────────────────┤
│ gethostbyaddr_r(), │ Безвредность в нитях │ MT-Safe env locale │
│ gethostbyname_r(), │ │ │
│ gethostbyname2_r() │ │ │
└─────────────────────────────┴──────────────────────┴──────────────────────────────────────────────────┘
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 или
более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.
Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом
разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских
переводчиков.
Справочные страницы Linux 6.9.1 2 мая 2024 г. gethostbyname(3)