gethostbyname

GETHOSTBYNAME(3)         Podręcznik programisty Linuksa         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

SKŁADNIA
       #include <netdb.h>
       extern int h_errno;

       struct hostent *gethostbyname(const char *nazwa);

       #include <sys/socket.h>       /* dla AF_INET */
       struct hostent *gethostbyaddr(const void *addr,
                                     socklen_t len, int type);

       void sethostent(int stayopen);

       void endhostent(void);

       void herror(const char *s);

       const char *hstrerror(int err);

       /* Rozszerzenie systemu V/POSIX */
       struct hostent *gethostent(void);

       /* Rozszerzenia GNU */
       struct hostent *gethostbyname2(const char *name, int af);

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

       int gethostbyaddr_r(const void *addr, socklen_t len, int type,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyname_r(const char *name,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *h_errnop);

       int gethostbyname2_r(const char *name, int af,
               struct hostent *ret, char *buf, size_t buflen,
               struct hostent **result, int *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 w wersji do 2.19 włącznie:
               _BSD_SOURCE || _SVID_SOURCE

       herror(), hstrerror():
           Od glibc 2.19:
               _DEFAULT_SOURCE
           Glibc 2.8 do 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 2.19:
               _BSD_SOURCE || _SVID_SOURCE || _POSIX_C_SOURCE < 200809L
           Przed glibc 2.12:
               brak

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 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ą.

       Funkcja gethostbyaddr() zwraca strukturę typu hostent dla zadanego adresu
       addr o długości len i typie adresu type. Poprawnymi typami adresów
       są AF_INET i AF_INET6. Adres komputera jest wskaźnikiem do struktury o
       typie zależnym od typu adresu, na przykład struct in_addr *
       (najprawdopodobniej otrzymany przez wywołanie inet_addr(3)) dla adresu o
       typie AF_INET.

       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.

       (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.

       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)).

   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    │
       │endhostent(),      │                        │ locale                        │
       │gethostent_r()     │                        │                               │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │herror(),          │ Bezpieczeństwo wątkowe │ MT-Safe                       │
       │hstrerror()        │                        │                               │
       ├───────────────────┼────────────────────────┼───────────────────────────────┤
       │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.

ZGODNE Z
       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)

O STRONIE
       Angielska wersja tej strony pochodzi z wydania 5.08 projektu Linux
       man-pages. Opis projektu, informacje dotyczące zgłaszania błędów oraz
       najnowszą wersję oryginału można znaleźć pod adresem
       https://www.kernel.org/doc/man-pages/.


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 lub nowszej. Nie przyjmuje się ŻADNEJ
       ODPOWIEDZIALNOŚCI.

       Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres
       <manpages-pl-list@lists.sourceforge.net>.



                                9 czerwca 2020 r.               GETHOSTBYNAME(3)