.\" -*- nroff -*- .\" Don't change the first line, it tells man that we need tbl. .\" This man page is Copyright (C) 1999 Andi Kleen . .\" and copyright (c) 1999 Matthew Wilcox. .\" Permission is granted to distribute possibly modified copies .\" of this page provided the header is included verbatim, .\" and in case of nontrivial modification author and date .\" of the modification is added to the header. .\" $Id: socket.7,v 1.1 2000/10/20 13:05:11 ricardo Exp $ .TH SOCKET 7 "7/05/1999" "Página de Manual do Linux" "Manual do Programador Linux" .SH NOME socket - interface para socket Linux .SH SINOPSE .B #include .br .IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol ); .SH DESCRIÇÃO Esta página do manual descreve a interface de usuário para a camada de socket de rede Linux. Os sockets compatíveis com BSD são uma interface uniforme entre o processo do usuário e as pilhas de protocolo de rede no kernel. Os módulos de protocolo estão agrupados em .I famílias de protocolos como .BR PF_INET ", " PF_IPX ", " PF_PACKET e .I tipos de socket como .B SOCK_STREAM ou .BR SOCK_DGRAM . Veja .BR socket (2) para mais informações sobre famílias e tipos. .SH FUNÇÕES DA CAMADA DE SOCKET Estas funções são usadas pelo processo do usuário para enviar ou receber pacotes, e realizar outras operações de socket. Para mais informações, veja as respectivas páginas de manual. .BR socket (2) cria um socket, .BR connect (2) conecta um socket a um endereço de socket remoto, a função .BR bind (2) liga um socket a um endereço de socket local, .BR listen (2) diz ao socket que novas conexões serão aceitas, e .BR accept (2) é usado para obter um novo socket com uma nova conexão de entrada. .BR socketpair (2) retorna dois sockets anônimos conectados (somente implementados para algumas famílias locais, como .BR PF_UNIX ) .PP .BR send (2), .BR sendto (2), e .BR sendmsg (2) enviam dados através de um socket, e .BR recv (2), .BR recvfrom (2), .BR recvmsg (2) recebem dados de um socket. .BR poll (2) e .BR select (2) aguardam por dados que chegam ou um estado de prontidão para enviar dados. Além disso, as operações padrão de I/O como .BR write (2), .BR writev (2), .BR sendfile (2), .BR read (2), e .BR readv (2) podem ser usados para ler e escrever dados. .PP .BR getsockname (2) retorna o endereço local do socket e .BR getpeername (2) retorna o endereço remoto do socket. .BR getsockopt (2) e .BR setsockopt (2) são usados para setar ou obter opções da camada de socket ou do protocolo. .BR ioctl (2) pode ser usado para setar ou ler algumas outras opções. .PP .BR close (2) é usado para encerrar um socket. .BR shutdown (2) encerra partes de uma conexão de socket "full duplex". .PP A busca ou a chamada de .BR pread (2) ou .BR pwrite (2) com uma posição diferente de zero não são suportados em sockets. .PP É possível fazer IO não-bloqueável em sockets configurando-se o flag .B O_NONBLOCK em um descritor de arquivo de socket, usando .BR fcntl (2). .B O_NONBLOCK é herdado através de um accept. Então todas as operações que normalmente bloqueariam (geralmente) retornarão com .BR EAGAIN ; .BR connect (2) retorna um erro do tipo .B EINPROGRESS neste caso. O usuário pode então esperar por vários eventos, via .BR poll (2) ou .BR select (2). .PP .TS tab(:) allbox; c s s l l l. I/O events Evento:Poll flag:Ocorrência Read:POLLIN:T{ Novo dado chegou. T} Read:POLLIN:T{ Uma configuração de conexão foi completada (para sockets orientados à conexão) T} Read:POLLHUP:T{ Um pedido de desconexão foi iniciado pelo outro extremo. T} Read:POLLHUP:T{ Uma conexão foi quebrada (somente para protocolos orientados à conexão). Quando o socket é escrito, .B SIGPIPE é enviado também. T} Write:POLLOUT:T{ O socket tem espaço de buffer suficiente para escrever novos dados. T} Read/Write:T{ POLLIN| .br POLLOUT T}:T{ Um .BR connect (2) externo terminou. T} Read/Write:POLLERR:Ocorreu um erro assíncrono. Read/Write:POLLHUP:O outro extremo desligou uma direção. Exception:POLLPRI:T{ Dado urgente chegou. .B SIGURG é enviado, então. T} .\" XXX not true currently .\" It is no I/O event when the connection .\" is broken from the local end using .\" .BR shutdown (2) .\" or .\" .BR close (2) .\" . .TE .PP Uma alternativa para poll/select é deixar o kernel informar o aplicativo sobre eventos através do sinal .B SIGIO . Para isso, o flag .B FASYNC deve ser configurado em um descritor de arquivo de socket através .BR fcntl (2) , e um manipulador de sinal válido para .B SIGIO deve ser instalado via .BR sigaction (2). Veja a discussão de .I SINAIS abaixo. .SH OPÇÕES DE SOCKET Estas opções de socket podem ser configuradas pelo uso de .BR setsockopt (2) , e lidas com .BR getsockopt (2) , com o nível de socket setado em .B SOL_SOCKET para todos os sockets: .TP .B SO_KEEPALIVE Habilita o envio de mensagens "keep-alive" em sockets orientados à conexão. Espera por um integer boolean flag. .TP .B SO_OOBINLINE Se esta opção é habilitada, dados out-of-band são colocados diretamente no fluxo de dados de recepção. Caso contrário, dados out-of-band são passados apenas quando o flag .B MSG_OOB é setado durante a recepção. .\" don't document it because it can do too much harm. .\".B SO_NO_CHECK .TP .BR SO_RCVLOWAT " e " SO_SNDLOWAT Especifica o número mínimo de bytes no buffer até que a camada de socket passe os dados para o protocolo .RB ( SO_SNDLOWAT ) , ou para o usuário, ao receber um .RB ( SO_RCVLOWAT ). Estes dois valores não são alteráveis em Linux, e o tamanho de seus argumentos são sempre fixados em 1 byte. .B getsockopt é capaz de lê-los; .B setsockopt sempre retornará .BR ENOPROTOOPT . .TP .BR SO_RCVTIMEO " and " SO_SNDTIMEO Especifica os timeouts de envio ou recepção, até reportar um erro. Eles são fixados em uma configuração Linux específica para cada protocolo, e não pode ser lidos nem escritos. Suas funcionalidades podem ser emuladas usando-se .BR alarm (2) ou .BR setitimer (2). .TP .B SO_BSDCOMPAT Habilita a compatibilidade BSD bug-a-bug. Isto é usado apenas no módulo do protocolo UDP e agendado para ser removido no futuro. Se habilitado erros de ICMP recebidos de um socket UDP não serão passados para o programa do usuário. O Linux 2.0 também habilita opções de compatibilidade BSD bug-a-bug (mudança aleatória de cabeçalhos, salto do sinalizador de broadcast) para sockets raw com estas opções, mas isso foi removido no Linux 2.2. É melhor corrigir os programas do usuário do que habilitar este sinalizador. .TP .B SO_PASSCRED Habilita ou desabilita a recepção de mensagem de controle .B SCM_CREDENTIALS . Para mais informações, veja .BR unix (7). .TP .B SO_PEERCRED Retorna as credenciais do processo estrangeiro conectado a este socket. É útil somente para sockets .B PF_UNIX ; veja .BR unix (7). O argumento é uma estrutura .B ucred . Válido somente como um .BR getsockopt . .TP .B SO_BINDTODEVICE Liga este socket a um dispositivo particular, como \(lqeth0\(rq, como especificado no nome de interface passado. Se o nome é uma string vazia, ou se o comprimento da opção é zero, a ligação do dispositivo do socket é removido. A opção passada é uma string de nome de interface com comprimento variável e terminada em caractere nulo, com comprimento máximo de .BR IFNAMSIZ . Se um socket é ligado a uma interface, somente os pacotes recebidos daquela interface particular serão processados pelo socket. .TP .B SO_DEBUG Habilita o debugging do socket. Somente permitido para processos com a capabilidade .B CAP_NET_ADMIN ou com id efetivo de usuário igual a 0. .TP .B SO_REUSEADDR Indica que as regras usadas nos endereços de validação fornecidos em uma chamada de .BR bind (2) permitiriam reusar os endereços locais. Para sockets .B PF_INET isso significa que um socket pode ser ligado, exceto quando há um socket em escuta ativo ligado ao endereço. Quando o socket em escuta é ligado a .B INADDR_ANY com uma porta específica, então não é possível ligá-lo a esta porta para qualquer endereço local. .TP .B SO_TYPE Obtém o tipo de socket como um inteiro (como .BR SOCK_STREAM ). Só pode ser lido com .BR getsockopt . .TP .B SO_DONTROUTE Não envia através de um gateway, somente envia a hosts conectados diretamente. O mesmo efeito pode ser atingido pela configuração do flag .B MSG_DONTROUTE sobre uma operação de socket .BR send (2). Espera um flag booleano inteiro. .TP .B SO_BROADCAST Seta ou obtém o flag de broadcast. Quando habilitado, os sockets de datagrama recebem pacotes enviados para um endereço de broadcast, e eles têm permissão para enviar pacotes a um endereço de broadcast. Esta opção não faz efeito em sockets orientados a streams. .TP .B SO_SNDBUF Seta ou obtém o buffer máximo de envio de socket em bytes. O valor padrão é selecionado pelo sysctl .B wmem_default e o máximo valor permitido é selecionado pelo sysctl .B wmem_max . .TP .B SO_RCVBUF Seta ou obtém o máximo buffer de recepção de socket em bytes. O valor default é setado pelo sysctl .B rmem_default e o máximo valor permitido é setado pelo sysctl .B rmem_max . .TP .B SO_LINGER Seleciona ou obtém a opção .B SO_LINGER. O argumento é uma estrutura .B linger . .PP .RS .nf .ta 4n 10n 22n struct linger { int l_onoff; /* linger ativo */ int l_linger; /* quantos segundos para realizar linger */ }; .ta .fi .RE .IP Quando habilitado, um .BR close (2) ou um .BR shutdown (2) não retornarão até que todas as mensagens para o socket que estiverem enfileiradas tenham sido enviadas com sucesso, ou o timeout do linger tenha sido atingido. Caso contrário, a chamada retorna imediatamente e o fechamento ocorre em background. Quando o socket é encerrado como parte de .BR exit (2) , ele sempre realiza o linger em background. .TP .B SO_PRIORITY Seta a prioridade definida por protocolo para todos os pacotes a serem enviados sobre este socket. Os usuários de Linux usam este valor para ordenar as filas de rede: pacotes com uma prioridade maior podem ser processados primeiro, dependendo da disciplina de fila do dispositivo selecionado. Para .BR ip (7) , isto também configura o campo IP "tipo-de-serviço (TOS)" para pacotes de saída. .TP .B SO_ERROR Obtém e limpa erros de socket pendentes. Somente válido como um .BR getsockopt . Espera um inteiro. .SH SINAIS Quando se escreve para um socket orientado a conexão que foi derrubado (pela extremidade local ou pela remota), .B SIGPIPE é enviado para o processo de escrita e .B EPIPE é retornado. O sinal não é enviado quando a chamada de escrita especificou o sinalizador .B MSG_NOSIGNAL . .PP Quando pedido com o fcntl .B FIOCSETOWN ou com o ioctl .B SIOCSPGRP , .B SIGIO é enviado quando ocorre um evento de I/O. É possível usar .BR poll (2) ou .BR select (2) em um manipulador de sinal para descobrir sobre qual socket o evento ocorreu. Uma alternativa (em Linux 2.2) é configurar um sinal de realtime usando o fnctl .B F_SETSIG ; o manipulador do sinal de tempo real será chamado com o descritor de arquivo no campo .I si_fd do seu .IR siginfo_t . Veja .BR fcntl (2) para mais informações. .PP Sob certas circunstâncias (por exemplo, múltiplos processos acessando um único socket), a condição que causou o .B SIGIO pode já ter desaparecido quando o processo reagir ao sinal. Se isso acontecer, o processo deveria esperar novamente porque o Linux reenviará o sinal mais tarde. .\" .SH MENSAGENS ANCILARES .SH SYSCTLS Os sysctls de núcleo para rede de sockets podem ser acessados usando-se os arquivos .B /proc/sys/net/core/* , ou com a interface .BR sysctl (2) . .TP .B rmem_default contém a configuração padrão, em bytes, do buffer de recepção de sockets. .TP .B rmem_max contém o tamanho máximo do buffer de recepção de sockets, em bytes, que um usuário pode selecionar pelo uso da opção de socket .B SO_RCVBUF . .TP .B wmem_default contém a configuração padrão, em bytes, do buffer de envio de sockets. .TP .B wmem_max contém o tamanho máximo do buffer de recepção de sockets, em bytes, que um usuário pode setar pelo uso da opção de socket .B SO_SNDBUF . .TP .BR message_cost " and " message_burst configuram o filtro bucket de token usado para carregar o limite de mensagens de atenção causadas por eventos externos à rede. .TP .B netdev_max_backlog Número máximo de pacotes na fila global de entrada. .TP .B optmem_max Comprimento máximo dos dados ancilares e dos dados de controle do usuário, como os iovecs por socket. .\" netdev_fastroute is not documented because it is experimental .SH IOCTLS Estes ioctls podem ser acessados usando-se .BR ioctl (2): .RS .nf .IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" .fi .RE .TP .B SIOCGSTAMP Retorna um .B struct timeval com o timestamp de recepção do último pacote passado ao usuário. Isto é útil para medidas precisas do tempo de "round trip". Veja .BR setitimer (2) para uma descrição de .BR "struct timeval" . .\" .TP .BR SIOCSPGRP Seta o processo ou grupo de processos para os quais se enviam sinais .B SIGIO ou .B SIGURG quando uma operação de I/O assíncrona terminou, ou quando dados urgentes estão disponíveis. O argumento é um ponteiro para .BR pid_t . Se o argumento é positivo, envia os sinais para aquele processo. Se o argumento é negativo, envia os sinais ao grupo de processos com o id de valor absoluto do argumento. O processo só pode escolher a si mesmo ou a seu próprio grupo de processos para receber sinais, a menos que ele tenha a capabilidade .B CAP_KILL ou um UID efetivo igual a 0. .TP .B FIOASYNC Altera o flag .B O_ASYNC para habilitar ou desabilitar o modo de IO assíncrono do socket. Modo de IO assíncrono significa que o sinal .B SIGIO , ou os sinais setados com .B F_SETSIG é raised quando ocorre um novo evento de I/O. .IP O argumento é um sinalizador booleano inteiro. .\" .TP .BR SIOCGPGRP Obtém o processo corrente ou grupo de processos que recebem sinais .B SIGIO ou .B SIGURG , ou 0 quando nenhum foi configurado. .PP fcntls válidos: .TP .BR FIOCGETOWN O mesmo que o ioctl SIOCGPGRP .TP .BR FIOCSETOWN O mesmo que o ioctl SIOCSPGRP .SH NOTAS O Linux assume que metade do buffer de envio/recepção é usado para estruturas internas do kernel; portanto, os sysctls são o dobro do que podem ser observados no wire. .SH PROBLEMAS As opções de socket .B CONFIG_FILTER , .B SO_ATTACH_FILTER e .B SO_DETACH_FILTER não são documentadas. A interface sugerida para usá-las é via biblioteca libpcap. .SH VERSÕES .B SO_BINDTODEVICE foi introduzido no Linux 2.0.30. .B SO_PASSCRED é novo no Linux 2.2. Os sysctls são novos no Linux 2.2. .SH AUTORES Esta página de manual foi escrita por Andi Kleen. .SH "VEJA TAMBÉM" .BR socket (2), .BR ip (7), .BR setsockopt (2), .BR getsockopt (2), .BR packet (7), .BR ddp (7) .SH TRADUZIDO POR LDP-BR em 21/08/2000. \&\fR\&\f(CWRubens de Jesus Nogueira (tradução)\fR \&\fR\&\f(CWAndré L. Fassone Canova (revisão)\fR