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¶
Uwaga! To tłumaczenie może być nieaktualne!
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)
Powyższe tłumaczenie pochodzi z nieistniejącego już
Projektu Tłumaczenia Manuali i
może nie być
aktualne. W razie zauważenia różnic między
powyższym opisem a rzeczywistym zachowaniem opisywanego programu lub
funkcji, prosimy o zapoznanie się z oryginalną
(angielską) wersją strony podręcznika za pomocą
polecenia:
- man --locale=C 3 getaddrinfo
Prosimy o pomoc w aktualizacji stron man - więcej informacji można
znaleźć pod adresem
http://sourceforge.net/projects/manpages-pl/.