Linux Certif

Toute la documentation sur la certification Linux LPI

getaddrinfo

NAZWA

getaddrinfo - t³umaczenie adresów i us³ug sieciowych

SK£ADNIA

#include <sys/types.h>

#include <sys/socket.h>

#include <netdb.h>



int getaddrinfo(const char *node, const char *service,

                const struct addrinfo *hints,

                struct addrinfo **res);



void freeaddrinfo(struct addrinfo *res);



const char *gai_strerror(int errcode);

OPIS

Funkcja getaddrinfo(3) ³±czy w pojedynczym interfejsie funkcjonalno¶æ udostêpnian± przez funkcje getipnodebyname(3), getipnodebyaddr(3), getservbyname (3) i getservbyport(3). Przystosowana do wielow±tkowo¶ci funkcja getaddrinfo(3) tworzy jedn± lub wiêcej struktur adresowych gniazda, które mog± byæ wykorzystane przez funkcje systemowe bind(2) i connect(2) do utworzenia gniazda klienta lub serwera.

Funkcja getaddrinfo(3) nie jest ograniczona do tworzenia struktur adresowych gniazd IPv4. Gniazda IPv6 mog± równie¿ byæ tworzone za jej pomoc±, o ile dostêpne jest wspomaganie dla IPv6. Te struktury adresowe gniazd mog± byæ bezpo¶rednio wykorzystane przez bind(2) i connect(2) do sporz±dzenia gniazda klienta lub serwera.

Struktura addrinfo u¿ywana przez tê funkcjê zawiera nastêpuj±ce pola:

struct addrinfo {

    int     ai_flags;

    int     ai_family;

    int     ai_socktype;

    int     ai_protocol;

    size_t  ai_addrlen;

    struct sockaddr *ai_addr;

    char   *ai_canonname;

    struct addrinfo *ai_next;

};

getaddrinfo(3) ustawia res, aby wskazywa³o na dynamicznie zaalokowan± listê struktur addrinfo, dowi±zan± do pola ai_next. Istnieje kilka powodów, dla których lista mo¿e zawieraæ wiêcej ni¿ jedn± strukturê addrinfo, w³±czaj±c w to: posiadanie przez host wielu interfejsów sieciowych oraz dostêpno¶æ tej samej us³ugi poprzez wiele protoko³ów gniazda (na przyk³ad, gdy jednym z nich jest SOCK_STREAM, a innym SOCK_DGRAM).

Pola ai_family, ai_socktype i ai_protocol maj± to samo znaczenie jako odpowiednie parametry wywo³ania systemowego socket(2). Funkcja getaddrinfo(3) zwraca adresy gniazd IPv4 lub IPv6 (ai_family zostanie ustawione albo na PF_INET albo na PF_INET6).

Parametr hints okre¶la preferowany rodzaj gniazda lub protokó³. Warto¶æ NULL dla hints okre¶la, ¿e akceptowany jest dowolny adres sieciowy lub protokó³. Je¶li parametr ten ma warto¶æ ró¿n± od NULL, wskazuje on na strukturê addrinfo, w której pola ai_family, ai_socktype i ai_protocol okre¶laj± preferowany rodzaj gniazda. PF_UNSPEC w ai_family okre¶la dowoln± rodzinê protoko³ów (na przyk³ad IPv4 lub IPv6). 0 w ai_socktype lub ai_protocol stwierdza, ¿e akceptowalny jest równie¿ dowolny rodzaj gniazda lub protokó³. Pole ai_flags zawiera dodatkowe, zdefiniowane poni¿ej, opcje. Wiele znaczników podaje siê jako ich logiczne OR. Wszystkie pozosta³e pola parametru hints musz± zawieraæ albo 0 albo wska¼nik NULL.

