.\" -*- nroff -*-
.\" Don't change the first line, it tells man that we need tbl.
.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\" 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" "Pgina de Manual do Linux" "Manual do Programador Linux" 
.SH NOME
socket - interface para socket Linux
.SH SINOPSE
.B #include <sys/socket.h>
.br
.IB mysocket " = socket(int " socket_family ", int " socket_type ", int " protocol );

.SH DESCRIO
Esta pgina do manual descreve a interface de usurio para a camada de
socket de rede Linux. Os sockets compatveis com BSD
so uma interface uniforme
entre o processo do usurio e as pilhas de protocolo de rede no kernel.
Os mdulos de protocolo esto agrupados em  
.I famlias 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 informaes sobre famlias e tipos.

.SH FUNES DA CAMADA DE SOCKET
Estas funes so usadas pelo processo do usurio para enviar ou receber
pacotes, e realizar outras operaes de socket. Para mais informaes,
veja as respectivas pginas de manual.

.BR socket (2)
cria um socket,
.BR connect (2)
conecta um socket a um endereo de socket remoto,
a funo 
.BR bind (2)
liga um socket a um endereo de socket local,
.BR listen (2)
diz ao socket que novas conexes sero aceitas, e
.BR accept (2)
 usado para obter um novo socket com uma nova conexo de entrada.
.BR socketpair (2)
retorna dois sockets annimos conectados (somente implementados para
algumas famlias locais, como
.BR PF_UNIX )
.PP
.BR send (2),
.BR sendto (2),
e
.BR sendmsg (2)
enviam dados atravs 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 prontido para enviar dados.
Alm disso, as operaes padro 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 endereo local do socket e
.BR getpeername (2)
retorna o endereo remoto do socket.
.BR getsockopt (2)
e
.BR setsockopt (2)
so usados para setar ou obter opes da camada de socket ou do protocolo. 
.BR ioctl (2)
pode ser usado para setar ou ler algumas outras opes.
.PP
.BR close (2)
 usado para encerrar um socket.
.BR shutdown (2)
encerra partes de uma conexo de socket "full duplex".
.PP
A busca ou a chamada de 
.BR pread (2) 
ou 
.BR pwrite (2)
com uma posio diferente de zero no so suportados em sockets.
.PP
 possvel fazer IO no-bloquevel em sockets configurando-se o flag 
.B O_NONBLOCK
em um descritor de arquivo de socket, usando 
.BR fcntl (2).
.B O_NONBLOCK
 herdado atravs de um accept. 
