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); [[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); /* Rozszerzenie systemu 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); Wymagane ustawienia makr biblioteki glibc (patrz 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 OPIS Funkcje gethostbyname*(), gethostbyaddr*(), herror() oraz hstrerror() sa przestarzale. Aplikacje powinny zamiast nich uzywacgetaddrinfo(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. 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 ). 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. (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; /* dlugosc 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 Dlugosc 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-Unsafe | | | | race:hostbyname env | | | | locale | +-------------------+--------------------------+-----------------------+ |gethostbyaddr() | Bezpieczenstwo watkowe | MT-Unsafe | | | | race:hostbyaddr env | | | | locale | +-------------------+--------------------------+-----------------------+ |sethostent(), | Bezpieczenstwo watkowe | MT-Unsafe | |endhostent(), | | race:hostent env | |gethostent_r() | | locale | +-------------------+--------------------------+-----------------------+ |herror(), | Bezpieczenstwo watkowe | MT-bezpieczne | |hstrerror() | | | +-------------------+--------------------------+-----------------------+ |gethostent() | Bezpieczenstwo watkowe | MT-Unsafe | | | | race:hostent | | | | race:hostentbuf env | | | | locale | +-------------------+--------------------------+-----------------------+ |gethostbyname2() | Bezpieczenstwo watkowe | MT-Unsafe | | | | race:hostbyname2 env | | | | locale | +-------------------+--------------------------+-----------------------+ |gethostbyaddr_r(), | Bezpieczenstwo watkowe | MT-bezpieczne env | |gethostbyname_r(), | | locale | |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. STANDARDY sethostent() endhostent() gethostent() POSIX.1-2008. gethostent_r() GNU. Others: None. HISTORIA 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. 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 len funkcji gethostbyname() byl typu int. Standard SUS-v2 jest bledny i okresla parametr len 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 buflen. 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 Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: 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.06 31 pazdziernika 2023 r. gethostbyname(3)