.\" -*- coding: UTF-8 -*-
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-1-para
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH CMSG 3 "17 Mayo 2025" "Páginas de Manual de Linux 6.15" 
.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 <sys/socket.h>\fP
.P
\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.
.P
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).
.P
La estructura \fIcmsghdr\fP se define de la siguiente manera:
.P
.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
.P
Nunca se debería acceder directamente a la secuencia de estructuras
\fIcmsghdr\fP. En su lugar, utilice las siguientes 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
Al inicializar un búfer con una serie de estructuras \fIcmsghdr\fP (por
ejemplo, para enviar con \fBsendmsg\fP(2)), dicho búfer debe inicializarse
primero a cero para garantizar el correcto funcionamiento de
\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()
Devuelve un puntero a la porción de datos de un \fIcmsghdr\fP. No se puede
asumir que el puntero devuelto esté correctamente alineado para acceder a
tipos de datos de carga útil arbitrarios. Las aplicaciones no deben
convertirlo a un tipo de puntero que coincida con la carga útil, sino que
deben usar \fBmemcpy\fP(3) para copiar datos hacia o desde un objeto declarado
correctamente.
.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.
.P
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 VERSIONES
Para facilitar la portabilidad, debería accederse a los datos auxiliares
utilizando únicamente las macros descritas aquí.
.P
En Linux, \fBCMSG_LEN\fP(), \fBCMSG_DATA\fP() y \fBCMSG_ALIGN\fP() son expresiones
constantes (suponiendo que su argumento sea constante), lo que significa que
estos valores pueden usarse para declarar el tamaño de las variables
globales. Sin embargo, esto podría no ser portable.
.SH ESTÁNDARES
.TP 
\fBCMSG_FIRSTHDR\fP()
.TQ
\fBCMSG_NXTHDR\fP()
.TQ
\fBCMSG_DATA\fP()
POSIX.1\-2008.
.TP 
\fBCMSG_SPACE\fP()
.TQ
\fBCMSG_LEN\fP()
.TQ
\fBCMSG_ALIGN\fP()
Linux.
.SH 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.
.P
.\" https://www.austingroupbugs.net/view.php?id=978#c3242
\fBCMSG_SPACE\fP() y \fBCMSG_LEN\fP() se incluirán en la próxima versión de POSIX
(Número 8).
.SH EJEMPLOS
Este código busca la opción \fBIP_TTL\fP en un buffer auxiliar recibido:
.P
.in +4n
.EX
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 pequeño o error de E/S */
}
.EE
.in
.P
El código a continuación pasa una matriz de descriptores de archivo a través
de un socket de dominio UNIX mediante \fBSCM_RIGHTS\fP:
.P
.in +4n
.EX
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));
.EE
.in
.P
Para un ejemplo de código completo que muestra el paso de descriptores de
archivo a través de un socket de dominio UNIX, consulte
\fBseccomp_unotify\fP(2).
.SH "VÉASE TAMBIÉN"
\fBrecvmsg\fP(2), \fBsendmsg\fP(2)
.P
RFC\ 2292
.PP
.SH TRADUCCIÓN
La traducción al español de esta página del manual fue creada por
Juan Piernas <piernas@ditec.um.es>
y
Marcos Fouces <marcos@debian.org>
.
.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 .