Ento todas as operaes que normalmente bloqueariam (geralmente)
retornaro com
.BR EAGAIN ;
.BR connect (2) 
retorna um erro do tipo
.B EINPROGRESS
neste caso.
O usurio pode ento esperar por vrios 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:Ocorrncia
Read:POLLIN:T{
Novo dado chegou. 
T}
Read:POLLIN:T{
Uma configurao de conexo foi completada
(para sockets orientados  conexo)
T}
Read:POLLHUP:T{
Um pedido de desconexo foi iniciado pelo outro extremo. 
T}
Read:POLLHUP:T{
Uma conexo foi quebrada (somente para protocolos orientados  conexo). 
Quando o socket  escrito, 
.B SIGPIPE 
 enviado tambm.
T}
Write:POLLOUT:T{
O socket tem espao 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 assncrono.
Read/Write:POLLHUP:O outro extremo desligou uma direo.
Exception:POLLPRI:T{
Dado urgente chegou.  
.B SIGURG
 enviado, ento.
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
atravs do sinal
.B SIGIO
. Para isso, o flag 
.B FASYNC
deve ser configurado em um descritor de arquivo de socket
atravs
.BR fcntl (2)
, e um manipulador de sinal vlido para  
.B SIGIO
deve ser instalado via 
.BR sigaction (2). 
Veja a discusso de 
.I SINAIS
abaixo.
.SH OPES DE SOCKET 
Estas opes de socket podem ser configuradas pelo uso de
.BR setsockopt (2)
, e lidas com 
.BR getsockopt (2)
, com o nvel 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
 conexo. Espera por um integer boolean flag. 
.TP
.B SO_OOBINLINE
Se esta opo  habilitada, dados out-of-band so colocados diretamente no fluxo de
dados de recepo. Caso contrrio, dados out-of-band so passados apenas quando o flag
.B MSG_OOB 
 setado durante a recepo. 
.\" don't document it because it can do too much harm.
.\".B SO_NO_CHECK
.TP
.BR SO_RCVLOWAT " e " SO_SNDLOWAT
Especifica o nmero mnimo de bytes no buffer at que a camada de socket
passe os dados para o protocolo 
.RB ( SO_SNDLOWAT ) 
, ou para o usurio, ao receber um 
.RB ( SO_RCVLOWAT ).
Estes dois valores no so alterveis em Linux, e o tamanho de seus
argumentos so 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 recepo, at reportar um erro.
Eles so fixados em uma configurao Linux especfica para cada protocolo, e no 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 mdulo
do protocolo UDP e agendado para ser removido no futuro.
Se habilitado erros de ICMP recebidos de um socket UDP no sero passados
para o programa do usurio. O Linux 2.0 tambm habilita opes de compatibilidade BSD bug-a-bug
(mudana aleatria de cabealhos, salto do sinalizador de broadcast) para sockets raw
com estas opes, mas isso foi removido no Linux 2.2.  melhor corrigir
os programas do usurio do que habilitar este sinalizador.
.TP
.B SO_PASSCRED
Habilita ou desabilita a recepo de mensagem de controle 
.B SCM_CREDENTIALS
. Para mais informaes, 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 
. Vlido 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 opo  zero, a ligao do dispositivo do socket  removido.
A opo passada  uma string de nome de interface 
com comprimento varivel e terminada em caractere nulo, com comprimento mximo de 
.BR IFNAMSIZ . 
Se um socket  ligado a uma interface,
somente os pacotes recebidos daquela interface particular sero 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 usurio igual a 0.
.TP
.B SO_REUSEADDR
Indica que as regras usadas nos endereos de validao fornecidos em uma chamada de  
.BR bind (2) 
permitiriam reusar os endereos locais. Para sockets
.B PF_INET
isso
significa que um socket pode ser ligado, exceto quando h um socket
em escuta ativo ligado ao endereo. Quando o socket em escuta
 ligado a 
.B INADDR_ANY
com uma porta especfica, ento no  possvel lig-lo a esta porta para
qualquer endereo local.
.TP
.B SO_TYPE
Obtm o tipo de socket como um inteiro (como 
.BR SOCK_STREAM ). 
S pode ser lido
com 
.BR getsockopt . 
.TP
.B SO_DONTROUTE
No envia atravs de um gateway, somente envia a hosts conectados
diretamente. O mesmo efeito pode ser atingido pela configurao do flag
.B MSG_DONTROUTE
sobre uma operao de socket 
.BR send (2).
Espera um flag booleano inteiro. 
.TP
.B SO_BROADCAST
Seta ou obtm o flag de broadcast. Quando habilitado, os sockets de
datagrama recebem pacotes enviados para um endereo de broadcast, e eles
tm permisso para enviar pacotes a um endereo de broadcast.
Esta opo no faz efeito em sockets orientados a streams.
.TP
.B SO_SNDBUF 
Seta ou obtm o buffer mximo de envio de socket em bytes. O valor padro  selecionado
pelo sysctl
.B wmem_default 
e o mximo valor permitido  selecionado pelo sysctl 
.B wmem_max
.
.TP
.B SO_RCVBUF
Seta ou obtm o mximo buffer de recepo de socket em bytes. O valor
default  setado pelo sysctl
.B rmem_default 
e o mximo valor permitido  setado pelo sysctl
.B rmem_max
.   
.TP
.B SO_LINGER
Seleciona ou obtm a opo 
.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)
no retornaro 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 contrrio, 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 usurios 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 tambm configura o campo IP "tipo-de-servio (TOS)" para pacotes de sada.
.TP
.B SO_ERROR
Obtm e limpa erros de socket pendentes. Somente vlido como um
.BR getsockopt .
Espera um inteiro. 
.SH SINAIS
Quando se escreve para um socket orientado a conexo que foi derrubado
(pela extremidade local ou pela remota),  
.B SIGPIPE
 enviado para o processo de escrita e 
.B EPIPE
 retornado. 
O sinal no  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.  possvel 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 informaes.
.PP
Sob certas circunstncias (por exemplo, mltiplos processos acessando um
nico socket), a condio 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 ncleo 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
contm a configurao padro, em bytes, do buffer de recepo de sockets.
.TP
.B rmem_max
contm o tamanho mximo do buffer de recepo de sockets, em bytes, que um
usurio pode selecionar pelo uso da opo de socket
.B SO_RCVBUF
.
.TP
.B wmem_default
contm a configurao padro, em bytes, do buffer de envio de sockets.
.TP
.B wmem_max
contm o tamanho mximo do buffer de recepo de sockets, em bytes, que um
usurio pode setar pelo uso da opo 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 ateno causadas por eventos externos  rede. 
.TP
.B netdev_max_backlog 
Nmero mximo de pacotes na fila global de entrada.
.TP
.B optmem_max
Comprimento mximo dos dados ancilares e dos dados de controle do
usurio, 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 recepo do ltimo pacote passado ao usurio. Isto
 til para medidas precisas do tempo de "round trip". Veja 
.BR setitimer (2) 
para uma descrio 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 operao de
I/O assncrona terminou, ou quando dados urgentes esto disponveis.
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 prprio 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 assncrono do
socket. Modo de IO assncrono 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
Obtm o processo corrente ou grupo de processos que recebem sinais
.B SIGIO 
ou 
.B SIGURG
,
ou 0
quando nenhum foi configurado.  
.PP
fcntls vlidos:
.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/recepo  usado para
estruturas internas do kernel; portanto, os sysctls so o dobro
do que podem ser observados no wire.
.SH PROBLEMAS
As opes de socket 
.B CONFIG_FILTER 
, 
.B SO_ATTACH_FILTER 
e 
.B SO_DETACH_FILTER 
no
so documentadas. A interface sugerida para us-las  via biblioteca
libpcap.
.SH VERSES
.B SO_BINDTODEVICE 
foi introduzido no Linux 2.0.30. 
.B SO_PASSCRED 
 novo no Linux 2.2.
Os sysctls so novos no Linux 2.2. 
.SH AUTORES
Esta pgina de manual foi escrita por Andi Kleen.
.SH "VEJA TAMBM"
.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 <darkseid99@usa.net> (traduo)\fR
\&\fR\&\f(CWAndr L. Fassone Canova <lonelywolf@blv.com.br> (reviso)\fR