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/.
