Provided by: manpages-pt-dev_20040726-2_all bug

NOME

       getaddrinfo - tradução de endereço de rede e serviço

SINOPSE

       #include <sys/types.h>
       #include <sys/socket.h>
       #include <netdb.h>

       int rc=getaddrinfo(const char *node, const char *service,
                          const struct addrinfo *hints,
                          struct addrinfo **res);

       void freeaddrinfo(struct addrinfo *res);

       char *gai_strerror(int errcode);

DESCRIÇÃO

       A  função  getaddrinfo(3)  combina  a  funcionalidade  fornecida  pelas
       funções  getipnodebyname(3),  getipnodebyaddr(3),  getservbyname(3),  e
       getservbyport(3)  para uma interface simples.  A função de linha segura
       getaddrinfo(3) cria uma ou mais estruturas de endereços de sockets  que
       podem  ser  usadas  pelas  chamadas de função bind(3) e connect(3) para
       criar um socket de cliente ou de servidor.

       A função getaddrinfo(3) não é  limitada  à  criação  de  estruturas  de
       endereço  de  socket  IPv4; estruturas de endereço de socket IPv6 podem
       ser criadas se o suporte a IPv6 estiver disponível. Estas estruturas de
       endereço  de  socket  podem  ser  usadas diretamente por bind(3) ou por
       connect(3), para preparar um socket de cliente ou de servidor.

       A estrutura addrinfo usada por esta função contém os seguintes membros:

       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)  seta  res  para apontar para a lista de ligação alocada
       dinamicamente de estruturas addrinfo , ligadas pelo membro ai_next.  Há
       várias  razões  pelas  quais  a  lista  de ligação pode ter mais de uma
       estrutura addrinfo , a saber: se o host da rede é multi-alocado; ou  se
       o mesmo serviço está disponível para múltiplos protocolos de socket (um
       endereço SOCK_STREAM e outro endereço SOCK_DGRAM , por exemplo).

       Os  membros  ai_family,  ai_socktype,  e  ai_protocol   têm   o   mesmo
       significado  que  os  parâmetros  correspondentes  na chamada de função
       socket(3).  A função getaddrinfo(3)  retorna  endereços  de  socket  de
       retorno  nas famílias IPv4 ou IPv6, (ai_family será setado para PF_INET
       ou PF_INET6).

       O parâmetro hints especifica o tipo preferido de socket, ou  protocolo.
       Um  hints  igual  a  NULL  especifica  que qualquer endereço de rede ou
       protocolo é aceitável.  Se este parâmetro não é NULL , ele aponta  para
       a   estrutura   addrinfo   cujos   membros  ai_family,  ai_socktype,  e
       ai_protocol especificam o  tipo  preferido  de  socket.   PF_UNSPEC  em
       ai_family  especifica  qualquer família de protocolo (IPv4 ou IPv6, por
       exemplo).  0 em ai_socktype ou em ai_protocol especifica  que  qualquer
       tipo  de  socket  ou  protocolo  é aceitável também.  O membro ai_flags
       especifica opções adicionais, definidas  abaixo.  Flags  múltiplas  são
       especificadas  realizando uma operação lógica "OU" entre elas. Todos os
       outros membros no parâmetro hints precisa  conter  0,  ou  um  ponteiro
       nulo.

       O  parâmetro  node  ou  service  , mas não ambos, podem ser NULL.  node
       especifica um endereço numérico de rede (formato  separado  por  pontos
       para  IPv4,  formato hexadecimal para IPv6) ou um nome de host da rede,
       cujos endereços de rede são  procurados  e  resolvidos.   Se  o  membro
       ai_flags  no  parâmetro  hints  contém  a flag AI_NUMERICHOST , então o
       parâmetro  node  deve  ser  um  endereço  numérico  de  rede.   A  flag
       AI_NUMERICHOST suprime qualquer procura de endereço de host da rede que
       seja potencialmente longo.

       A função  getaddrinfo(3)  cria  uma  lista  de  ligação  de  estruturas
       addrinfo  , uma para cada endereço de rede sujeito a qualquer restrição
       imposta pelo parâmetro hints.  ai_canonname é setada para apontar  para
       o   nome   oficial  do  host,  se  ai_flags  em  hints  inclui  a  flag
       AI_CANONNAME.  ai_family, ai_socktype,  e  ai_protocol  especificam  os
       parâmetros de criação do socket.  Um ponteiro para o endereço do socket
       é colocado no membro ai_addr , e o comprimento do endereço  de  socket,
       em bytes, é colocado na estrutura ai_addrlen.

       Se  node  é  NULL,  o   endereço  de rede em cada estrutura de socket é
       inicializada de acordo com a flag AI_PASSIVE , que é setada  no  membro
       ai_flags  do  parâmetro hints.  O endereço de rede em cada estrutura de
       socket será deixado não-especificado se a  flag  AI_PASSIVE  é  setada.
       Isto  é  usado  por  aplicativos  do  servidor,  que  pretendem aceitar
       conexões de clientes em em qualquer endereço de rede.   O  endereço  de
       rede  será  setado para o endereço de interface de ’loopback’ se a flag
       AI_PASSIVE não for setada.  Isto é usado por  aplicativos  de  cliente,
       que  pretendem  se  conectar  com  um servidor rodando no mesmo host da
       rede.

       service seta o número de porta no endereço de rede de cada estrutura de
       socket.   Se  service  é  NULL,  o  número  de  porta será deixado não-
       inicializado.

       A função freeaddrinfo(3) libera a memória que foi alocada para a  lista
       de ligação alocada dinamicamente res.

VALORES DE RETORNO

       getaddrinfo(3) retorna 0 se for bem-sucedido, ou um dos códigos de erro
       diferentes de zero:

       EAI_FAMILY    A família de endereço requerida não é suportada de  jeito
                     nenhum.

       EAI_SOCKTYPE  O  tipo  de  socket  requerido  não  é suportado de jeito
                     nenhum.

       EAI_BADFLAGS  ai_flags contém flags inválidas.

       EAI_NONAME    O n ou servio não é  conhecido.   Este  erro  também  é
                     retornado se tanto o n quanto o servio são NULL.

       EAI_SERVICE   O  serviço  requerido  não está disponível para o tipo de
                     socket requerido.  Ele pode estar disponível  através  de
                     outro tipo de socket.

       EAI_ADDRFAMILY
                     O  host  de rede especificado não tem quaisquer endereços
                     de rede na família de endereço requerida.

       EAI_NODATA    O host de rede especificado existe, mas não tem  qualquer
                     endereço de rede definido.

       EAI_MEMORY    Falta de memória.

       EAI_FAIL      O  servidor  de  nomes  retornou  uma  indicação de falha
                     permanente.

       EAI_AGAIN     O servidor  de  nome  retornou  uma  indicação  de  falha
                     temporária.  Tente novamente mais tarde.

       EAI_SYSTEM    Outro   erro   de  sistema,  verifique  errno  para  mais
                     detalhes.

       A função gai_strerror(3) traduz estes códigos de erro para  uma  string
       legível para o homem, confiável para o relato de erros.

VEJA TAMBÉM

       getipnodebyname(3), getipnodebyaddr(3)

TRADUÇÃO PARA A LÍNGUA PORTUGUESA

       RUBENS  DE  JESUS  NOGUEIRA  <darkseid99@usa.net>  (tradução) XXXXXX XX
       XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisão)