Provided by: manpages-pt-dev_20040726-4_all bug

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)