GETHOSTBYNAME(3)

NOME
gethostbyname, gethostbyaddr, sethostent, endhostent, herror, hstrerror - obtém entrada de 'host' de rede

SINÓPSE
#include <netdb.h>
extern int h_errno;

struct hostent *gethostbyname(const char *name);

#include <sys/socket.h>        /* for AF_INET */
struct hostent *gethostbyaddr(const char *addr,
  int len, int type);

void sethostent(int stayopen);

void endhostent(void);

void herror(const char *s);

const char * hstrerror(int err);

DESCRIÇÃO
A função gethostbyname() retorna uma estrutura do tipo hostent para o 'host' name. Aqui name é ou um nome de 'host', ou um endereço IPv4 na notação padrão utilizando pontos, ou um endereço IPv6 em notação utilizando dois-pontos (e possivelmente pontos). (Veja RFC 1884 para a descrição dos endereços IPv6). Se nome é um endereço IPv4 ou IPv6, nenhuma busca é realizada e gethostbyname() simplesmente copia name para o campo h_name e sua struct in_addr equivalente para o campo h_addr_list[0] da estrutura hostent retornada. Se name não termina num ponto e a variável de ambiente HOSTALIASES está definida, o arquivo de alias apontado por HOSTALIASES será percorrido em busca de name primeiro (veja hostname(7) para o formato do arquivo). O domínio atual e seus pais são procurados a não ser que name termine num ponto.

A função gethostbyaddr() retorna uma estrutura do tipo hostent para o endereço de 'host' addr dado de tamanho len e tipo de endereço type. O único tipo de endereço válido no momento é AF_INET.

A função sethostent() especifica, se stayopen é verdadeiro (1), que um socket TCP conectado deve ser usado para as buscas do servidor de nomes e que a conexão deve permanecer aberta durante as buscas subseqüentes. Caso contrário, as buscas do servidor de nomes usarão datagramas UDP.

A função endhostent() finaliza o uso de uma conexão TCP para as buscas do servidor de nomes.

A função (obsoleta) herror() mostra a mensagem de erro associada com o valor atual de h_errno em stderr.

A função (obsoleta) hstrerror() toma um número de erro (tipicamente h_errno) e retorna a string da mensagem correspondente.

As buscas de nome de domínio realizadas por gethostbyname() e gethostbyaddr() usam uma combinação de alguns ou todos do servidor de nomes named(8), uma linha retirada do arquivo /etc/hosts, e o Network Information Service (NIS ou YP), dependendo da linha order em /etc/host.conf. (Veja resolv+(8)). A ação padrão é buscar no named(8), seguido pelo /etc/hosts.

A estrutura hostent está definida em <netdb.h> como segue:

    struct hostent {
    	char	*h_name;		/* nome oficial do 'host' */
    	char	**h_aliases;		/* lista de aliases */
    	int	h_addrtype;		/* tipo de endereço da 'host' */
    	int	h_length;		/* tamanho do endereço */
    	char	**h_addr_list;		/* lista de endereços */
    }
    #define h_addr	h_addr_list[0]		/* para compatibilidade */

Os membros da estrutura hostent são:

h_name
    O nome oficial do 'host'.

h_aliases
    Um array terminado por zero de nomes alternativos para o 'host'.

h_addrtype
    O tipo do endereço; sempre AF_INET no momento.

h_length
    O tamanho do endereço em bytes.

h_addr_list
    Um array terminado por zero de endereços de rede para o 'host' na ordem de byte da rede.

h_addr
    O primeiro endereço em h_addr_list para compatibilidade.

VALORES RETORNADOS
As funções gethostbyname() and gethostbyaddr() retornam a estrutura hostent ou um ponteiro NULL se um erro ocorre. No erro, a variável h_errno guarda o número de um erro.

ERROS
A variável h_errno pode ter os seguintes valores:

HOST_NOT_FOUND
    O 'host' especificada é desconhecida.

NO_ADDRESS ou NO_DATA
    O nome solicitado é válido mas não tem um endereço IP.

NO_RECOVERY
    Um erro não-recuperável do servidor de nomes ocorreu.

TRY_AGAIN
    Um erro temporário ocorreu em um servidor de nomes autoritativo. Tente novamente mais tarde.

ARQUIVOS

/etc/host.conf
    arquivo de configuração do resolvedor

/etc/hosts
    arquivo do banco de dados de 'host'

DE ACORDO COM
BSD 4.3.

NOTAS
As funções gethostbyname() e gethostbyaddr() podem devolver ponteiros para dados estáticos, que podem ser sobre escritos por outras chamadas. Copiar o struct hostent não é suficente, desde que ele contenha ponteiros - um copia profunda é requerida.

O padrão SUS-v2 está com erro e declara que o parâmetro len é do tipo size_t. (Isto está errado, porque ele tem que ser int, e size_t não é. A versão preliminar de Austin diz que deve ser socklen_t, o que é OK.)

Glibc2 também tem

struct hostent *gethostbyname2(const char *name, int af);

que funciona como gethostbyname(), mas permite especificar uma família de endereços ao qual o endereço deve pertencer.

O rascunho Austin aponta gethostbyaddr() e gethostbyname() como arcaicas, e introduz

struct hostent *getipnodebyaddr (const void *restrict addr,
  socklen_t len, int type, int *restrict error_num);

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

VEJA TAMBÉM
resolver(3), hosts(5), hostname(7), resolv+(8), named(8).

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>