gethostbyname(3) Library Functions Manual gethostbyname(3) NAZWA gethostbyname, gethostbyaddr, sethostent, gethostent, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r - zwraca wpis sieciowy komputera BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include void sethostent(int stayopen); void endhostent(void); [[przestarzale]] extern int h_errno; [[przestarzale]] struct hostent *gethostbyname(const char *name); [[przestarzale]] struct hostent *gethostbyaddr(socklen_t size; const void addr[size], socklen_t size, int type); [[przestarzale]] void herror(const char *s); [[przestarzale]] const char *hstrerror(int err); /* Rozszerzenie systemu V/POSIX */ struct hostent *gethostent(void); /* Rozszerzenia GNU */ [[przestarzale]] struct hostent *gethostbyname2(const char *name, int af); int gethostent_r(size_t bufsize; struct hostent *restrict ret, char buf[restrict bufsize], size_t bufsize, struct hostent **restrict result, int *restrict h_errnop); [[przestarzale]] int gethostbyaddr_r(socklen_t size, size_t bufsize; const void addr[restrict size], socklen_t size, int type, struct hostent *restrict ret, char buf[restrict bufsize], size_t bufsize, struct hostent **restrict result, int *restrict h_errnop); [[przestarzale]] int gethostbyname_r(size_t bufsize; const char *restrict name, struct hostent *restrict ret, char buf[restrict bufsize], size_t bufsize, struct hostent **restrict result, int *restrict h_errnop); [[przestarzale]] int gethostbyname2_r(size_t bufsize; const char *restrict name, int af, struct hostent *restrict ret, char buf[restrict bufsize], size_t bufsize, struct hostent **restrict result, int *restrict h_errnop); Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)): gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r(): Od glibc 2.19: _DEFAULT_SOURCE glibc do 2.19 wlacznie: _BSD_SOURCE || _SVID_SOURCE herror(), hstrerror(): Od glibc 2.19: _DEFAULT_SOURCE glibc 2.8 do glibc 2.19: _BSD_SOURCE || _SVID_SOURCE Przed glibc 2.8: brak h_errno: Od glibc 2.19 _DEFAULT_SOURCE || _POSIX_C_SOURCE < 200809L glibc 2.12 do glibc 2.19: _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L Przed glibc 2.12: brak OPIS Funkcje gethostbyname*(), gethostbyaddr*(), herror() oraz hstrerror() sa przestarzale. Aplikacje powinny zamiast nich uzywac getaddrinfo(3), getnameinfo(3) i gai_strerror(3). Funkcja sethostent() okresla, jezeli stayopen jest prawdziwe (1), ze do odpytywania serwera nazw bedzie uzyte polaczenie TCP i to polaczenie bedzie otwarte podczas kolejnych zapytan. W przeciwnym wypadku serwer nazw bedzie odpytywany przy uzyciu datagramow UDP. Funkcja endhostent() konczy polaczenie TCP odpytywania serwera nazw. Funkcja gethostbyname() dla danego komputera name zwraca strukture typu hostent. name jest tutaj albo nazwa komputera, albo adresem IPv4 w standardowej notacji z kropkami (jak opisano w inet_addr(3)). Jezeli name jest adresem IPv4, to gethostbyname() nie wykonuje zadnych sprawdzen i po prostu kopiuje name do pola h_name oraz jej odpowiednik struct in_addr do pola h_addr_list[0] zwracanej struktury hostent. Jezeli name nie konczy sie kropka oraz ustawiono zmienna srodowiskowa HOSTALIASES, to wyszukiwanie name zacznie sie od pliku z aliasami, wskazywanego przez HOSTALIASES (format tego pliku opisany jest w hostname(7)). Biezaca domena i jej domeny nadrzedne sa przeszukiwane, chyba ze name konczy sie kropka. Funkcja gethostbyaddr() zwraca strukture typu hostent dla zadanego adresu addr o rozmiarze size i typie adresu type. Poprawnymi typami adresow sa AF_INET i AF_INET6 (zdefiniowane w ). Adres komputera jest wskaznikiem do struktury o typie zaleznym od typu adresu, na przyklad struct in_addr * (najprawdopodobniej otrzymany przez wywolanie inet_addr(3)) dla adresu o typie AF_INET. (Przestarzala) funkcja herror() wypisuje na standardowe wyjscie bledow stderr komunikat bledu przypisany do biezacej wartosci zmiennej h_errno. (Przestarzala) funkcja hstrerror() dla przekazanego numeru bledu (zazwyczaj h_errno) zwraca odpowiadajacy mu komunikat bledu. Zapytania o nazwy domenowe z gethostbyname() i gethostbyaddr() polegaja na skonfigurowanych zrodlach Name Service Switch (nsswitch.conf(5)) lub lokalnym serwerze nazw (named(8)). Domyslna akcja jest odpytanie skonfigurowanych zrodel Name Service Switch (nsswitch.conf(5), a jesli sie to nie powiedzie, lokalnego serwera nazw (named(8)). Historia Plik nsswitch.conf(5) jest wspolczesnym sposobem kontrolowania kolejnosci wyszukiwan komputerow. W glibc 2.4 i wczesniejszych, do okreslenia kolejnosci wyszukiwan komputerow sluzylo slowo kluczowe order zdefiniowane w /etc/host.conf (host.conf(5)). Struktura hostent zdefiniowana w nastepujaco: struct hostent { char *h_name; /* oficjalna nazwa komputera */ char **h_aliases; /* lista aliasow */ int h_addrtype; /* typ adresu komputera */ int h_length; /* rozmiar adresu */ char **h_addr_list; /* lista adresow */ } #define h_addr h_addr_list[0] /* dla zachowania zgodnosci */ /* z wczesniejszymi wersjami */ Struktra hostent sklada sie z: h_name Oficjalna nazwa komputera. h_aliases Zakonczona wskaznikiem null tablica alternatywnych nazw komputera. h_addrtype Typ adresu; obecnie zawsze jest to AF_INET lub AF_INET6. h_length Rozmiar adresu w bajtach. h_addr_list Zakonczona wskaznikiem null tablica adresow sieciowych komputera (w sieciowym porzadku bajtow). h_addr Pierwszy adres z h_addr_list - dla zachowania zgodnosci ze wczesniejszymi wersjami WARTOSC ZWRACANA Funkcje gethostbyname() i gethostbyaddr() zwracaja strukture hostent lub wskaznik null w przypadku bledu. W razie bledu, zmienna h_errno przechowuje numer bledu. Wartosc zwrocona, jesli jest rozna od null, moze wskazywac na statyczne dane, patrz UWAGI ponizej. BLEDY Zmienna h_errno moze przyjmowac nastepujace wartosci: HOST_NOT_FOUND Podany komputer jest nieznany. NO_DATA Zadana nazwa jest prawidlowa, lecz nie posiada adresu IP. Inny typ zadania skierowany do serwera nazw dla tej domeny moze zwrocic odpowiedz. Stala NO_ADDRESS jest synonimem NO_DATA. NO_RECOVERY Wystapil trwaly blad serwera nazw. TRY_AGAIN Autorytatywny serwer nazw zwrocil tymczasowy blad. Prosze sprobowac ponownie pozniej. PLIKI /etc/host.conf plik konfiguracyjny biblioteki resolver /etc/hosts plik bazy danych komputerow /etc/nsswitch.conf plik konfiguracyjny serwisow nazw (NSS) ATRYBUTY Informacje o pojeciach uzywanych w tym rozdziale mozna znalezc w podreczniku attributes(7). +-------------------+--------------------------+-----------------------+ |Interfejs | Atrybut | Wartosc | +-------------------+--------------------------+-----------------------+ |gethostbyname() | Bezpieczenstwo watkowe | MT-niebezpieczne | | | | race:hostbyname env | | | | locale | +-------------------+--------------------------+-----------------------+ |gethostbyaddr() | Bezpieczenstwo watkowe | MT-niebezpieczne | | | | race:hostbyaddr env | | | | locale | +-------------------+--------------------------+-----------------------+ |sethostent(), | Bezpieczenstwo watkowe | MT-niebezpieczne | |endhostent(), | | race:hostent env | |gethostent_r() | | locale | +-------------------+--------------------------+-----------------------+ |herror(), | Bezpieczenstwo watkowe | MT-bezpieczne | |hstrerror() | | | +-------------------+--------------------------+-----------------------+ |gethostent() | Bezpieczenstwo watkowe | MT-niebezpieczne | | | | race:hostent | | | | race:hostentbuf env | | | | locale | +-------------------+--------------------------+-----------------------+ |gethostbyname2() | Bezpieczenstwo watkowe | MT-niebezpieczne | | | | race:hostbyname2 env | | | | locale | +-------------------+--------------------------+-----------------------+ |gethostbyaddr_r(), | Bezpieczenstwo watkowe | MT-bezpieczne env | |gethostbyname_r(), | | locale | |gethostbyname2_r() | | | +-------------------+--------------------------+-----------------------+ W powyzszej tabeli, hostent w race:hostent oznacza, ze jesli ktoras z funkcji sethostent(), gethostent(), gethostent_r() lub endhostent() jest uzywana rownolegle w roznych watkach programu, moze nastapic sytuacja wyscigu danych. STANDARDY sethostent() endhostent() gethostent() POSIX.1-2008. gethostent_r() GNU. Pozostale: Brak. HISTORIA sethostent() endhostent() gethostent() POSIX.1-2001. gethostbyname() gethostbyaddr() h_errno Oznaczone jako wychodzace z uzycia w POSIX.1-2001. Usuniete w POSIX.1-2008, z zaleceniem stosowania w zamian getaddrinfo(3) i getnameinfo(3). UWAGI Funkcje gethostbyname() i gethostbyaddr() moga zwracac wskazniki do danych statycznych, ktore moga byc nadpisane przez kolejne wywolania. Kopiowanie struct hostent nie wystarcza, poniewaz zawiera ona wskazniki - wymagane jest skopiowanie wszystkiego. W oryginalnej implementacji BSD, argument size funkcji gethostbyname() byl typu int. Standard SUS-v2 jest bledny i okresla parametr size funkcji gethostbyaddr() jako bedacy typu size_t. (Nie jest to wlasciwe, poniewaz musi to byc typ int, ktorym size_t nie jest. POSIX.1-2001 uzywa socklen_t, co jest OK). Patrz takze accept(2). Prototyp BSD funkcji gethostbyaddr() uzywa const char * dla trzeciego argumentu. Rozszerzenie System V/POSIX POSIX wymaga, aby wywolanie gethostent() zwrocilo nastepny wpis w bazie danych komputerow. Jesli uzywany jest DNS/BIND nie ma to wiekszego sensu, ale moze byc uzasadnione, jesli baza danych komputerow jest plikiem, ktory mozna odczytac linia po linii. Wiele systemow funkcja o tej nazwie czyta plik /etc/hosts. Moze byc on dostepny tylko wtedy, gdy biblioteka zostala skompilowana bez wsparcia dla DNS-u. Wersja glibc ignoruje wpisy IPv6. Ta funkcja nie jest wielowatkowa, glibc dodaje jej wielowatkowa wersje gethostent_r(). Rozszerzenia GNU Glibc2 ma takze funkcje gethostbyname2(), ktora dziala jak gethostbyname(), ale pozwala okreslic rodzine adresow, do ktorej musi nalezec zadany adres. Glibc2 ma takze wielowatkowe wersje gethostent_r(), gethostbyaddr_r(), gethostbyname_r() i gethostbyname2_r(). Proces wywolujacy przekazuje strukture hostent w ret, ktory bedzie wypelniony, gdy funkcja zakonczy sie pomyslnie, oraz tymczasowy bufor roboczy buf o rozmiarze bufsize. Po pomyslnym wywolaniu, result bedzie wskazywal na wynik. W razie bledu lub gdy nie znaleziono zadnego wpisu result bedzie ustawiony na NULL. Funkcje zwracaja one 0 w przypadku powodzenia lub liczbe rozna od zera w razie bledu. Oprocz bledow, ktore moga zwrocic niewielowatkowe wersje tych funkcji, funkcje moga zwroc blad RANGE, jesli buf jest za maly - w takim wypadku nalezy powtorzyc wywolanie funkcji z wiekszym buforem. Globalna zmienna h_errno nie jest modyfikowana, ale numer bledu jest przekazywany w zmiennej, ktorej adres zostal podany w h_errnop. USTERKI gethostbyname() nie rozpoznaje komponentow oddzielonego kropkami lancucha adresu IPv4, jesli sa one wyrazone jako liczby szesnastkowe. ZOBACZ TAKZE getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3), resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8) TLUMACZENIE Tlumaczenie niniejszej strony podrecznika: Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.18 8 lutego 2026 r. gethostbyname(3)