.\" This man page is Copyright (C) 1999 Andi Kleen . .\" 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 acessórios. .SH SINOPSE .B #include .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 cabeçalho */ int cmsg_level; /* protocolo original */ int cmsg_type; /* tipo protocolo-específico */ /* followed by unsigned char cmsg_data[]; */ }; .ta .fi .SH DESCRIÇÃO Estas macros servem para criar e acessar mensagens de controle (também chamadas dados acessórios) que não são parte do conteúdo do socket. Esta informação pode incluir a interface onde o pacote foi recebido, uma miscelânea de cabeçalhos raramente usados, uma descrição 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 cabeçalho adicionais tais como opções IP. Os dados são enviados com .BR sendmsg (2) e recebidos com .BR recvmsg (2). Veja as manpages para mais informações. .PP Os dados acessórios consistem numa seqüência de .B struct cmsghdr seguidas de dados adicionais, que devem ser acessadas apenas com as macros descritas nesta manpage e não diretamente. Veja os tipos de mensagens de controle nas manpages dos protocolos. O tamanho máximo 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 acessório associado ao .BR msghdr . .PP .B CMSG_NXTHDR retorna o próximo .B cmsghdr válido depois do .B cmsghdr. indicado, e retorna .B NULL se não houver mais espaço 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 número de bytes de um elemento acessório com um conteúdo do comprimento indicado. Esta expressão é 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 necessário. Esta expressão é constante. .PP Para criar dados acessórios, 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 porção 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 informações sobre o .BR msghdr , veja .BR recvmsg (2). .PP Quando o buffer de mensagens de controle não comportar todas as mensagens, o flag .B MSG_CTRUNC do .I msg_flags de .BR msghdr será ativado. .SH EXEMPLO Este código procura a opção .B IP_TTL num buffer acessório recebido: .PP .RS .nf .ta 8n 16n 32n struct msghdr msgh; struct cmsghdr *cmsg; int *ttlptr; int received_ttl; /* Receber dados acessórios 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 código abaixo transmite um array de descritores de arquivo através 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 acessórios */ 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 conteúdo: */ 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 OBSERVAÇÕES Os dados acessórios devem ser acessados apenas com as macros definidas aqui para manter a portabilidade. .B CMSG_ALIGN é uma extensão linux, e deve ser evitada em programas portáveis. .PP No linux, .BR CMSG_LEN , .BR CMSG_DATA , e .B CMSG_ALIGN são constantes (se receberem um argumento constante), e podem ser usados para declarar o tamanho de variáveis globais. Isto pode, no entanto, não ser portável. .SH DE ACORDO COM O modelo de dados acessórios segue o draft POSIX.1003.1g, 4.4BSD-Lite, a API IPv6 avançada descrita no RFC2292 e a Single Unix specification v2. .B CMSG_ALIGN é uma extensão linux. .SH VER TAMBÉM .BR sendmsg "(2), " recvmsg (2) .PP RFC 2292 .SH TRADUZIDO POR LDP-BR em 21/08/2000. \&\fR\&\f(CWPaulo César Mendes (tradução)\fR \&\fR\&\f(CWxxxxxxxxxxxxxxxxxxxxxxxxx (revisão)\fR