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 System V/POSIX */
struct hostent *gethostent(void);

/* rozszerzenia GNU */
struct hostent *gethostbyname2(const char *nazwa, 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():
    _BSD_SOURCE || _SVID_SOURCE
herror(), hstrerror():
    Od glibc 2.8:
        _BSD_SOURCE || _SVID_SOURCE
    Przed glibc 2.8:
        brak
h_errno:
    Od glibc 2.12:
        _BSD_SOURCE || _SVID_SOURCE ||
            (_POSIX_C_SOURCE < 200809L && _XOPEN_SOURCE < 700)
    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)), albo adresem IPv6 w notacji ze średnikami (i być może kropkami). (Proszę przeczytać RFC 1984, aby uzyskać opis adresów IPv6). Jeżeli name jest adresem IPv4 lub IPv6, 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.

Funkcje gethostbyname() i gethostbyaddr() używają do odpytywania serwera kombinacji któregokolwiek bądź wszystkich serwerów nazw named(8), poszczególnych linii z /etc/hosts oraz Systemu Informacji Sieciowej (Network Information Service - NIS lub YP), w zależności od zawartości linii order w pliku /etc/host.conf. Domyślnie najpierw odpytywane są serwery named(8), a następnie przeglądany jest /etc/hosts.

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_ADDRESS lub NO_DATA
    Żądana nazwa jest poprawna, ale nie ma adresu IP.

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)

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 3.71 projektu Linux man-pages. Opis projektu, informacje dotyczące zgłaszania błędów, oraz najnowszą wersję oryginału można znaleźć pod adresem http://www.kernel.org/doc/man-pages/.

TŁUMACZENIE
Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Robert Luberda <robert@debian.org> i Michał Kułach <michal.kulach@gmail.com>.

Polskie tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów na stronie http://sourceforge.net/projects/manpages-pl/. Jest zgodne z wersją 3.71 oryginału.