Linux Certif

Toute la documentation sur la certification Linux LPI

gethostbyname

NAZWA

gethostbyname, gethostbyaddr, sethostent, endhostent, herror, hstrerror - zwróæ 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 char *adres,

  int dlug, int typ);



void sethostent(int stayopen);



void endhostent(void);



void herror(const char *s);



const char *hstrerror(int err);



/* rozszerzenia GNU */




struct hostent *gethostbyname2(const char *nazwa, int af);



int gethostbyname_r (const char *nazwa,

  struct hostent *ret, char *buf, size_t buflen,

  struct hostent **result, int *h_errnop);



int gethostbyname2_r (const char *nazwa, int af,

  struct hostent *ret, char *buf, size_t buflen,

  struct hostent **result, int *h_errnop);

OPIS

Funkcja gethostbyname() dla danego komputera nazwa zwraca strukturê typu hostent. Nazwa jest tutaj albo nazw± komputera, albo adresem IPv4 w standardowej notacji z kropkami, albo adresem IPv6 w notacji ze ¶rednikami (i byæ mo¿e kropkami). (Proszê przeczytaæ RFC 1984, aby uzyskaæ opis adresów IPv6). Je¿eli nazwa jest adresem Ipv4 lub IPv6, to gethostbyname() nie wykonuje ¿adnych sprawdzeñ i po prostu kopiuje nazwê do pola h_name oraz jej odpowiednik struct in_addr do pola h_addr_list[0] zwracanej struktury hostent. Je¿eli nazwa nie koñczy siê kropk± oraz ustawiono zmienn± ¶rodowiskow± HOSTALIASES, to wyszukiwanie nazwy zacznie siê od pliku z aliasami, wskazywanego przez HOSTALIASES. (format tego pliku opisany jest w hostname(7)). Bie¿±ca domenta i jej domeny nadrzêdne s± przeszukiwane, chyba ¿e nazwa koñczy siê kropk±.

Funkcja gethostbyaddr() zwraca strukturê typu hostent dla zadanego adresu adres o d³ugo¶ci dlug i typie adresu typ. Obecnie jedynym poprawnym typem adresu jest 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 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), wydzielonych 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. (Proszê przeczytaæ resolv+(8)). 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 zerem tablica alternatywnych nazw komputera.

h_addrtype

Typ adresu; obecnie zawsze jest to AF_INET.

h_length

D³ugo¶æ adresu w bajtach.

h_addr_list

Zakoñczona zerem tablica adresów sieciowych komputera w sieciowym porz±dku bajtów (network byte order).

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.

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 resolver configuration file

/etc/hosts

plik bazy danych komputerów

ZGODNE Z

BSD 4.3.

UWAGI

Standard SUS-v2 jest b³êdny i okre¶la parametr len funkcji gethostbyaddr() jako maj±cy typ size_t. (No nie jest w³a¶ciwe, poniewa¿ musi to byæ typ int, którym size_t nie jest. POSIX 1003.1-2001 u¿ywa socklen_t, co jest OK)

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.

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 gethostbyname_r() i gethostbyname2_r(). Zwracaj± one 0 w przypadku powodzenia i niezero w razie b³êdu. Wynik funkcji jest przechowywany w strukturze o adresie ret. Po wywo³aniu funkcji *result bêdzie NULL w razie b³êdu albo wska¼nikiem do wyniku, gdy funkcja zakoñczy siê powodzeniem. Pomocnicze dane s± przechowywane w buforze buf o d³ugo¶ci buflen. (Je¿eli bufor jest za ma³y, to funkcje te zwróc± ERANGE.) Globalna zmienna h_errno nie jest modyfikowana, ale numer b³êdu jest przekazywany w zmiennej, której adres zosta³ podany w h_errnop.

POSIX 1003.1-2001 traktuje gethostbyaddr() i gethostbyname() jako spu¶ciznê i wprowadza

struct hostent *getipnodebyaddr (const void *restrict addr,

  socklen_t len, int type, int *restrict error_num);



struct hostent *getipnodebyname (const char *name,

  int type, int flags, int *error_num);

 

ZOBACZ TAK¯E

resolver(3), hosts(5), hostname(7), resolv+(8), named(8)