NOME

       CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - Accesso a dados acessórios.

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);
       void *CMSG_DATA(struct cmsghdr *cmsg);

       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[]; */
       };

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 sendmsg(2) e recebidos com
       recvmsg(2).  Veja as manpages para mais informações.

       Os dados acessórios consistem numa seqüência de 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 net.core.optmem_max do sysctl. Ver socket(7).

       CMSG_FIRSTHDR retorna um ponteiro para o primeiro cmsghdr do buffer acessório associado ao msghdr.

       CMSG_NXTHDR retorna o próximo cmsghdr válido depois do cmsghdr.  indicado, e retorna NULL se  não  houver
       mais espaço suficiente no buffer.

       CMSG_ALIGN, given a length, returns it including the required alignment. This is a constant expression.

       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. Esta expressão é constante.

       Para  criar dados acessórios, 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 campos e a porção de dados de cmsghdr com CMSG_DATA.  No final, coloque a soma dos comprimentos de
       todas  as  mensagens  de  controle  (dados  em  CMSG_SPACE  ) no campo msg_controllen do msghdr Para mais
       informações sobre o msghdr, veja recvmsg(2).

       Quando o buffer de mensagens de controle não comportar todas as mensagens, o flag MSG_CTRUNC do msg_flags
       de msghdr será ativado.

EXEMPLO

       Este código procura a opção IP_TTL num buffer acessório recebido:

              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 .
                       */
              }

       O código abaixo transmite um array de descritores de arquivo através de um socket Unix usando SCM_RIGHTS:

              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;

OBSERVAÇÕES

       Os dados acessórios 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.

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.  CMSG_ALIGN é uma extensão linux.

VER TAMBÉM

       sendmsg(2), recvmsg(2)

       RFC 2292

TRADUZIDO POR LDP-BR em 21/08/2000.

       Paulo César Mendes <drpc@ism.com.br> (tradução) xxxxxxxxxxxxxxxxxxxxxxxxx <xxx@xxxxxx.xxx.xx> (revisão)

Linux Man Page                                     2 Oct 1998                                            CMSG(3)