Provided by:
manpages-pt-dev_20040726-4_all 
NOME
getaddrinfo - traducao de endereco de rede e servico
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,C~AO
A funcao getaddrinfo(3) combina a funcionalidade fornecida pelas
funcoes getipnodebyname(3), getipnodebyaddr(3), getservbyname(3), e
getservbyport(3) para uma interface simples. A funcao de linha segura
getaddrinfo(3) cria uma ou mais estruturas de enderecos de sockets que
podem ser usadas pelas chamadas de funcao bind(3) e connect(3) para
criar um socket de cliente ou de servidor.
A funcao getaddrinfo(3) nao e limitada a criacao de estruturas de
endereco de socket IPv4; estruturas de endereco de socket IPv6 podem
ser criadas se o suporte a IPv6 estiver disponivel. Estas estruturas de
endereco 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 funcao contem 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 ligacao alocada
dinamicamente de estruturas addrinfo , ligadas pelo membro ai_next. Ha
varias razoes pelas quais a lista de ligacao pode ter mais de uma
estrutura addrinfo , a saber: se o host da rede e multi-alocado; ou se
o mesmo servico esta disponivel para multiplos protocolos de socket (um
endereco SOCK_STREAM e outro endereco SOCK_DGRAM , por exemplo).
Os membros ai_family, ai_socktype, e ai_protocol tem o mesmo
significado que os parametros correspondentes na chamada de funcao
socket(3). A funcao getaddrinfo(3) retorna enderecos de socket de
retorno nas familias IPv4 ou IPv6, (ai_family sera setado para PF_INET
ou PF_INET6).
O parametro hints especifica o tipo preferido de socket, ou protocolo.
Um hints igual a NULL especifica que qualquer endereco de rede ou
protocolo e aceitavel. Se este parametro nao e 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 familia de protocolo (IPv4 ou IPv6, por
exemplo). 0 em ai_socktype ou em ai_protocol especifica que qualquer
tipo de socket ou protocolo e aceitavel tambem. O membro ai_flags
especifica opcoes adicionais, definidas abaixo. Flags multiplas sao
especificadas realizando uma operacao logica "OU" entre elas. Todos os
outros membros no parametro hints precisa conter 0, ou um ponteiro
nulo.
O parametro node ou service , mas nao ambos, podem ser NULL. node
especifica um endereco numerico de rede (formato separado por pontos
para IPv4, formato hexadecimal para IPv6) ou um nome de host da rede,
cujos enderecos de rede sao procurados e resolvidos. Se o membro
ai_flags no parametro hints contem a flag AI_NUMERICHOST , entao o
parametro node deve ser um endereco numerico de rede. A flag
AI_NUMERICHOST suprime qualquer procura de endereco de host da rede que
seja potencialmente longo.
A funcao getaddrinfo(3) cria uma lista de ligacao de estruturas
addrinfo , uma para cada endereco de rede sujeito a qualquer restricao
imposta pelo parametro hints. ai_canonname e 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
parametros de criacao do socket. Um ponteiro para o endereco do socket
e colocado no membro ai_addr , e o comprimento do endereco de socket,
em bytes, e colocado na estrutura ai_addrlen.
Se node e NULL, o endereco de rede em cada estrutura de socket e
inicializada de acordo com a flag AI_PASSIVE , que e setada no membro
ai_flags do parametro hints. O endereco de rede em cada estrutura de
socket sera deixado nao-especificado se a flag AI_PASSIVE e setada.
Isto e usado por aplicativos do servidor, que pretendem aceitar
conexoes de clientes em em qualquer endereco de rede. O endereco de
rede sera setado para o endereco de interface de 'loopback' se a flag
AI_PASSIVE nao for setada. Isto e usado por aplicativos de cliente,
que pretendem se conectar com um servidor rodando no mesmo host da
rede.
service seta o numero de porta no endereco de rede de cada estrutura de
socket. Se service e NULL, o numero de porta sera deixado nao-
inicializado.
A funcao freeaddrinfo(3) libera a memoria que foi alocada para a lista
de ligacao alocada dinamicamente res.
VALORES DE RETORNO
getaddrinfo(3) retorna 0 se for bem-sucedido, ou um dos codigos de erro
diferentes de zero:
EAI_FAMILY A familia de endereco requerida nao e suportada de jeito
nenhum.
EAI_SOCKTYPE O tipo de socket requerido nao e suportado de jeito
nenhum.
EAI_BADFLAGS ai_flags contem flags invalidas.
EAI_NONAME O n'o ou servi,co nao e conhecido. Este erro tambem e
retornado se tanto o n'o quanto o servi,co sao NULL.
EAI_SERVICE O servico requerido nao esta disponivel para o tipo de
socket requerido. Ele pode estar disponivel atraves de
outro tipo de socket.
EAI_ADDRFAMILY
O host de rede especificado nao tem quaisquer enderecos
de rede na familia de endereco requerida.
EAI_NODATA O host de rede especificado existe, mas nao tem qualquer
endereco de rede definido.
EAI_MEMORY Falta de memoria.
EAI_FAIL O servidor de nomes retornou uma indicacao de falha
permanente.
EAI_AGAIN O servidor de nome retornou uma indicacao de falha
temporaria. Tente novamente mais tarde.
EAI_SYSTEM Outro erro de sistema, verifique errno para mais
detalhes.
A funcao gai_strerror(3) traduz estes codigos de erro para uma string
legivel para o homem, confiavel para o relato de erros.
VEJA TAMB'EM
getipnodebyname(3), getipnodebyaddr(3)
TRADU,C~AO PARA A L'INGUA PORTUGUESA
RUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traducao) XXXXXX XX
XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisao)
Pagina de Manual Linux 22 de maio de 2000 getaddrinfo(3)