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)