Provided by: manpages-pl-dev_20060617-1_all bug

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)