.\" -*- nroff -*-
.\" Don't change the first line, it tells man that tbl is needed.
.\" This man page copyright 1998 by Andi Kleen. Subject to the GPL.
.\" This manpage copyright 1998 by Andi Kleen. Subject to the GPL.
.\" Based on the original comments from Alexey Kuznetsov
.\" $Id: netlink.7,v 1.1 2000/10/20 13:05:11 ricardo Exp $
.TH NETLINK  7 "27/04/1999" "Pgina de Manual do Linux" "Manual do Programador Linux"
.SH NOME
netlink, PF_NETLINK \- Comunicao entre o kernel e o usurio.
.SH SINOPSE
.nf
.\" XXX
.B #include <asm/types.h>
.br
.B #include <sys/socket.h>
.br
.B #include <linux/netlink.h> 
.br
.PP
.BI "netlink_socket = socket(PF_NETLINK, " socket_type ", " netlink_family ); 
.SH DESCRIPTION
Netlink  usado para transferir informao entre mdulos do kernel e processos do espao do usurio.
Consiste de uma interface padro baseada em sockets, para processos de usurio
e uma API interna do kernel para mdulos. A interface interna do kernel no 
documentada nesta pgina do manual. H tambm uma interface netlink obsoleta, via
dispositivos de caracteres netlink, esta interface no  documentada aqui e s
 fornecida para retro-compatibilidade.

Netlink  um servio orientado a datagrama. Tanto
.B SOCK_RAW 
quanto 
.B SOCK_DGRAM
so valores vlidos para
.IR socket_type ;
porm, o protocolo netlink no distingue entre
datagramas e sockets diretos.

.I netlink_family
seleciona o mdulo do kernel ou grupo de netlink para se comunicar. 
As famlias de netlink atribudas atualmente so:
.TP
.B NETLINK_ROUTE
Recebe atualizaes de roteamento e pode ser usado para modificar a tabela
de roteamento IPv4 (veja
.BR rtnetlink (7)).
.TP
.B NETLINK_FIREWALL 
Recebe pacotes enviados pelo cdigo do firewall IPv4.
.TP
.B NETLINK_ARPD
Para gerenciamento da tabela arp no espao do usurio.
.TP
.B NETLINK_ROUTE6
Recebe e envia atualizaes da tabela de roteamento IPv6.
.TP
.B NETLINK_IP6_FW
recebe pacotes que falharam nas checagens do firewall IPv6 (no
implementado correntemente).
.TP
.BR NETLINK_TAPBASE ... NETLINK_TAPBASE+15
so as instncias do dispositivo
.B ethertap. 
Ethertap  um pseudo-dispositivo de tnel de rede que permite a um driver 
ethernet ser simulado a partir do espao do usurio.
.TP
.B NETLINK_SKIP
Reservado para ENskip.
.TP
.B NETLINK_USERSOCK
 reservado para futuros protocolos do espao do usurio.
.PP
Mensagens do netlink consistem de uma seqncia de bytes com um ou vrios cabealhos  
.B nlmsghdr
, e "payload" associado.
Para mensagens multipartes, o primeiro cabealho e todos os seguintes tm o sinalizador
.B NLM_F_MULTI
setado, exceto pelo ltimo cabealho,
que tem o tipo
.BR NLMSG_DONE .
A seqncia de bytes deveria ser acessada somente com as macros 
.B NLMSG_*
padres, veja
.BR netlink (3). 

Netlink no  um protocolo confivel. Ele tenta fazer o melhor para entregar uma
mensagem a seu(s) destinatrio(s), mas pode perder mensagens quando ocorre uma
condio de falta de memria, ou outra. Para transferncia segura, o remetente
pode requerer um reconhecimento do receptor, atravs da configurao do sinalizador 
.B NLM_F_ACK.
Um reconhecimento  um pacote
.B NLMSG_ERROR 
com o campo de erro setado para 0. A aplicao deve gerar acks para as
prprias mensagens recebidas. O kernel tenta enviar uma mensagem
.B NLMSG_ERROR
para todos os pacotes falhos. Um processo de usurio tambm deveria seguir esta conveno.

Cada famlia de netlink tem um conjunto de 32 grupos de multicast.
Quando 
.BR bind (2)
 chamado no socket, o campo
.B nl_groups
no
.B sockaddr_nl
deveria ser setado para uma mscara de bits do grupo que ele deseja ouvir.
O valor padro para este campo  zero, o que significa que nenhum multicast
ser reebido.
Um socket podem realizar o multicast de mensagens para qualquer um dos grupos de multicast, atravs da configurao de 
.B nl_groups
para uma mscara de bits dos grupos para os quais ele deseja enviar, quando ele chama
.BR sendmsg (2)
ou executa um
.BR connect (2).
Somente usurios com uid efetivo igual a 0 ou a capabilidade
.B CAP_NET_ADMIN
podem enviar ou escutar um
grupo de multicast netlink.
Qualquer resposta a uma mensagem recebida de um grupo de multicast
deveria ser enviada de volta ao pid remetente e ao grupo de multicast. 

