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)