Provided by: manpages-pt-dev_20040726-4_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)