getnameinfo(3)

NOME
getnameinfo - tradução endereço-nome de forma independente do protocolo

SINOPSIS
#include <sys/socket.h>
#include <netdb.h>

int getnameinfo(const struct sockaddr *sa, socklen_t salen,
                char *host, size_t hostlen,
                char *serv, size_t servlen, int flags);

DESCRIÇÃO
A função getnameinfo(3) está definida para tradução endereço-nomedonó independentemente de protocolo. Ela combina a funcionalidade de gethostbyaddr(3) e getservbyport(3) e é o inverso de getaddrinfo(3). O argumento sa é um ponteiro para uma estrutura de endereço de 'socket' genérico (de tipo (of type sockaddr_in ou sockaddr_in6) de tamanho salen que contém as entradas endereço IP e número da porta. Os argumentos host e serv são ponteiros para buffers (de tamanho hostlen e servlen respectivamente) para manter os valores de retorno. O chamador pode especificar que o 'hostname' (ou o nome de serviço) não está sendo solicitado fornecendo um argumento host (ou serv) como NULO ou um parâmetro hostlen (ou servlen) como zero. Entretanto, um dos dois (ou "hostname" ou nome de serviço) deve ser solicitado. O argumento flags modifica o comportamento de getnameinfo(3) como segue:

NI_NOFQDN
    Se ligado, retorna apenas a parte "hostname" do FQDN para hosts locais.

NI_NUMERICHOST
    Se ligado, então a forma numérica do "hostname" é retornada. (Quando desligado, isto ainda irá acontecer para o caso em que o nome do nó não puder ser encontrado.)

NI_NAMEREQD
    Se ligado, um erro é retornado se o "hostname" não pode ser encontrado.

NI_NUMERICSERV
    Se ligado, o endereço de serviço é retornado na forma numérica, por exemplo, pelo seu número de porta.

NI_DGRAM
    Se ligado, o serviço é baseado em datagrama (UDP) em vez de baseado em stream (TCP). Isto é requerido para as poucas portas (512-514) que possuem serviços diferentes para UDP e TCP.

VALORES RETORNADOS
No sucesso, 0 é retornado, e nomes de nó e de serviço, se solicitados, são preenchidos com strings terminadas em ' ', possivelmente truncadas para caber nos tamanhos de buffers especificados. Havendo erro um valor diferente de zero é retornado, e a variável errno é ajustada apropriadamente.

ERROS

EAI_AGAIN
    O nome não pode ser resolvido desta vez. Tente novamente mais tarde.

EAI_BADFLAGS
    O parâmetro flags possui um valor inválido.

EAI_FAIL
    Um erro irrecuperável ocorreu.

EAI_FAMILY
    A família de endereços não foi reconhecida, ou o tamanho do endereço era inválido para a família especificada.

EAI_MEMORY
    Memória insuficiente.

EAI_NONAME
    O nome não é resolvido para os parâmetros supridos. NI_NAMEREQD está ligado e o nome do host não pode ser localizado, ou nem o hostname nem o nome de serviço foram solicitados.

EAI_SYSTEM
    Um erro de sistema ocorreu. O código de erro pode ser encontrado em errno.

ARQUIVOS
/etc/hosts
/etc/nsswitch.conf
/etc/resolv.conf

NOTA
A fim de ajudar o programador a escolher tamanhos razoáveis para os buffers fornecidos, <netdb.h> define as constantes
    # define NI_MAXHOST      1025
    # define NI_MAXSERV      32
A primeira é a constante MAXDNAME em versões recentes do arquivo header do BIND <arpa/nameser.h>. O último é um chute baseado nos serviços listados na RFC "Assigned Numbers" atual.

EXEMPLOS
O seguinte código tenta obter o hostname numérico e o nome de serviço, para um dado endereço de 'socket'. Note que não há referência no código para uma família de endereços em particular.
      struct sockaddr *sa;    /* entrada */
      char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
      if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
          sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
              printf("host=%s, serv=%s\n", hbuf, sbuf);
A seguinte versão verifica se o endereço do 'socket' possui um mapeamento de endereço reverso.
      struct sockaddr *sa; /* entrada */
      char hbuf[NI_MAXHOST];
      if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
          NULL, 0, NI_NAMEREQD))
             printf("não foi possível resolver hostname");
      else
             printf("host=%s\n", hbuf);

DE ACORDO COM
RFC 2553. (See also XNS, issue 5.2.)

VEJA TAMBÉM
getaddrinfo(3), gethostbyaddr(3), getservbyname(3), getservbyport(3), inet_ntop(3), socket(3), hosts(5), services(5), hostname(7), named(8).

R. Gilligan, S. Thomson, J. Bound e W. Stevens, Basic Socket Interface Extensions for IPv6, RFC 2553, March 1999.

Tatsuya Jinmei e Atsushi Onoe, An Extension of Format for IPv6 Scoped Addresses, versão preliminar da internet, trabalho em progresso. ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt

Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track: 2000 USENIX annual technical conference, June 2000. http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html

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>