table of contents
GETHOSTBYNAME(3) | Linux - příručka programátora | GETHOSTBYNAME(3) |
JMÉNO¶
gethostbyname, gethostbyaddr, sethostent, gethostend, endhostent, h_errno, herror, hstrerror, gethostbyaddr_r, gethostbyname2, gethostbyname2_r, gethostbyname_r, gethostent_r, - zjistí záznam z databáze počítačů
SYNTAXE¶
#include <netdb.h> extern int h_errno; struct hostent *gethostbyname(const char *name); #include <sys/socket.h> /*AF_INET*/ struct hostent *gethostbyaddr(const char *addr, int len, int type); void sethostent(int stayopen); void endhostent(void); void herror(const char *s); const char *hstrerror(int err); /*rozšíření System V/POSIX*/ struct hostent *gethostent(void); /*rozšíření GNU*/ struct hostent *gethostbyname2(const char *name, int af);
- int gethostend_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);
Vyžaduje Feature Test Makro pro glibc (viz feature_test_macros(7)): gethostbyname2(), gethostent_r(), gethostbyaddr_r(), gethostbyname_r(), gethostbyname2_r(): _BSD_SOURCE || _SVID_SOURCE
POPIS¶
Funkce gethostbyname*() a gethostbyaddr*() jsou zastaralé. V programech by měly být nahrazeny funkcemi getaddrinfo(3) a getnameinfo(3).
Funkce gethostbyname() vrací strukturu typu hostent pro zadaný počítač name. V poli name může být buď hostaname nebo IPv4 adresa v klasické tečkové notaci (jako v inet_addr(3)), případně IPv6 adresa v dvojtečkové (případně v tečkové) notaci. (Více informací o formátu IPv6 adres lze nalézt v RFC 1884.) Je-li jméno IPv4 nebo IPv6 adresa není prováděno žádné hledání a gethostbyname() jednoduše zkopíruje name do pole h_name a strukturu struct in_addr do pole h_addr_list[0] ve vracené struktuře hostent. Doména počítače a jí nadřazené jsou prohledávány pouze tehdy, nekončí-li name tečkou. Pokud name nekončí tečkou a proměnná prostředí HOSTALIASES je nastavena, bude prvně prohledáván soubor, na který ukazuje proměnná HOSTALIASES.
Funkce gethostbyaddr() vrací strukturu typu hostent pro počítač, jehož adresa addr (délky len a typu type) byla zadána. Platné typy adres jsou AF_INET a AF_INET6. Parametr adresa hosta je ukazatel do struktury jejíž typ závisí na druhu adresy. Například struct in_addr * (zřejmě získáno skrze volání inet_addr(3)) pro adresy typu AF_INET.
Funkce sethostent() specifikuje, je-li stayopen pravdivé (1), že k dotazování budou použity spojené TCP sokety a spojení zůstane mezi jednotlivými dotazy otevřeno. Jinak budou k dotazování použity UDP datagramy.
Funkce endhostent() ukončí TCP spojení pro dotazy na nameserver.
Funkce herror() vytiskne chybovou zprávu, která přísluší hodnotě proměnné h_errno.
Zastaralá funkce hsterror() vezme číslo chyby (obvykle h_errno) a vrátí odpovídající řetězec.
Funkce gethostbyname() a gethostbyaddr() používají při své činnosti jak nameservery named(8), tak soubor /etc/hosts, ale samozřejmě i NIS nebo YP, to záleží na pořadí definovaném v /etc/host.conf. (Viz resolv+(8)). Standardně je prvně dotazován named(8) a potom soubor /etc/hosts.
Struktura hostent je definována v <netdb.h> následovně:
struct hostent {
char *h_name; /* official name of host */
char **h_aliases; /* alias list */
int h_addrtype; /* host address type */
int h_length; /* length of address */
char **h_addr_list; /* list of addresses */ } #define h_addr h_addr_list[0] /* for backward compatibility */
Prvky struktury hostent jsou:
- h_name
- Oficiální jméno počítače.
- h_aliases
- Nulou ukončené pole alternativních jmen počítačů.
- h_addrtype
- Typ adres, v současné době vždy AF_INET.
- h_length
- Délka adresy v bajtech.
- h_addr_list
- Nulou ukončené pole síťových adres počítače v síťovém pořadí dat.
- h_addr
- První adresa v h_addr_list kvůli zpětné kompatibilitě.
NÁVRATOVÁ HODNOTA¶
Funkce gethostbyname() a gethostbyaddr() vrací strukturu hostent nebo ukazatel NULL v případě výskytu chyby. Potom je nastavena proměnná h_errno. Pokud je návratová hodnota not-NULL pak zřejmě návratová hodnota odkazuje na statická data. Více informací v poznámkách níže.
ROZEZNÁVANÉ CHYBY¶
Proměnná h_errno může obsahovat následující hodnoty:
- HOST_NOT_FOUND
- Specifikovaný počítač je neznámý.
- NO_ADDRESS nebo NO_DATA
- Jméno je platné, ale nemá žádnou IP adresu.
- NO_RECOVERY
- Došlo k výskytu neodstranitelné chyby nameserveru.
- TRY_AGAIN
- Došlo k dočasné chybě autoritativního nameserveru. Zkuste později.
SOUBORY¶
- /etc/host.conf
- konfigurační soubor resolveru.
- /etc/hosts
- databáze počítačů.
- /etc/nsswitch.conf
- konfigurační soubor pro výběr jmenné služby
POZNÁMKY¶
Funkce gethostbyname() a gethostbyaddr() mohou vracet ukazatele na statická data. Tyto ukazatele mohou být přepsány pozdějším voláním. Zkopírování hodnoty do struct hostent není dostatečné, protože obsahuje ukazatele.
V originálních BSD implementacích měl parametr len funkce gethostbyname() typ int. Standard SUSv2 je chybový a deklaruje parametr len funkce gethostbyaddr() jako typ size_t. (Což je špatně, protože musí být typu int a ne size_t. Norma POSIX.1-2001 mu přiřazuje typ socklen_t
U BSD prototypu funkce gethostbyaddr() je první argument typu const char *.
Norma POSIX.1-2001 označila funkce gethostbyaddr() a gethostbyname() za zastaralé. Viz getaddrinfo(3), getnameinfo(3), gai_sterror(3).
System V/POSIX rozšíření
POSIX vyžaduje, aby volání gethostent() vracelo
další záznam z hostitelské databáze.
Pokud používáme DNS/BIND tak to nedává
moc smysl, nicméně může to být
užitečné, pokud hostitelská databáze
obsahuje soubory, které mohou být čteny po
řádcích. Na mnoha systémech čte tato
funkce ze souboru /etc/hosts. Funkce může být
dostupná pouze pokud byla knihovna přeložena bez
podpory DNS. Glibc verze ignoruje IPv6 záznamy. Tato funkce
není reentrantní. Glibc proto přidává
reentrantní verzi gethostent_r().
GNU rozšíření
Glibc2 zavádí také funkci gethostbyname2()
která pracuje stejně jako funkce gethostbyname(), ale
umožňuje specifikaci rodiny do níž musí
adresa spadat.
Glibc2 zavádí reentrantní funkce gethostent_r(), gethostbyaddr_r(), gethostbyname_r() a gethostbynbame2_r(). Volající musí poskytnout hostent strukturu ret, která bude v případě úspěchu naplněna, a dočasný pracovní buffer buf o velikosti buflen. Po skončení funkce bude result obsahovat ukazatel na výsledek v případě úspěšného volání. V případě chyby nebo když není nalezen žádný záznam je result NULL. Tato funkce vrací v případě úspěchu 0 a nenulovou hodnotu při v případě chyby. V návaznosti na chyby vracené nereentrantními verzemi je vrácena chyba ERANGE v případě, že je poskytnutý buffer buf příliš malý. Volání by pak mělo být realizováno s větším množstvím paměti. Globální proměnná h_errno není změněna, ale adresa proměnné do které se ukládají čísla chyb je předána h_errnop.
CHYBY¶
Funkce gethostbyname() nerozeznává části IPv4 adresy, které jsou zadané v tečkové konvenci hexadecimálně.
SPLŇUJE STANDARDY¶
BSD 4.3
DALŠÍ INFORMACE¶
getaddrinfo(3), getnameinfo(3), inet(3), inet_ntop(3) inet_pton()3 resolver(3), hosts(5), nsswitch.conf(5), hostname(7), named(8)
TIRÁŽ¶
Tato stránka je součástí projektu Linux man-pages. Popis projektu a informace o hlášení chyb najdete na http://www.kernel.org/doc/man-pages/.
5. listopadu 2009 | BSD |