Provided by: manpages-pl-dev_4.18.1-1_all 
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)
SKŁADNIA
#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);
/* 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() są przestarzałe.
Aplikacje powinny zamiast nich używaćgetaddrinfo(3), getnameinfo(3) i gai_strerror(3).
Funkcja sethostent() określa, jeżeli stayopen jest prawdziwe (1), że do odpytywania
serwera nazw będzie użyte połączenie TCP i to połączenie będzie otwarte podczas kolejnych
zapytań. W przeciwnym wypadku serwer nazw będzie odpytywany przy użyciu datagramów UDP.
Funkcja endhostent() kończy połączenie TCP odpytywania serwera nazw.
Funkcja gethostbyname() dla danego komputera name zwraca strukturę typu hostent. name jest
tutaj albo nazwą komputera, albo adresem IPv4 w standardowej notacji z kropkami (jak
opisano w inet_addr(3)). Jeżeli name jest adresem IPv4, to gethostbyname() nie wykonuje
żadnych sprawdzeń i po prostu kopiuje name do pola h_name oraz jej odpowiednik struct
in_addr do pola h_addr_list[0] zwracanej struktury hostent. Jeżeli name nie kończy się
kropką oraz ustawiono zmienną środowiskową HOSTALIASES, to wyszukiwanie name zacznie się
od pliku z aliasami, wskazywanego przez HOSTALIASES (format tego pliku opisany jest w
hostname(7)). Bieżąca domena i jej domeny nadrzędne są przeszukiwane, chyba że name kończy
się kropką.
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.
(Przestarzała) funkcja herror() wypisuje na standardowe wyjście błędów stderr komunikat
błędu przypisany do bieżącej wartości zmiennej h_errno.
(Przestarzała) funkcja hstrerror() dla przekazanego numeru błędu (zazwyczaj h_errno)
zwraca odpowiadający mu komunikat błędu.
Zapytania o nazwy domenowe z gethostbyname() i gethostbyaddr() polegają na
skonfigurowanych źródłach Name Service Switch (nsswitch.conf(5)) lub lokalnym serwerze
nazw (named(8)). Domyślną akcją jest odpytanie skonfigurowanych źródeł Name Service Switch
(nsswitch.conf(5), a jeśli się to nie powiedzie, lokalnego serwera nazw (named(8)).
Historia
Plik nsswitch.conf(5) jest współczesnym sposobem kontrolowania kolejności wyszukiwań
komputerów.
W glibc 2.4 i wcześniejszych, do określenia kolejności wyszukiwań komputerów służyło słowo
kluczowe order zdefiniowane w /etc/host.conf (host.conf(5)).
Struktura hostent zdefiniowana w <netdb.h> następująco:
struct hostent {
char *h_name; /* oficjalna nazwa komputera */
char **h_aliases; /* lista aliasów */
int h_addrtype; /* typ adresu komputera */
int h_length; /* długość adresu */
char **h_addr_list; /* lista adresów */
}
#define h_addr h_addr_list[0] /* dla zachowania zgodności */
/* z wcześniejszymi wersjami */
Struktra hostent składa się z:
h_name Oficjalna nazwa komputera.
h_aliases
Zakończona wskaźnikiem null tablica alternatywnych nazw komputera.
h_addrtype
Typ adresu; obecnie zawsze jest to AF_INET lub AF_INET6.
h_length
Długość adresu w bajtach.
h_addr_list
Zakończona wskaźnikiem null tablica adresów sieciowych komputera (w sieciowym
porządku bajtów).
h_addr Pierwszy adres z h_addr_list - dla zachowania zgodności ze wcześniejszymi wersjami
WARTOŚĆ ZWRACANA
Funkcje gethostbyname() i gethostbyaddr() zwracają strukturę hostent lub wskaźnik null w
przypadku błędu. W razie błędu, zmienna h_errno przechowuje numer błędu. Wartość zwrócona,
jeśli jest różna od null, może wskazywać na statyczne dane, patrz UWAGI poniżej.
BŁĘDY
Zmienna h_errno może przyjmować następujące wartości:
HOST_NOT_FOUND
Podany komputer jest nieznany.
NO_DATA
Żądana nazwa jest prawidłowa, lecz nie posiada adresu IP. Inny typ żądania
skierowany do serwera nazw dla tej domeny może zwrócić odpowiedź. Stała NO_ADDRESS
jest synonimem NO_DATA.
NO_RECOVERY
Wystąpił trwały błąd serwera nazw.
TRY_AGAIN
Autorytatywny serwer nazw zwrócił tymczasowy błąd. Proszę spróbować ponownie
później.
PLIKI
/etc/host.conf
plik konfiguracyjny biblioteki resolver
/etc/hosts
plik bazy danych komputerów
/etc/nsswitch.conf
plik konfiguracyjny serwisów nazw (NSS)
ATRYBUTY
Informacje o pojęciach używanych w tym rozdziale można znaleźć w podręczniku
attributes(7).
┌──────────────────────┬────────────────────────┬─────────────────────────────────────────┐
│Interfejs │ Atrybut │ Wartość │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│gethostbyname() │ Bezpieczeństwo wątkowe │ MT-Unsafe race:hostbyname env locale │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│gethostbyaddr() │ Bezpieczeństwo wątkowe │ MT-Unsafe race:hostbyaddr env locale │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│sethostent(), │ Bezpieczeństwo wątkowe │ MT-Unsafe race:hostent env locale │
│endhostent(), │ │ │
│gethostent_r() │ │ │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│herror(), hstrerror() │ Bezpieczeństwo wątkowe │ MT-Safe │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│gethostent() │ Bezpieczeństwo wątkowe │ MT-Unsafe race:hostent race:hostentbuf │
│ │ │ env locale │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│gethostbyname2() │ Bezpieczeństwo wątkowe │ MT-Unsafe race:hostbyname2 env locale │
├──────────────────────┼────────────────────────┼─────────────────────────────────────────┤
│gethostbyaddr_r(), │ Bezpieczeństwo wątkowe │ MT-Safe env locale │
│gethostbyname_r(), │ │ │
│gethostbyname2_r() │ │ │
└──────────────────────┴────────────────────────┴─────────────────────────────────────────┘
W powyższej tabeli, hostent w race:hostent oznacza, że jeśli któraś z funkcji
sethostent(), gethostent(), gethostent_r() lub endhostent() jest używana równolegle w
różnych wątkach programu, może nastąpić sytuacja wyścigu danych.
STANDARDY
POSIX.1-2001 definiuje gethostbyname(), gethostbyaddr(), sethostent(), endhostent(),
gethostent() i h_errno; gethostbyname(), gethostbyaddr() i h_errno są oznaczone jako
starzejące się. POSIX.1-2008 usuwa definicje gethostbyname(), gethostbyaddr() oraz
h_errno, zalecając używanie zamiast nich funkcjigetaddrinfo(3) i getnameinfo(3).
UWAGI
Funkcje gethostbyname() i gethostbyaddr() mogą zwracać wskaźniki do danych statycznych,
które mogą być nadpisane przez kolejne wywołania. Kopiowanie struct hostent nie wystarcza,
ponieważ zawiera ona wskaźniki - wymagane jest skopiowanie wszystkiego.
W oryginalnej implementacji BSD, argument len funkcji gethostbyname() był typu int.
Standard SUS-v2 jest błędny i określa parametr len funkcji gethostbyaddr() jako będący
typu size_t. (Nie jest to właściwe, ponieważ musi to być typ int, którym size_t nie jest.
POSIX.1-2001 używa socklen_t, co jest OK). Patrz także accept(2).
Prototyp BSD funkcji gethostbyaddr() używa const char * dla trzeciego argumentu.
Rozszerzenie System V/POSIX
POSIX wymaga, aby wywołanie gethostent() zwróciło następny wpis w bazie danych komputerów.
Jeśli używany jest DNS/BIND nie ma to większego sensu, ale może być uzasadnione, jeśli
baza danych komputerów jest plikiem, który można odczytać linia po linii. Wiele systemów
funkcja o tej nazwie czyta plik /etc/hosts. Może być on dostępny tylko wtedy, gdy
biblioteka została skompilowana bez wsparcia dla DNS-u. Wersja glibc ignoruje wpisy IPv6.
Ta funkcja nie jest wielowątkowa, glibc dodaje jej wielowątkową wersję gethostent_r().
Rozszerzenia GNU
Glibc2 ma także funkcję gethostbyname2(), która działa jak gethostbyname(), ale pozwala
określić rodzinę adresów, do której musi należeć zadany adres.
Glibc2 ma także wielowątkowe wersje gethostent_r(), gethostbyaddr_r(), gethostbyname_r() i
gethostbyname2_r(). Proces wywołujący przekazuje strukturę hostent w ret, który będzie
wypełniony, gdy funkcja zakończy się pomyślnie, oraz tymczasowy bufor roboczy buf o
rozmiarze buflen. Po pomyślnym wywołaniu, result będzie wskazywał na wynik. W razie błędu
lub gdy nie znaleziono żadnego wpisu result będzie ustawiony na NULL. Funkcje zwracają one
0 w przypadku powodzenia lub liczbę różną od zera w razie błędu. Oprócz błędów, które mogą
zwrócić niewielowątkowe wersje tych funkcji, funkcje mogą zwróć błąd RANGE, jeśli buf jest
za mały - w takim wypadku należy powtórzyć wywołanie funkcji z większym buforem. Globalna
zmienna h_errno nie jest modyfikowana, ale numer błędu jest przekazywany w zmiennej,
której adres został podany w h_errnop.
BŁĘDY
gethostbyname() nie rozpoznaje komponentów oddzielonego kropkami łańcucha adresu IPv4,
jeśli są one wyrażone jako liczby szesnastkowe.
ZOBACZ TAKŻE
getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3), inet_pton(3), resolver(3),
hosts(5), nsswitch.conf(5), hostname(7), named(8)
TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Robert Luberda
<robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>
Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji
można uzyskać zapoznając się z GNU General Public License w wersji 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ lub nowszej. Nie przyjmuje się ŻADNEJ
ODPOWIEDZIALNOŚCI.
Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej
⟨manpages-pl-list@lists.sourceforge.net⟩.