.\" Copyright 2000 Sam Varshavchik .\" .\" 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" "Página de Manual Linux" "Manual do Programador Linux" .SH NOME getaddrinfo \- tradução de endereço de rede e serviço .SH SINOPSE .nf .B "#include .B "#include .B "#include .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 DESCRIÇÃO A função .BR "getaddrinfo" "(3) combina a funcionalidade fornecida pelas funções .BR "getipnodebyname" "(3), .BR "getipnodebyaddr" "(3), .BR "getservbyname" "(3), e .BR "getservbyport" "(3) para uma interface simples. A função de linha segura .BR "getaddrinfo" "(3) cria uma ou mais estruturas de endereços de sockets que podem ser usadas pelas chamadas de função .BR "bind" "(3) e .BR "connect" "(3) para criar um socket de cliente ou de servidor. A função .BR "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 a IPv6 estiver disponível. Estas estruturas de endereço 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 função contém 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 ligação alocada dinamicamente de estruturas .B addrinfo , ligadas pelo membro .I ai_next. Há várias razões pelas quais a lista de ligação pode ter mais de uma estrutura .B 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 .B SOCK_STREAM e outro endereço .B SOCK_DGRAM , por exemplo). Os membros .IR "ai_family" ", .IR "ai_socktype" ", e .I "ai_protocol" têm o mesmo significado que os parâmetros correspondentes na chamada de função .BR socket (3). A função .BR "getaddrinfo" "(3) retorna endereços de socket de retorno nas famílias IPv4 ou IPv6, .RI "(" "ai_family será setado para .B PF_INET ou .BR PF_INET6 "). O parâmetro .I hints especifica o tipo preferido de socket, ou protocolo. Um .I hints igual a NULL especifica que qualquer endereço de rede ou protocolo é aceitável. Se este parâmetro não é .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 família 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 é aceitável também. O membro .I 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 .I hints precisa conter 0, ou um ponteiro nulo. O parâmetro .I node ou .I service , mas não ambos, podem ser NULL. .I 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 .I ai_flags no parâmetro .I hints contém a flag .B AI_NUMERICHOST , então o parâmetro .I node deve ser um endereço numérico de rede. A flag .B AI_NUMERICHOST suprime qualquer procura de endereço de host da rede que seja potencialmente longo. A função .BR "getaddrinfo" "(3) cria uma lista de ligação de estruturas .B addrinfo , uma para cada endereço de rede sujeito a qualquer restrição imposta pelo parâmetro .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 parâmetros de criação do socket. Um ponteiro para o endereço do socket é colocado no membro .I ai_addr , e o comprimento do endereço de socket, em bytes, é colocado na estrutura .I ai_addrlen. Se .I node é NULL, o endereço de rede em cada estrutura de socket é inicializada de acordo com a flag .B AI_PASSIVE , que é setada no membro .I ai_flags do parâmetro .I hints. O endereço de rede em cada estrutura de socket será deixado não-especificado se a flag .B AI_PASSIVE é setada. 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á setado para o endereço de interface de 'loopback' se a flag .B AI_PASSIVE não 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 número de porta no endereço de rede de cada estrutura de socket. Se .I service é NULL, o número de porta será deixado não-inicializado. A função .BR "freeaddrinfo" "(3) libera a memória que foi alocada para a lista de ligação alocada dinamicamente .IR res . .SH "VALORES DE RETORNO .BR "getaddrinfo" "(3) retorna 0 se for bem-sucedido, ou um dos códigos de erro diferentes de zero: .TP 14 .B EAI_FAMILY A família de endereço requerida não é suportada de jeito nenhum. .TP 14 .B EAI_SOCKTYPE O tipo de socket requerido não é suportado de jeito nenhum. .TP 14 .B EAI_BADFLAGS .I ai_flags contém flags inválidas. .TP 14 .B EAI_NONAME O .I nó ou .I serviço não é conhecido. Este erro também é retornado se tanto o .I nó quanto o .I serviço são NULL. .TP 14 .B 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. .TP 14 .B EAI_ADDRFAMILY O host de rede especificado não tem quaisquer endereços de rede na família de endereço requerida. .TP 14 .B EAI_NODATA O host de rede especificado existe, mas não tem qualquer endereço de rede definido. .TP 14 .B EAI_MEMORY Falta de memória. .TP 14 .B EAI_FAIL O servidor de nomes retornou uma indicação de falha permanente. .TP 14 .B EAI_AGAIN O servidor de nome retornou uma indicação de falha temporária. Tente novamente mais tarde. .TP 14 .B EAI_SYSTEM Outro erro de sistema, verifique .I errno para mais detalhes. .PP A função .BR "gai_strerror" "(3) traduz estes códigos de erro para uma string legível para o homem, confiável para o relato de erros. .SH "VEJA TAMBÉM .BR getipnodebyname (3), .BR getipnodebyaddr (3) .SH TRADUÇÃO PARA A LÍNGUA PORTUGUESA \&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA (tradução)\fR \&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX (revisão)\fR