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 serviço não é conhecido.
Este erro também é retornado se tanto o nó
quanto o serviço 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)