CMSG(3) Library Functions Manual CMSG(3) NOMBRE CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR - acceso a datos auxiliares BIBLIOTECA Biblioteca Estandar C (libc, -lc) SINOPSIS #include 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); DESCRIPCION Estas macros se usan para crear y acceder a mensajes de control (tambien llamados datos auxiliares) que no son parte del contenido util de un conector. Esta informacion de control puede incluir la interfaz en la que se ha recibido el paquete, diferentes campos de cabecera usados raramente, una descripcion 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 envian llamando a sendmsg(2) y se reciben llamando a recvmsg(2). Vea sus paginas de manual para mas informacion. Los datos auxiliares son una secuencia de estructuras cmsghdr con datos anadidos. Vea las paginas de manual especificas del protocolo para conocer los tipos de mensajes de control disponibles. El tamano maximo permitido del buffer auxiliar por conector se puede configura con /proc/sys/net/core/optmem_max. Vea socket(7). La estructura cmsghdr se define de la siguiente manera: 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 especifico de protocol */ /* Seguido por unsigned char cmsg_data[]; */ }; Nunca se deberia acceder directamente a la secuencia de estructuras cmsghdr. En su lugar, utilice las siguientes macros: CMSG_FIRSTHDR() devuelve un puntero a la primera cmsghdr en el buffer de datos auxiliares asociado con la msghdr pasada. Devolvera NULL si no se dispone de suficiente espacio para una cmsghdr en el buffer. CMSG_NXTHDR() devuelve la siguiente cmsghdr valida despues de la cmsghdr pasada. Devuelve NULL cuando no queda suficiente espacio en el buffer. Al inicializar un bufer con una serie de estructuras cmsghdr (por ejemplo, para enviar con sendmsg(2)), dicho bufer debe inicializarse primero a cero para garantizar el correcto funcionamiento de CMSG_NXTHDR(). CMSG_ALIGN(), CMSG_ALIGN(), dada una longitud, la devuelve incluyendo la alineacion necesaria. Esta es una expresion constante. CMSG_SPACE() devuelve la cantidad de bytes que ocupa un elemento auxiliar cuyo contenido util es de la longitud de datos pasada. Esta es una expresion constante. CMSG_DATA() Devuelve un puntero a la porcion de datos de un cmsghdr. No se puede asumir que el puntero devuelto este correctamente alineado para acceder a tipos de datos de carga util arbitrarios. Las aplicaciones no deben convertirlo a un tipo de puntero que coincida con la carga util, sino que deben usar memcpy(3) para copiar datos hacia o desde un objeto declarado correctamente. CMSG_LEN() devuelve el valor a almacenar en el miembro cmsg_len de la estructura cmsghdr teniendo en cuenta cualquier alineacion necesaria. Toma como argumento la longitud de los datos. Esta es una expresion constante. Para crear datos auxiliares, inicialice primero el miembro msg_controllen de la estructura msghdr con el tamano del buffer de mensajes de control. Use CMSG_FIRSTHDR() sobre msghdr para obtener el primer mensaje de control y CMSG_NXTHDR() para obtener los siguientes. En cada mensaje de control, inicialice cmsg_len (con CMSG_LEN()), los otros campos cabecera de cmsghdr y la parte de datos usando CMSG_DATA(). Finalmente, deberia asignar al campo msg_controllen de msghdr la suma de los CMSG_SPACE() de las longitudes de todos los mensajes de control del buffer. Para mas informacion sobre msghdr, vea recvmsg(2). VERSIONES Para facilitar la portabilidad, deberia accederse a los datos auxiliares utilizando unicamente las macros descritas aqui. En Linux, CMSG_LEN(), CMSG_DATA() y CMSG_ALIGN() son expresiones constantes (suponiendo que su argumento sea constante), lo que significa que estos valores pueden usarse para declarar el tamano de las variables globales. Sin embargo, esto podria no ser portable. ESTANDARES CMSG_FIRSTHDR() CMSG_NXTHDR() CMSG_DATA() POSIX.1-2008. CMSG_SPACE() CMSG_LEN() CMSG_ALIGN() Linux. HISTORIAL Este modelo de datos auxiliares cumple con el borrador POSIX.1g, 4.4BSD-Lite, la API avanzada de IPv6 descrita en RFC 2292 y SUSv2. CMSG_SPACE() y CMSG_LEN() se incluiran en la proxima version de POSIX (Numero 8). EJEMPLOS Este codigo busca la opcion IP_TTL en un buffer auxiliar recibido: struct msghdr msgh; struct cmsghdr *cmsg; int received_ttl; /* Recibe 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: IP_TTL no activado, buffer muy pequeno o error de E/S */ } El codigo a continuacion pasa una matriz de descriptores de archivo a traves de un socket de dominio UNIX mediante SCM_RIGHTS: struct msghdr msg = { 0 }; struct cmsghdr *cmsg; int myfds[NUM_FD]; /* Contiene los descriptores de archivo a pasar */ 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)); Para un ejemplo de codigo completo que muestra el paso de descriptores de archivo a traves de un socket de dominio UNIX, consulte seccomp_unotify(2). VEASE TAMBIEN recvmsg(2), sendmsg(2) RFC 2292 TRADUCCION La traduccion al espanol de esta pagina del manual fue creada por Juan Piernas y Marcos Fouces Esta traduccion es documentacion libre; lea la GNU General Public License Version 3 o posterior con respecto a las condiciones de copyright. No existe NINGUNA RESPONSABILIDAD. Si encuentra algun error en la traduccion de esta pagina del manual, envie un correo electronico a . Paginas de Manual de Linux 6.15 17 Mayo 2025 CMSG(3)