.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\" 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: cmsg.3,v 1.1 2000/10/20 13:05:09 ricardo Exp $
.TH CMSG 3 "2 Oct 1998" "Linux Man Page" "Linux Programmer's Manual" 
.SH NOME
CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Accesso a dados acessrios.
.SH SINOPSE
.B #include <sys/socket.h>
.br
.sp 2
.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh ");"
.br
.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg ");"
.br
.BI "size_t CMSG_ALIGN(size_t " length ");"
.br
.BI "size_t CMSG_SPACE(size_t " length ");"
.br
.BI "size_t CMSG_LEN(size_t " length ");"
.br
.BI "void *CMSG_DATA(struct cmsghdr *" cmsg ");"       
.sp
.nf
.ta 8n 20n 32n
struct cmsghdr {
	socklen_t	cmsg_len;	/* total de bytes de dados, incluindo o cabealho */
	int	cmsg_level;	/* protocolo original */
	int	cmsg_type;	/* tipo protocolo-especfico */
/* followed by
	unsigned char	cmsg_data[]; */
};
.ta
.fi
.SH DESCRIO
Estas macros servem para criar e acessar mensagens de controle (tambm chamadas
dados acessrios) que no so parte do contedo do socket.
Esta informao pode incluir a interface onde o pacote foi recebido, uma miscelnea
de cabealhos raramente usados, uma descrio de erro mais detalhada, um conjunto de
descritores de arquivo ou credenciais unix. Por exemplo, pode se usar mensagens de
controle para enviar campos de cabealho adicionais tais como opes IP.
Os dados so enviados com
.BR sendmsg (2)
e recebidos com
.BR recvmsg (2).
Veja as manpages para mais informaes. 
.PP
Os dados acessrios consistem numa seqncia de 
.B struct cmsghdr 
seguidas de dados adicionais, que devem ser acessadas apenas com as macros descritas nesta
manpage e no diretamente. Veja os tipos de mensagens de controle nas manpages dos protocolos.
O tamanho mximo do buffer auxiliar do socket pode ser definido com
.B net.core.optmem_max
do sysctl. Ver
.BR socket (7).  
.PP
.B CMSG_FIRSTHDR 
retorna um ponteiro para o primeiro
.B cmsghdr 
do buffer acessrio associado ao
.BR msghdr .
.PP
.B CMSG_NXTHDR 
retorna o prximo
.B cmsghdr 
vlido depois do
.B cmsghdr. 
indicado, e retorna
.B NULL 
se no houver mais espao suficiente no buffer.
.PP
.BR CMSG_ALIGN ,
given a length, returns it including the required alignment. This is a 
constant expression.
.PP
.B CMSG_SPACE
retorna o nmero de bytes de um elemento acessrio com um contedo do comprimento indicado.
Esta expresso  constante.
.PP
.B CMSG_DATA
retorna um ponteiro para os dados de um
.BR cmsghdr . 
.PP
.B CMSG_LEN
retorna o valor do membro
.I cmsg_len
do struct
.B cmsghdr 
considerando qualquer alinhamento necessrio. Esta expresso  constante.
.PP
Para criar dados acessrios, inicialize o membro
.I msg_controllen
do
.B msghdr 
com o comprimento do buffer de mensagem de controle. Use
.B CMSG_FIRSTHDR 
no
.B msghdr 
para recuperar a primeira mensagem de controle e
.B CMSG_NEXTHDR
para as seguintes.
Para cada mensagem de controle, inicialize
.I cmsg_len
(com 
.BR CMSG_LEN ), 
e os outros campos e a poro de dados de
.B cmsghdr 
com
.BR CMSG_DATA .
No final, coloque a soma dos comprimentos de todas as mensagens de controle
(dados em
.B CMSG_SPACE )
no campo
.I msg_controllen 
do
.B msghdr 
Para mais informaes sobre o
.BR msghdr ,
veja
.BR recvmsg (2). 
.PP
Quando o buffer de mensagens de controle no comportar todas as mensagens,
o flag
.B MSG_CTRUNC 
do
.I msg_flags 
de
.BR msghdr 
ser ativado.
.SH EXEMPLO
Este cdigo procura a opo
.B IP_TTL 
num buffer acessrio recebido:
.PP
.RS
.nf
.ta 8n 16n 32n
struct msghdr msgh; 
struct cmsghdr *cmsg;
int *ttlptr;
int received_ttl;

/* Receber dados acessrios em msgh */ 
for (cmsg = CMSG_FIRSTHDR(&msgh); 
     cmsg != NULL; 
     cmsg = CMSG_NXTHDR(&msgh,cmsg) {
	if (cmsg->cmsg_level == SOL_IP 
	  && cmsg->cmsg_type == IP_TTL) { 
		ttlptr = (int *) CMSG_DATA(cmsg);
		received_ttl = *ttlptr; 
		break;
	}
}
if (cmsg == NULL) {
	/* Erro: IP_TTL desabilitado ou buffer muito curto
	 * ou erro de I/O .
	 */ 
} 
.ta
.fi
.RE
.PP
O cdigo abaixo transmite um array de descritores de arquivo atravs de um socket Unix usando
.BR SCM_RIGHTS :
.PP
.RS
.nf
.ta 8n 16n 32n
struct msghdr msg = {0};
struct cmsghdr *cmsg;
int myfds[NUM_FD]; /* Descritores de arquivo a transmitir. */ 
char buf[CMSG_SPACE(sizeof myfds)];  /* buffer de dados acessrios */
int *fdptr;

msg.msg_control = buf; 
msg.msg_controllen = sizeof buf;
cmsg = CMSG_FIRSTHDR(&msg); 
cmsg->cmsg_level = SOL_SOCKET;
cmsg->cmsg_type = SCM_RIGHTS;
cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD); 
/* Inicializar o contedo: */ 
fdptr = (int *)CMSG_DATA(cmsg); 
memcpy(fdptr, myfds, NUM_FD * sizeof(int)); 
/* Soma dos comprimentos de todas as mensagens de controle no buffer: */
msg.msg_controllen = cmsg->cmsg_len;
.ta
.fi
.RE
.SH OBSERVAES
Os dados acessrios devem ser acessados apenas com as macros definidas aqui
para manter a portabilidade.
.B CMSG_ALIGN
 uma extenso linux, e deve ser evitada em programas portveis.
.PP
No linux,
.BR CMSG_LEN , 
.BR CMSG_DATA ,
e
.B CMSG_ALIGN
so constantes (se receberem um argumento constante), e podem ser usados
para declarar o tamanho de variveis globais. Isto pode, no entanto, no ser
portvel.
.SH DE ACORDO COM
O modelo de dados acessrios segue o draft POSIX.1003.1g, 4.4BSD-Lite, a API IPv6
avanada descrita no RFC2292 e a Single Unix specification v2.
.B
CMSG_ALIGN 
 uma extenso linux. 
.SH VER TAMBM
.BR sendmsg "(2), " recvmsg (2)
.PP
RFC 2292
.SH TRADUZIDO POR LDP-BR em 21/08/2000.
\&\fR\&\f(CWPaulo Csar Mendes <drpc@ism.com.br> (traduo)\fR
\&\fR\&\f(CWxxxxxxxxxxxxxxxxxxxxxxxxx <xxx@xxxxxx.xxx.xx> (reviso)\fR