.\" Copyright 2000 Sam Varshavchik <mrsam@stop.mail-abuse.org>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" References: RFC 2553
.TH getaddrinfo 3 "22 de maio de 2000" "Pgina de Manual Linux" "Manual do Programador Linux"
.SH NOME
getaddrinfo \- traduo de endereo de rede e servio
.SH SINOPSE
.nf
.B "#include <sys/types.h>
.B "#include <sys/socket.h>
.B "#include <netdb.h>
.sp
.BI "int rc=getaddrinfo(const char *" "node" ", const char *" "service" ","
.BI "                   const struct addrinfo *" "hints" ","
.BI "                   struct addrinfo **" "res" ");"
.sp
.BI "void freeaddrinfo(struct addrinfo *" "res" ");"
.sp
.BI "char *gai_strerror(int " "errcode" ");"
.fi
.SH DESCRIO
A funo
.BR "getaddrinfo" "(3)
combina a funcionalidade fornecida pelas funes
.BR "getipnodebyname" "(3),
.BR "getipnodebyaddr" "(3),
.BR "getservbyname" "(3),
e
.BR "getservbyport" "(3)
para uma interface simples.
A funo de linha segura
.BR "getaddrinfo" "(3)
cria uma ou mais estruturas de endereos de sockets que podem ser usadas pelas chamadas de funo
.BR "bind" "(3)
e
.BR "connect" "(3)
para criar um socket de cliente ou de servidor.

A funo
.BR "getaddrinfo" "(3)
no  limitada  criao de estruturas de endereo de socket IPv4; estruturas de endereo de
socket IPv6 podem ser criadas se o suporte a IPv6 estiver disponvel. Estas estruturas de endereo
de socket podem ser usadas diretamente por
.BR "bind" "(3)
ou por
.BR "connect" "(3),
para preparar um socket de cliente ou de servidor.

A estrutura
.B addrinfo
usada por esta funo contm os seguintes membros:
.sp
.nf
.B "struct addrinfo {
.BI "    int     " "ai_flags" ";
.BI "    int     " "ai_family" ";
.BI "    int     " "ai_socktype" ";
.BI "    int     " "ai_protocol" ";
.BI "    size_t  " "ai_addrlen" ";
.BI "    struct sockaddr *" "ai_addr" ";
.BI "    char   *" "ai_canonname" ";
.BI "    struct addrinfo *" "ai_next" ";
.B "};
.fi
.PP
.BR "getaddrinfo" "(3)
seta
.I res
para apontar para a lista de ligao alocada dinamicamente de estruturas
.B addrinfo
, ligadas pelo membro
.I ai_next.
H vrias razes pelas quais a lista de ligao pode ter mais de uma estrutura
.B addrinfo
, a saber: se o host da rede  multi-alocado; ou se o mesmo servio
est disponvel para mltiplos protocolos de socket (um endereo
.B SOCK_STREAM
e outro endereo 
.B SOCK_DGRAM
, por exemplo).

Os membros
.IR "ai_family" ",
.IR "ai_socktype" ",
e
.I "ai_protocol"
tm o mesmo significado que os parmetros correspondentes na chamada de funo
.BR socket (3).
A funo
.BR "getaddrinfo" "(3)
retorna endereos de socket de retorno nas famlias IPv4 ou IPv6, 
.RI "(" "ai_family
ser setado para 
.B PF_INET
ou
.BR PF_INET6 ").

O parmetro
.I hints
especifica o tipo preferido de socket, ou protocolo.
Um
.I hints
igual a NULL especifica que qualquer endereo de rede ou protocolo  aceitvel.
Se este parmetro no  
.B NULL
, ele aponta para a estrutura
.B addrinfo
cujos membros
.IR ai_family ,
.IR ai_socktype ,
e
.I ai_protocol
especificam o tipo preferido de socket.
.B PF_UNSPEC
em
.I ai_family
especifica qualquer famlia de protocolo (IPv4 ou IPv6, por exemplo).
0 em
.I ai_socktype
ou em
.I ai_protocol
especifica que qualquer tipo de socket ou protocolo  aceitvel tambm.
O membro
.I ai_flags
especifica opes adicionais, definidas abaixo. Flags mltiplas so especificadas
realizando uma operao lgica "OU" entre elas. Todos os outros membros no parmetro
.I hints
precisa conter 0, ou um ponteiro nulo.