Parametry node i service mog± byæ równe NULL, ale nie oba naraz. node zawiera albo adres sieciowy w postaci numerycznej (w formacie dziesiêtnych liczb rozdzielonych kropkami dla IPv4, a w formacie szesnastkowym dla IPv6) albo nazwê hosta, dla której adresy sieciowe bêd± poszukiwane i rozwi±zane. Je¶li pole ai_flags parametru hints zawiera znacznik AI_NUMERICHOST, to parametr node musi byæ adresem sieciowym w postaci numerycznej. Znacznik AI_NUMERICHOST eliminuje jakiekolwiek, potencjalnie d³ugotrwa³e, poszukiwania adresu sieciowego hosta.

Funkcja getaddrinfo(3) tworzy listê struktur addrinfo, po jednej dla ka¿dej podstawy ograniczenia adresów sieciowych narzuconej przez parametr hints. Gdy ai_flags w hints zawiera znacznik AI_CANONNAME, to ai_canonname jest ustawiane tak, aby wskazywa³o na oficjaln± nazwê hosta. ai_family, ai_socktype i ai_protocol zawieraj± parametry tworzenia gniazda. Wska¼nik do adresu gniazda jest umieszczany w polu ai_addr, a d³ugo¶æ adresu gniazda w bajtach jest umieszczana w polu ai_addrlen.

Gdy node jest równe NULL, inicjalizacja adresu sieciowego w ka¿dej ze struktur gniazda zale¿y od znacznika AI_PASSIVE, który jest ustawiany w polu ai_flags parametru hints. Gdy znacznik AI_PASSIVE jest ustawiony, to adres sieciowy w ka¿dej ze struktur gniazda pozostanie nieokre¶lony. Jest to wykorzystywane przez programy serwerów, które zamierzaj± przyjmowaæ po³±czenia od klientów na dowolny adres sieciowy. Gdy znacznik AI_PASSIVE nie jest ustawiony, to adres sieciowy zostanie ustawiony na adres interfejsu loopback. Jest to wykorzystywane przez programy klienckie, które zamierzaj± po³±czyæ siê z serwerem dzia³aj±cym na tym samym ho¶cie.

service ustawia numer portu w adresie sieciowym ka¿dej ze struktur gniazda. Je¶li service jest ró¿ne od NULL, to numer portu pozostanie niezainicjalizowany.

Funkcja freeaddrinfo(3) zwalnia pamiêæ przydzielon± dla dynamicznie zaalokowanej listy res.

WARTO¦Æ ZWRACANA

getaddrinfo(3) zwraca 0, gdy zakoñczy siê pomy¶lnie, a w przeciwnym razie jeden z nastêpuj±cych niezerowych kodów b³êdów:

EAI_FAMILY

Zupe³ny brak wsparcia dla ¿±danej rodziny adresów.

EAI_SOCKTYPE

Zupe³ny brak wsparcia dla ¿±danego rodzaju gniazda.

EAI_BADFLAGS

ai_flags zawiera nieprawid³owe znaczniki.

EAI_NONAME

node lub service jes nieznane. Ten b³±d jest równie¿ zwracany, gdy zarówno node, jak i service s± równe NULL.

EAI_SERVICE

¯±dana us³uga nie jest dostêpna dla zadanego rodzaju gniazda. Mo¿e ona jednak byæ dostêpna dla innego rodzaju gniazda.

EAI_ADDRFAMILY

Podany host nie posiada ¿adnego adresu sieciowego dla zadanej rodziny adresów.

EAI_NODATA

Podany host istnieje, ale nie zdefiniowano dla niego ¿adnego adresu sieciowego.

EAI_MEMORY

Brak pamiêci.

EAI_FAIL

Serwer nazw zwróci³ b³±d trwa³y.

EAI_AGAIN

Serwer nazw zwróci³ b³±d tymczasowy. Nale¿y spróbowaæ pó¼niej.

EAI_SYSTEM

Inny b³±d systemowy; szczegó³owe informacje zawarte s± w errno.

Funkcja gai_strerror(3) t³umaczy te kody b³êdów na czytelny dla cz³owieka napis, odpowiedni dla zg³aszania b³êdów.

ZOBACZ TAK¯E

getipnodebyname(3), getipnodebyaddr(3)