Ubuntu Manpage: getaddrinfo - tłumaczenie adresów i usług sieciowych

nazwa
składnia
opis
wartość zwracana
zobacz także
informacje o tłumaczeniu

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)

INFORMACJE O TŁUMACZENIU

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