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

NOME

       CMSG_ALIGN,  CMSG_SPACE,  CMSG_NXTHDR,  CMSG_FIRSTHDR - Accesso a dados
       acessorios.

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 cabecalho */
               int         cmsg_level; /* protocolo original */
               int         cmsg_type;  /* tipo protocolo-especifico */
       /* followed by
               unsigned char           cmsg_data[]; */
       };

DESCRI,C~AO

       Estas macros servem para criar e acessar mensagens de controle  (tambem
       chamadas  dados  acessorios)  que  nao sao parte do conteudo do socket.
       Esta informacao pode incluir a interface onde o  pacote  foi  recebido,
       uma  miscelanea  de  cabecalhos raramente usados, uma descricao 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 cabecalho adicionais tais  como  opcoes  IP.   Os  dados  sao
       enviados  com  sendmsg(2) e recebidos com recvmsg(2).  Veja as manpages
       para mais informacoes.

       Os dados acessorios consistem numa sequencia de struct cmsghdr seguidas
       de  dados  adicionais,  que  devem  ser  acessadas apenas com as macros
       descritas nesta manpage e nao diretamente. Veja os tipos  de  mensagens
       de  controle  nas  manpages dos protocolos.  O tamanho maximo 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
       acessorio associado ao msghdr.

       CMSG_NXTHDR  retorna  o  proximo  cmsghdr  valido  depois  do  cmsghdr.
       indicado,  e  retorna  NULL  se  nao  houver  mais espaco suficiente no
       buffer.

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

       CMSG_SPACE  retorna  o  numero de bytes de um elemento acessorio com um
       conteudo do comprimento indicado.  Esta expressao e 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   necessario.  Esta  expressao  e
       constante.

       Para criar dados acessorios,  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  porcao  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 informacoes sobre o msghdr,
       veja recvmsg(2).

       Quando o buffer  de  mensagens  de  controle  nao  comportar  todas  as
       mensagens, o flag MSG_CTRUNC do msg_flags de msghdr sera ativado.

EXEMPLO

       Este codigo procura a opcao IP_TTL num buffer acessorio recebido:

              struct msghdr msgh;
              struct cmsghdr *cmsg;
              int *ttlptr;
              int received_ttl;

              /* Receber dados acessorios 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 codigo abaixo transmite um array de descritores de arquivo atraves 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 acessorios */
              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 conteudo: */
              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,C~OES

       Os dados acessorios devem ser acessados apenas com as macros  definidas
       aqui  para  manter a portabilidade.  CMSG_ALIGN e uma extensao linux, e
       deve ser evitada em programas portaveis.

       No  linux,  CMSG_LEN,  CMSG_DATA,  e  CMSG_ALIGN  sao  constantes   (se
       receberem  um  argumento constante), e podem ser usados para declarar o
       tamanho de variaveis globais. Isto pode, no entanto, nao ser portavel.

DE ACORDO COM

       O modelo de dados acessorios segue o draft POSIX.1003.1g,  4.4BSD-Lite,
       a  API  IPv6 avancada descrita no RFC2292 e a Single Unix specification
       v2.  CMSG_ALIGN e uma extensao linux.

VER TAMB'EM

       sendmsg(2), recvmsg(2)

       RFC 2292

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

       Paulo       Cesar       Mendes       <drpc@ism.com.br>       (traducao)
       xxxxxxxxxxxxxxxxxxxxxxxxx <xxx@xxxxxx.xxx.xx> (revisao)