getipnodebyname(3)

NOME
getipnodebyname, getipnodebyaddr, freehostent - obtém nomes e endereços de 'hosts' da rede

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

struct hostent *getipnodebyname(const char *name,
                         int af, int flags,
                         int *error_num);

struct hostent *getipnodebyaddr(const void *addr,
                         size_t len, int af,
                         int *error_num);

void freehostent(struct hostent *ip);

DESCRIÇÃO
As funções getipnodebyname(3) e getipnodebyaddr(3) retornam os nomes e endereços de um 'host' da rede. Estas funções retornam um ponteiro para a seguinte estrutura:

struct hostent {
        char    *h_name;
        char    **h_aliases;
        int     h_addrtype;
        int     h_length;
        char    **h_addr_list;
};

Estas funções substituem as funções gethostbyname(3) e gethostbyaddr(3), as quais podiam acessar apenas a família de endereços de rede IPv4. As funções getipnodebyname(3) e getipnodebyaddr(3) podem acessar várias famílias de endereços de rede.

Diferentemente das funções gethostby estas funções retornam ponteiros para memória alocada dinamicamente. A função freehostent(3) é utilizada para liberar a memória alocada dinamicamente depois do chamador não mais precisar da estrutura hostent.

  Parâmetros de getipnodebyname
A função getipnodebyname(3) procura endereços de rede para o 'host' especificada pelo parâmetro especificado pelo parâmetro name. O parâmetro af especifica um dos seguintes valores:

AF_INET
    O parâmetro name aponta para um endereço IPv4 na notação quadri-pontuada ou um nome de um 'host' de rede IPv4.

AF_INET6
    O parâmetro name aponta para um endereço IPv6 hexadecimal ou um nome de um 'host' de rede IPv6.

O parâmetro flags especifica opções adicionais. Mais de uma opção pode ser especificada utilizando-se uma operação de OR lógico. flags devem ser definidos para 0 se nenhuma opção é desejada.

AI_V4MAPPED
    Este sinalizador é usado com AF_INET6 para solicitar uma busca por endereços IPv4 em vez de endereços IPv6; os endereços IPv4 serão mapeados para endereços IPv6.

AI_ALL
    Este sinalizador é usado com AI_V4MAPPED para solicitar uma busca para ambos endereços IPv4 e IPv6. Qualquer endereço IPv4 será mapeado para um endereço IPv6.

AI_ADDRCONFIG
    Este sinalizador é usado com AF_INET6 para também solicitar que as buscas por endereços IPv6 não sejam feitas a não ser que o sistema possua ao menos um endereço IPv6 atribuído a uma interface de rede, e que buscas por endereços IPv4 não sejam feitos a não ser que o sistema possua no mínimo um endereço IPv4 atribuído para uma interface de rede. Este sinalizador pode ser usado sozinho ou em conjunto com o sinalizador AI_V4MAPPED.

AI_ALL
    Este sinalizador é equivalente a (AI_ADDRCONFIG | AI_V4MAPPED).

  Parâmetros de getipnodebyaddr
A função getipnodebyaddr(3) procura o nome do 'host' da qual o endereço de rede é especificado pelo parâmetro addr. O parâmetro af especifica um dos seguintes valores:

AF_INET
    O parâmetro addr aponta para uma struct in_addr e len deve ser definido como sizeof(struct in_addr).

AF_INET6
    O parâmetro addr aponta para uma struct in6_addr e len deve estar definido como sizeof(struct in6_addr).

VALORES RETORNADOS
Um ponteiro nulo é retornado se um erro ocorreu, e error_num conterá um código de erro da seguinte lista:

HOST_NOT_FOUND
    O nome do 'host' ou endereço de rede não foi encontrado.

NO_ADDRESS
    O servidor de nomes reconheceu o endereço de rede ou nome, mas nenhuma resposta foi retornada. Isto pode acontecer se a máquina de rede possiu apenas endereços IPv4 e uma solicitação foi feita por informação de IPv6 apenas, ou vice-versa.

NO_RECOVERY
    O servidor de nomes retornou uma resposta de falha permanente.

TRY_AGAIN
    O servidor de nomes retornou uma resposta de falha temporária. Você pode ter mais sorte na próxima vez.

Uma busca bem sucedida retorna um ponteiro para uma estrutura hostent que contém os seguintes campos:

h_name
    Este é o nome oficial deste 'host' da rede.

h_aliases
    Este é um array de ponteiros para aliases não oficiais para a mesma máquina. O array é terminado por um ponteiro nulo.

h_addrtype
    Este é uma cópia do parâmetro af para getipnodebyname(3) ou getipnodebyaddr(3). h_addrtype sempre será AF_INET se o parâmetro af for AF_INET. h_addrtype será sempre AF_INET6 se o parâmetro af af for AF_INET6.

h_length
    Este campo será definido para sizeof(struct in_addr) se h_addrtype for AF_INET, e para sizeof(struct in6_addr) se h_addrtype for AF_INET6.

h_addr_list
    Este é um array de um ou mais ponteiros para estruturas de endereços de rede para o 'host' de rede. O array é terminado por um ponteiro nulo.

VEJA TAMBÉM
getaddrinfo(3), inet_ntop(3), inet_pton(3).

TRADUZIDO POR LDP-BR em 28/05/2001.

  Tradução:
Felipe M Pereira <Felipe.Pereira@ic.unicamp.br>

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