NOME¶

CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - accesso a dados ancilares

SINOPSE¶

#include <sys/socket.h>

struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *msgh);
struct cmsghdr *CMSG_NXTHDR(struct msghdr *msgh, struct cmsghdr *cmsg);
size_t CMSG_ALIGN(size_t length);
size_t CMSG_SPACE(size_t length);
size_t CMSG_LEN(size_t length);
unsigned char *CMSG_DATA(struct cmsghdr *cmsg);

DESCRIÇÃO¶

Estas macros servem para criar e acessar mensagens de controle (também chamadas dados ancilares) 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 sendmsg(2) e recebidos com recvmsg(2). Veja as manpages para mais informações.

Ancillary data is a sequence of cmsghdr structures with appended data. See the specific protocol man pages for the available control message types. The maximum ancillary buffer size allowed per socket can be set using /proc/sys/net/core/optmem_max; see socket(7).

The cmsghdr structure is defined as follows:

struct cmsghdr {


    size_t cmsg_len;    /* Data byte count, including header


                           (type is socklen_t in POSIX) */


    int    cmsg_level;  /* Originating protocol */


    int    cmsg_type;   /* Protocol-specific type */
/* followed by


   unsigned char cmsg_data[]; */
};

The sequence of cmsghdr structures should never be accessed directly. Instead, use only the following macros:

• CMSG_FIRSTHDR() retorna um ponteiro para o primeiro cmsghdr do 'buffer' ancilar associado ao msghdr.
• CMSG_NXTHDR() retorna o próximo cmsghdr válido depois do cmsghdr. indicado, e retorna NULO se não houver mais espaço suficiente no 'buffer'.
• CMSG_ALIGN(), dado um tamanho, retorna-o incluindo o alinhamento requerido. Isto é uma expressão constante.
• CMSG_SPACE() retorna o número de bytes de um elemento acessório com um conteúdo do comprimento indicado. Esta expressão é constante.
• CMSG_DATA() retorna um ponteiro para os dados de um cmsghdr.
• CMSG_LEN() retorna o valor do membro cmsg_len do struct cmsghdr considerando qualquer alinhamento necessário. Ela pega o tamanho como argumento. Esta expressão é constante.

Para criar dados ancilares, inicialize o membro msg_controllen do msghdr com o comprimento do 'buffer' de mensagem de controle. Use CMSG_FIRSTHDR() no msghdr para recuperar a primeira mensagem de controle e CMSG_NEXTHDR() para as seguintes. Para cada mensagem de controle, inicialize cmsg_len (com CMSG_LEN()), e os outros cmsghdr campos e a porção de dados com CMSG_DATA(). No final, o campo msg_controllen de msghdr deve ter a soma dos comprimentos de todas as mensagens de controle CMSG_SPACE() do 'buffer'. Para mais informações sobre o msghdr, veja recvmsg(2).

When the control message buffer is too short to store all messages, the MSG_CTRUNC flag is set in the msg_flags member of the msghdr.

DE ACORDO COM¶

This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite, the IPv6 advanced API described in RFC 2292 and SUSv2. CMSG_ALIGN() is a Linux extension.

NOTAS¶

Os dados ancilares devem ser acessados apenas com as macros definidas aqui para manter a portabilidade. CMSG_ALIGN() é uma extensão linux, e deve ser evitada em programas portáveis.

No Linux, CMSG_LEN(), CMSG_DATA() e 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.

EXEMPLO¶

Este código procura a opção IP_TTL num 'buffer' ancilar recebido:

struct msghdr msgh;
struct cmsghdr *cmsg;
int *ttlptr;
int received_ttl;
/* Receber dados ancilares em msgh */
for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;


        cmsg = CMSG_NXTHDR(&msgh, cmsg)) {


    if (cmsg->cmsg_level == IPPROTO_IP


            && cmsg->cmsg_type == IP_TTL) {


        ttlptr = (int *) CMSG_DATA(cmsg);


        received_ttl = *ttlptr;


        break;


    }
}
if (cmsg == NULL) {


    /* Error: IP_TTL not enabled or small buffer or I/O error */
}

The code below passes an array of file descriptors over a UNIX domain socket using SCM_RIGHTS:

struct msghdr msg = { 0 };
struct cmsghdr *cmsg;
int myfds[NUM_FD];  /* Contains the file descriptors to pass */
int *fdptr;
char iobuf[1];
struct iovec io = {


    .iov_base = iobuf,


    .iov_len = sizeof(iobuf)
};
union {         /* Ancillary data buffer, wrapped in a union


                   in order to ensure it is suitably aligned */


    char buf[CMSG_SPACE(sizeof(myfds))];


    struct cmsghdr align;
} u;
msg.msg_iov = &io;
msg.msg_iovlen = 1;
msg.msg_control = u.buf;
msg.msg_controllen = sizeof(u.buf);
cmsg = CMSG_FIRSTHDR(&msg);
cmsg->cmsg_level = SOL_SOCKET;
cmsg->cmsg_type = SCM_RIGHTS;
cmsg->cmsg_len = CMSG_LEN(sizeof(int) * NUM_FD);
fdptr = (int *) CMSG_DATA(cmsg);    /* Initialize the payload */
memcpy(fdptr, myfds, NUM_FD * sizeof(int));

VEJA TAMBÉM¶

recvmsg(2), sendmsg(2)

RFC 2292

COLOFÃO¶

Esta página faz parte da versão 4.16 do projeto Linux man-pages. Uma descrição do projeto, informações sobre relatórios de bugs e a versão mais recente desta página podem ser encontradas em https://www.kernel.org/doc/man-pages/.

TRADUÇÃO¶

A tradução para português brasileiro desta página man foi criada por Paulo César Mendes <drpc@ism.com.br> e André Luiz Fassone <lonely_wolf@ig.com.br>

Esta tradução é uma documentação livre; leia a Licença Pública Geral GNU Versão 3 ou posterior para as condições de direitos autorais. Nenhuma responsabilidade é aceita.

Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para a lista de discussão de tradutores.