.\" -*- coding: UTF-8 -*- .\" This man page is Copyright (C) 1999 Andi Kleen . .\" .\" %%%LICENSE_START(VERBATIM_ONE_PARA) .\" 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. .\" %%%LICENSE_END .\" .\" $Id: cmsg.3,v 1.8 2000/12/20 18:10:31 ak Exp $ .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH CMSG 3 "29 Octubre 2022" "Páginas de manual de Linux 6.03" .SH NOMBRE CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- acceso a datos auxiliares .SH BIBLIOTECA Biblioteca Estándar C (\fIlibc\fP, \fI\-lc\fP) .SH SINOPSIS .nf \fB#include \fP .PP \fBstruct cmsghdr *CMSG_FIRSTHDR(struct msghdr *\fP\fImsgh\fP\fB);\fP \fBstruct cmsghdr *CMSG_NXTHDR(struct msghdr *\fP\fImsgh\fP\fB,\fP \fB struct cmsghdr *\fPcmsg\fB);\fP \fBsize_t CMSG_ALIGN(size_t \fP\fIlength\fP\fB);\fP \fBsize_t CMSG_SPACE(size_t \fP\fIlength\fP\fB);\fP \fBsize_t CMSG_LEN(size_t \fP\fIlength\fP\fB);\fP \fBunsigned char *CMSG_DATA(struct cmsghdr *\fP\fIcmsg\fP\fB);\fP .fi .SH DESCRIPCIÓN Estas macros se usan para crear y acceder a mensajes de control (también llamados datos auxiliares) que no son parte del contenido útil de un conector. Esta información de control puede incluir la interfaz en la que se ha recibido el paquete, diferentes campos de cabecera usados raramente, una descripción de error ampliada, un conjunto de descriptores de fichero o credenciales de UNIX. Por ejemplo, los mensajes de control se pueden usar para enviar campos de cabecera adicionales tales como opciones IP. Los datos auxiliares se envían llamando a \fBsendmsg\fP(2) y se reciben llamando a \fBrecvmsg\fP(2). Vea sus páginas de manual para más información. .PP Los datos auxiliares son una secuencia de estructuras \fIcmsghdr\fP con datos añadidos. Vea las páginas de manual específicas del protocolo para conocer los tipos de mensajes de control disponibles. El tamaño máximo permitido del buffer auxiliar por conector se puede configura con \fI/proc/sys/net/core/optmem_max\fP. Vea \fBsocket\fP(7). .PP The \fIcmsghdr\fP structure is defined as follows: .PP .in +4n .EX struct cmsghdr { size_t cmsg_len; /* recuento de byte de datos incluyendo cabeceras (el tipo en POSIX es socklen_t) */ int cmsg_level; /* Protocolo origen */ int cmsg_type; /* tipo específico de protocol */ /* Seguido por unsigned char cmsg_data[]; */ }; .EE .in .PP The sequence of \fIcmsghdr\fP structures should never be accessed directly. Instead, use only the following macros: .TP \fBCMSG_FIRSTHDR\fP() devuelve un puntero a la primera \fBcmsghdr\fP en el buffer de datos auxiliares asociado con la \fBmsghdr\fP pasada. Devolverá NULL si no se dispone de suficiente espacio para una \fIcmsghdr\fP en el buffer. .TP \fBCMSG_NXTHDR\fP() devuelve la siguiente \fBcmsghdr\fP válida después de la \fIcmsghdr\fP pasada. Devuelve NULL cuando no queda suficiente espacio en el buffer. .IP When initializing a buffer that will contain a series of \fIcmsghdr\fP structures (e.g., to be sent with \fBsendmsg\fP(2)), that buffer should first be zero\-initialized to ensure the correct operation of \fBCMSG_NXTHDR\fP(). .TP \fBCMSG_ALIGN\fP(), \fBCMSG_ALIGN\fP(), dada una longitud, la devuelve incluyendo la alíneación necesaria. Ésta es una expresión constante. .TP \fBCMSG_SPACE\fP() devuelve la cantidad de bytes que ocupa un elemento auxiliar cuyo contenido útil es de la longitud de datos pasada. Ésta es una expresión constante. .TP \fBCMSG_DATA\fP() returns a pointer to the data portion of a \fIcmsghdr\fP. The pointer returned cannot be assumed to be suitably aligned for accessing arbitrary payload data types. Applications should not cast it to a pointer type matching the payload, but should instead use \fBmemcpy\fP(3) to copy data to or from a suitably declared object. .TP \fBCMSG_LEN\fP() devuelve el valor a almacenar en el miembro \fIcmsg_len\fP de la estructura \fIcmsghdr\fP teniendo en cuenta cualquier alíneación necesaria. Toma como argumento la longitud de los datos. Ésta es una expresión constante. .PP Para crear datos auxiliares, inicialice primero el miembro \fImsg_controllen\fP de la estructura \fImsghdr\fP con el tamaño del buffer de mensajes de control. Use \fBCMSG_FIRSTHDR\fP() sobre \fImsghdr\fP para obtener el primer mensaje de control y \fBCMSG_NXTHDR\fP() para obtener los siguientes. En cada mensaje de control, inicialice \fIcmsg_len\fP (con \fBCMSG_LEN\fP()), los otros campos cabecera de \fIcmsghdr\fP y la parte de datos usando \fBCMSG_DATA\fP(). Finalmente, debería asignar al campo \fImsg_controllen\fP de \fImsghdr\fP la suma de los \fBCMSG_SPACE\fP() de las longitudes de todos los mensajes de control del buffer. Para más información sobre \fImsghdr\fP, vea \fBrecvmsg\fP(2). .SH ESTÁNDARES .\" https://www.austingroupbugs.net/view.php?id=978#c3242 This ancillary data model conforms to the POSIX.1g draft, 4.4BSD\-Lite, the IPv6 advanced API described in RFC\ 2292 and SUSv2. \fBCMSG_FIRSTHDR\fP(), \fBCMSG_NXTHDR\fP(), and \fBCMSG_DATA\fP() are specified in POSIX.1\-2008. \fBCMSG_SPACE\fP() and \fBCMSG_LEN\fP() will be included in the next POSIX release (Issue 8). .PP \fBCMSG_ALIGN\fP() es una extensión de Linux. .SH NOTAS Para transportabilidad, sólo se debería acceder a los datos auxiliares usando las macros descritas aquí. \fBCMSG_ALIGN\fP() es una extensión de Linux y no debería usarse en programas transportables. .PP In Linux, \fBCMSG_LEN\fP(), \fBCMSG_DATA\fP(), and \fBCMSG_ALIGN\fP() are constant expressions (assuming their argument is constant), meaning that these values can be used to declare the size of global variables. This may not be portable, however. .SH EJEMPLOS Este código busca la opción \fBIP_TTL\fP en un buffer auxiliar recibido: .PP .in +4n .EX struct msghdr msgh; struct cmsghdr *cmsg; int received_ttl; /* Recibir los datos auxiliares en msgh */ for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL; cmsg = CMSG_NXTHDR(&msgh, cmsg)) { if (cmsg\->cmsg_level == IPPROTO_IP && cmsg\->cmsg_type == IP_TTL) { memcpy(&receive_ttl, CMSG_DATA(cmsg), sizeof(received_ttl)); break; } } if (cmsg == NULL) { /* Error: Error: IP_TTL no habilitada o buffer pequeño o error de E/S. */ } .EE .in .PP The code below passes an array of file descriptors over a UNIX domain socket using \fBSCM_RIGHTS\fP: .PP .in +4n .EX struct msghdr msg = { 0 }; struct cmsghdr *cmsg; int myfds[NUM_FD]; /* Contains the file descriptors to pass */ 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(myfds)); memcpy(CMSG_DATA(cmsg), myfds, sizeof(myfds)); .EE .in .PP For a complete code example that shows passing of file descriptors over a UNIX domain socket, see \fBseccomp_unotify\fP(2). .SH "VÉASE TAMBIÉN" \fBrecvmsg\fP(2), \fBsendmsg\fP(2) .PP RFC\ 2292 .PP .SH TRADUCCIÓN La traducción al español de esta página del manual fue creada por Juan Piernas y Marcos Fouces . .PP Esta traducción es documentación libre; lea la .UR https://www.gnu.org/licenses/gpl-3.0.html GNU General Public License Version 3 .UE o posterior con respecto a las condiciones de copyright. No existe NINGUNA RESPONSABILIDAD. .PP Si encuentra algún error en la traducción de esta página del manual, envíe un correo electrónico a .MT debian-l10n-spanish@lists.debian.org .ME .