Provided by:
manpages-pt-dev_20040726-2_all 
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)