O parmetro
.I node
ou
.I service
, mas no ambos, podem ser NULL.
.I node
especifica um endereo numrico de rede (formato separado por pontos para IPv4, formato
hexadecimal para IPv6)
ou um nome de host da rede, cujos endereos de rede so procurados e resolvidos.
Se o membro
.I ai_flags
no parmetro
.I hints
contm a flag
.B AI_NUMERICHOST
, ento o parmetro
.I node
deve ser um endereo numrico de rede.
A flag
.B AI_NUMERICHOST
suprime qualquer procura de endereo de host da rede que seja potencialmente longo.

A funo 
.BR "getaddrinfo" "(3)
cria uma lista de ligao de estruturas
.B addrinfo
, uma para cada endereo de rede sujeito a qualquer restrio imposta pelo parmetro
.I hints.
.I "ai_canonname
 setada para apontar para o nome oficial do host, se
.I ai_flags
em
.I hints
inclui a flag
.B AI_CANONNAME.
.IR ai_family ,
.IR ai_socktype ,
e
.I ai_protocol
especificam os parmetros de criao do socket.
Um ponteiro para o endereo do socket  colocado no membro
.I ai_addr
, e o comprimento do endereo de socket, em bytes,  colocado
na estrutura
.I ai_addrlen.

Se
.I node
 NULL,
o  endereo de rede em cada estrutura de socket  inicializada de acordo com a flag
.B AI_PASSIVE
, que  setada no membro
.I ai_flags
do parmetro
.I hints.
O endereo de rede em cada estrutura de socket ser deixado no-especificado
se a flag
.B AI_PASSIVE
 setada.
Isto  usado por aplicativos do servidor, que pretendem aceitar conexes de clientes em 
em qualquer endereo de rede.
O endereo de rede ser setado para o endereo de interface de 'loopback' se 
a flag
.B AI_PASSIVE
no for setada.
Isto  usado por aplicativos de cliente, que pretendem se conectar com um 
servidor rodando no mesmo host da rede.

.I service
seta o nmero de porta no endereo de rede de cada estrutura de socket.
Se
.I service
 NULL, o nmero de porta ser deixado no-inicializado.

A funo
.BR "freeaddrinfo" "(3)
libera a memria que foi alocada para a lista de ligao alocada dinamicamente
.IR res .
.SH "VALORES DE RETORNO
.BR "getaddrinfo" "(3)
retorna 0 se for bem-sucedido, ou um dos cdigos de erro diferentes de zero:
.TP 14
.B EAI_FAMILY
A famlia de endereo requerida no  suportada de jeito nenhum.
.TP 14
.B EAI_SOCKTYPE
O tipo de socket requerido no  suportado de jeito nenhum.
.TP 14
.B EAI_BADFLAGS
.I ai_flags
contm flags invlidas.
.TP 14
.B EAI_NONAME
O
.I n
ou
.I servio
no  conhecido.
Este erro tambm  retornado se tanto o
.I n
quanto o
.I servio
so NULL.
.TP 14
.B EAI_SERVICE
O servio requerido no est disponvel para o tipo de socket requerido.
Ele pode estar disponvel atravs de outro tipo de socket.
.TP 14
.B EAI_ADDRFAMILY
O host de rede especificado no tem quaisquer endereos de rede na famlia
de endereo requerida.
.TP 14
.B EAI_NODATA
O host de rede especificado existe, mas no tem qualquer endereo de rede 
definido.
.TP 14
.B EAI_MEMORY
Falta de memria.
.TP 14
.B EAI_FAIL
O servidor de nomes retornou uma indicao de falha permanente.
.TP 14
.B EAI_AGAIN
O servidor de nome retornou uma indicao de falha temporria.
Tente novamente mais tarde.
.TP 14
.B EAI_SYSTEM
Outro erro de sistema, verifique 
.I errno
para mais detalhes.
.PP
A funo
.BR "gai_strerror" "(3)
traduz estes cdigos de erro para uma string legvel para o homem,
confivel para o relato de erros.
.SH "VEJA TAMBM
.BR getipnodebyname (3),
.BR getipnodebyaddr (3)
.SH TRADUO PARA A LNGUA PORTUGUESA
\&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traduo)\fR
\&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (reviso)\fR