getaddrinfo(3)

NOME
getaddrinfo - tradução de endereço de rede e serviço

SINÓPSE
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>

int getaddrinfo(const char *node, const char *service,
                const struct addrinfo *hints,
                struct addrinfo **res);

void freeaddrinfo(struct addrinfo *res);

const 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 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) seleciona 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á selecionado para PF_INET ou PF_INET6).

O parâmetro hints especifica o tipo preferido de socket, ou protocolo. Um hints igual a NULO especifica que qualquer endereço de rede ou protocolo é aceitável. Se este parâmetro não é NULO, 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 NULO. 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 um sinalizador AI_NUMERICHOST, então o parâmetro node deve ser um endereço numérico de rede. Um sinalizador 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 é selecionada para apontar para o nome oficial do 'host', se ai_flags em hints inclui um sinalizador 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 é NULO, o endereço de rede em cada estrutura de 'socket' é inicializada de acordo com um sinalizador AI_PASSIVE, que é selecionada no membro ai_flags do parâmetro hints. O endereço de rede em cada estrutura de 'socket' será deixado não-especificado se um sinalizador AI_PASSIVE é selecionada. 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á selecionado para o endereço de interface de 'loopback' se um sinalizador AI_PASSIVE não for selecionada. Isto é usado por aplicativos de cliente, que pretendem se conectar com um servidor rodando no mesmo 'host' da rede.

service seleciona o número de porta no endereço de rede de cada estrutura de 'socket'. Se service é NULO, 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 RETORNADOS
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 sinalizadores 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 NULO.

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).

TRADUZIDO POR LDP-BR em 21/08/2000.

  Tradução:
Rubens de Jesus Nogueira <darkseid99@usa.net>

  Revisão.:
André Luiz Fassone <lonely_wolf@ig.com.br>