.RS
.nf
.ta 4 13 25
struct nlmsghdr
{
	__u32	nlmsg_len;	/* Comprimento da mensagem incluindo cabealho */
	__u16	nlmsg_type;	/* Contedo da mensagem */
	__u16	nlmsg_flags;	/* Flags adicionais */
	__u32	nlmsg_seq;	/* Nmero de seqncia */
	__u32	nlmsg_pid;	/* PID de envio de processo */
};


struct nlmsgerr
{
	int	error;	/* errno negativo, ou 0 para acks. */ 
	struct nlmsghdr msg;	/* cabealho da mensagem que causou o erro */ 
};
.ta
.fi
.RE

Depois de cada
.B nlmsghdr
o "payload" se segue. 
.B nlmsg_type
pode ser um dos tipos de mensagem padro: 
.B NLMSG_NOOP
mensagem deve ser ignorada,
.B NLMSG_ERROR
a mensagem sinaliza um erro e o "payload" contm uma estrutura 
.I nlmsgerr 
,
.B NLMSG_DONE
mensagem encerra uma mensagem multiparte,
.\" 2.1.130 does not seem to use it.
.\" .B NLMSG_OVERRUN
.\" data was lost. 

Uma famlia netlink geralmente especifica mais tipos de mensagem, veja
a pgina de manual apropriada para isso, por exemplo 
.BR rtnetlink (7)
para 
.IR NETLINK_ROUTE .

.TS 
tab(:); 
l s 
l l.
Bits de Flag Padro em nlmsg_flags
NLM_F_REQUEST:setado em todas as mensagens de pedido
NLM_F_MULTI:T{
a mensagem  parte de uma mensagem multipart terminada por 
.B 
NLMSG_DONE
.\" XXX describe that
T}
NLM_F_ACK:responde com um reconhecimento se bem-sucedido
NLM_F_ECHO:ecoa este pedido
.TE

.TS
tab(:);
l s 
l l.
Bits adicionais de flag para pedidos GET
NLM_F_ROOT:Retorna a tabela completa em vez de uma entrada nica.
NLM_F_MATCH:Ainda no implementado. 
NLM_F_ATOMIC:Retorna um snapshot atmico da tabela.
NLM_F_DUMP:Ainda no documentado.
.TE

.TS
tab(:);
l s
l l.
Bits adicionais de flag para pedidos NEW
NLM_F_REPLACE:Sobrepe objeto existente.
NLM_F_EXCL:No substitui se o objeto j existe.
NLM_F_CREATE:Cria objeto se ele ainda no existe.
NLM_F_APPEND:Acrescenta ao fim da lista de objetos.
.TE

Note que NLM_F_ATOMIC requer CAP_NET_ADMIN ou direitos de super usurio.

.SH FORMATOS DE ENDEREO
A estrutura 
.B sockaddr_nl
descreve um cliente netlink no espao do usurio no kernel.
Um sockaddr_nl pode ser unicast (somente envia para um peer) ou
enviar para grupos de netlink (nl_groups diferente de 0). 

.RS
.nf
struct sockaddr_nl
{
    sa_family_t nl_family;    /* AF_NETLINK */
    unsigned short nl_pad;    /* zero */
    pid_t       nl_pid;       /* pid do processo */
    __u32       nl_groups;    /* mscara dos grupos de multicast */
};
.fi
.RE

.B nl_pid 
 o pid do netlink do espao do usurio, ou 0 se o destino est no
kernel. 
.B nl_groups 
 uma mscara de bits, com cada bit representando um nmero de grupo de netlink.
.\" XXX describe what that is. 


.SH PROBLEMAS
Esta pgina de manual no est completa. 

.SH NOTAS
Freqentemente  melhor usar netlink via 
.B libnetlink
do que via interface de kernel de baixo nvel.

.SH VERSES
A interface de socket para netlink  uma realizao nova no Linux 2.2

O Linux 2.0 suporta uma interface netlink baseada em um dispositivo mais
primitivo (que ainda est disponvel como uma opo de
compatibilidade). Esta interface obsoleta no  descrita aqui. 

.SH VEJA TAMBM
.BR cmsg (3),
.BR rtnetlink (7),
.BR netlink (3).
.PP
.BR ftp://ftp.inr.ac.ru/ip-routing/iproute2* 
para libnetlink
.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