(split) Apply minor changes from v3.32 to v3.35 in the upstream.

[linuxjm/LDP_man-pages.git] / release / man3 / cmsg.3

.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
.\" 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.
.\" $Id: cmsg.3,v 1.3 2001/01/14 05:30:39 hanataka Exp $
.\"
.\" Japanese Version Copyright (c) 1999 Shouichi Saito
.\"     all rights reserved.
.\" Translated Mon Jul 26 21:58:26 JST 1999
.\"     by Shouichi Saito <ss236rx@ymg.urban.ne.jp>
.\" Proofed Tue Aug 17 1999 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
.\"
.TH CMSG 3 2008-11-20 "Linux" "Linux Programmer's Manual"
.SH ̾Á°
CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Êä½õ¥Ç¡¼¥¿¤Ë¥¢¥¯¥»¥¹¤¹¤ë¡£
.SH ½ñ¼°
.B #include <sys/socket.h>
.sp
.BI "struct cmsghdr *CMSG_FIRSTHDR(struct msghdr *" msgh );
.br
.BI "struct cmsghdr *CMSG_NXTHDR(struct msghdr *" msgh ", struct cmsghdr *" cmsg );
.br
.BI "size_t CMSG_ALIGN(size_t " length );
.br
.BI "size_t CMSG_SPACE(size_t " length );
.br
.BI "size_t CMSG_LEN(size_t " length );
.br
.BI "unsigned char *CMSG_DATA(struct cmsghdr *" cmsg );
.sp
.nf
struct cmsghdr {
    socklen_t cmsg_len;    /* data byte count, including header */
    int       cmsg_level;  /* originating protocol */
    int       cmsg_type;   /* protocol-specific type */
    /* followed by unsigned char cmsg_data[]; */
};
.fi
.SH ÀâÌÀ
¤³¤ì¤é¤Î¥Þ¥¯¥í¤ÏÀ©¸æ¥á¥Ã¥»¡¼¥¸
(Êä½õ¥Ç¡¼¥¿ (ancillary data) ¤È¤â¸Æ¤Ð¤ì¤ë) ¤òºî¤ê¡¢
¤½¤ì¤Ë¥¢¥¯¥»¥¹¤¹¤ë¤¿¤á¤Ë»È¤ï¤ì¤ë¡£
À©¸æ¥á¥Ã¥»¡¼¥¸¤Ï¥½¥±¥Ã¥È¤Ë¤Î¤ë¥Ç¡¼¥¿¤Ç¤Ï¤Ê¤¤¡£
¤³¤ÎÀ©¸æ¾ðÊó¤Ï¡¢ÅþÃ夷¤¿¥Ñ¥±¥Ã¥È¤Ø¤Î¥¤¥ó¥¿¡¼¥Õ¥§¥¤¥¹¡¢ÍÍ¡¹¤Ê¤¢¤Þ¤ê
»È¤ï¤ì¤Ê¤¤¥Ø¥Ã¥À¡¼¥Õ¥£¡¼¥ë¥É¡¢¥¨¥é¡¼µ­½Ò¤Î³ÈÄ¥¡¢¥Õ¥¡¥¤¥ë¥Ç¥¹¥¯¥ê
¥×¥¿¤Î½¸¹ç¤ä¡¢UNIX¤Ë¤ª¤±¤ë¿®Íê¾ðÊó (credential) ¤ò´Þ¤ó¤Ç¤¤¤ë¡£
À©¸æ¥á¥Ã¥»¡¼¥¸¤Ï¡¢Î㤨¤Ð IP ¥ª¥×¥·¥ç¥ó¤Î¤è¤¦¤ÊÄɲåإåÀ¡¼¥Õ¥£¡¼¥ë¥É¤ò
Á÷¤ë¤Î¤Ë»È¤¦»ö¤¬¤Ç¤­¤ë¡£
Êä½õ¥Ç¡¼¥¿¤Ï¡¢
.BR sendmsg (2)
¤ò¸Æ¤Ó½Ð¤·¤ÆÁ÷¤ê¡¢
.BR recvmsg (2)
¤ò¸Æ¤Ó½Ð¤·¤Æ¼õ¤±¼è¤ë¡£
¾ÜºÙ¤Ï¤½¤ì¤é¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤ò»²¾È¡£
.PP
Êä½õ¥Ç¡¼¥¿¤Ï
.I struct cmsghdr
¹½Â¤ÂΤΥ·¡¼¥±¥ó¥¹¤ËÄɲåǡ¼¥¿¤¬Éղ䵤줿¤â¤Î¤Ç¤¢¤ë¡£
¤³¤Î¥·¡¼¥±¥ó¥¹¤Ë¤Ï¤³¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤Ë½ñ¤«¤ì¤Æ¤¤¤ë
¥Þ¥¯¥í¤ò»È¤Ã¤Æ¥¢¥¯¥»¥¹¤¹¤Ù¤­¤Ç¡¢Ä¾ÀÜ¥¢¥¯¥»¥¹¤¹¤Ù¤­¤Ç¤Ï¤Ê¤¤¡£
»ÈÍѲÄǽ¤ÊÀ©¸æ¥á¥Ã¥»¡¼¥¸¤Î¥¿¥¤¥×¤Ë¤Ä¤¤¤Æ¤Ï¡¢
¤½¤ì¤¾¤ì¤Î¥×¥í¥È¥³¥ë¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤ò»²¾È¤Î¤³¤È¡£
ÀܳËè¤ÎºÇÂçÊä½õÍѥХåե¡¥µ¥¤¥º¤Ï
.I /proc/sys/net/core/optmem_max
¤ò»È¤Ã¤ÆÀßÄê¤Ç¤­¤ë¡£
.BR socket (7)
¤ò»²¾È¡£
.PP
.BR CMSG_FIRSTHDR ()
¤Ï¡¢ÅϤ·¤¿
.I msghdr
¤Ë´ØÏ¢¤·¤¿Êä½õ¥Ç¡¼¥¿¥Ð¥Ã¥Õ¥¡Ãæ¤Î¡¢ºÇ½é¤Î
.I cmsghdr
¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
.PP
.BR CMSG_NXTHDR ()
¤Ï¡¢ÅϤ·¤¿
.I cmsghdr
¤Î¼¡¤Ë¤¯¤ë (Í­¸ú¤Ê)
.I cmsghdr
¤òÊÖ¤¹¡£
¥Ð¥Ã¥Õ¥¡¤Ë½½Ê¬¤Ê¶õ¤­¤¬Ìµ¤¤¾ì¹ç¡¢NULL ¤òÊÖ¤¹¡£
.PP
.BR CMSG_ALIGN ()
¤ËŤµ¤òÍ¿¤¨¤ë¤È¡¢É¬Íפʥ¢¥é¥¤¥ó¥á¥ó¥È¤ò²ÃÌ£¤·¤¿Ä¹¤µ¤òÊÖ¤·¤Æ¤¯¤ë¡£
¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
.PP
.BR CMSG_SPACE ()
¤Ï¡¢Í¿¤¨¤¿¥Ç¡¼¥¿Ä¹¤¬Àê¤á¤ë¤Î¤ËɬÍפÊÊä½õÍ×ÁÇ (ancillary element) ¤Î
¥Ð¥¤¥È¿ô¤òÊÖ¤¹¡£¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
.PP
.BR CMSG_DATA ()
¤Ï¡¢
.I cmsghdr
¤Î¥Ç¡¼¥¿Éôʬ¤Ø¤Î¥Ý¥¤¥ó¥¿¤òÊÖ¤¹¡£
.PP
.BR CMSG_LEN ()
¤Ï¡¢
.I cmsghdr
¹½Â¤ÂΤÎ
.I cmsg_len
¥á¥ó¥Ð¤Ë¥Ç¡¼¥¿¤ò³ÊǼ¤¹¤ëºÝ¤ËɬÍפÊÃͤòÊÖ¤¹¡£¥¢¥é¥¤¥ó¥á¥ó¥È¤â¹Íθ¤ËÆþ¤ì
¤é¤ì¤ë¡£
°ú¿ô¤È¤·¤Æ¥Ç¡¼¥¿Ä¹¤ò¤È¤ë¡£¤³¤ì¤ÏÄê¿ô¼°¤Ç¤¢¤ë¡£
.PP
Êä½õ¥Ç¡¼¥¿¤òºî¤ë¤¿¤á¤Ë¤ÏºÇ½é¤Ë
.I msghdr
¤Î¥á¥ó¥Ð¡¼
.I msg_controllen
¤ò¡¢À©¸æ¥á¥Ã¥»¡¼¥¸¥Ð¥Ã¥Õ¥¡¤ÎŤµ¤Ç½é´ü²½¤¹¤ë¡£
.BR CMSG_FIRSTHDR ()
¤ò
.I msghdr
¤ËÍѤ¤¤ë¤ÈºÇ½é¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤¬ÆÀ¤é¤ì¡¢
.BR CMSG_NXTHDR ()
¤ò»È¤¦¤È¼¡¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤¬ÆÀ¤é¤ì¤ë¡£
¤½¤ì¤¾¤ì¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤Ç¤Ï¡¢
.I cmsg_len
¤ò½é´ü²½¤¹¤ë
.RB ( CMSG_LEN ()
¤ò»È¤¦)¡£
¤½¤Î¾¤Î
.I cmsghdr
¥Ø¥Ã¥À¡¼¥Õ¥£¡¼¥ë¥É¡¢¤½¤·¤Æ¥Ç¡¼¥¿Éôʬ¤ËÂФ·¤Æ¤â
.BR CMSG_DATA ()
¤ò»È¤Ã¤Æ½é´ü²½¤ò¤¹¤ë¡£
ºÇ¸å¤Ë
.I msghdr
¤Î
.I msg_controllen
¥Õ¥£¡¼¥ë¥É¤Ë¡¢¥Ð¥Ã¥Õ¥¡Ãæ¤ÎÀ©¸æ¥á¥Ã¥»¡¼¥¸¤ÎŤµ¤Î
.BR CMSG_SPACE ()
¤Î¹ç·×¤¬¥»¥Ã¥È¤µ¤ì¤ë¡£
.I msghdr
¤Ë¤Ä¤¤¤Æ¤Î¾ÜºÙ¤Ï
.BR recvmsg (2)
¤ò»²¾È¡£
.PP
À©¸æ¥á¥Ã¥»¡¼¥¸¥Ð¥Ã¥Õ¥¡¤¬Á´¤Æ¤Î¥á¥Ã¥»¡¼¥¸¤òǼ¤á¤ë¤Î¤Ë¤Ïû¤¹¤®¤ë¾ì¹ç¡¢
.I msghdr
¤Î
.I msg_flags
¥á¥ó¥Ð¡¼¤Ë
.B MSG_CTRUNC
¥Õ¥é¥°¤¬¥»¥Ã¥È¤µ¤ì¤ë¡£
.SH ½àµò
¤³¤ÎÊä½õ¥Ç¡¼¥¿¥â¥Ç¥ë¤Ï¡¢POSIX.1g draft, 4.4BSD-Lite, RFC\ 2292 ¤Ë
µ­½Ò¤µ¤ì¤Æ¤¤¤ë IPv6 advanced API, ¤½¤·¤Æ SUSv2
¤Ë½àµò¤·¤Æ¤¤¤ë¡£
.BR CMSG_ALIGN ()
¤Ï Linux ¤Î³ÈÄ¥¤Ç¤¢¤ë¡£
.SH Ãí°Õ
°Ü¿¢À­¤Î¤¿¤á¤Ë¡¢Êä½õ¥Ç¡¼¥¿¤Ø¤Î¥¢¥¯¥»¥¹¤Ë¤Ï¡¢
¤³¤³¤Ç½Ò¤Ù¤é¤ì¤Æ¤¤¤ë¥Þ¥¯¥í¤ò»È¤¦¤À¤±¤Ë¤¹¤Ù¤­¤Ç¤¢¤ë¡£
.BR CMSG_ALIGN ()
¤Ï Linux ¤Ç¤Î³ÈÄ¥¤Ç¤¢¤ê¡¢°Ü¿¢À­¤ò¹Í¤¨¤¿¥×¥í¥°¥é¥à¤Ç¤Ï»È¤¦¤Ù¤­¤Ç¤Ï¤Ê¤¤¡£
.PP
Linux ¤Ç¤Ï
.BR CMSG_LEN (),
.BR CMSG_DATA (),
.BR CMSG_ALIGN ()
¤ÏÄê¿ô¼°¤Ç¤¢¤ë (¤½¤ì¤é¤Î°ú¿ô¤¬Äê¿ô¤È¤ß¤Ê¤µ¤ì¤ë)¡£
¤³¤Î¤³¤È¤Ï¡¢Âç°èÊÑ¿ô¤Î¥µ¥¤¥º¤òÀë¸À¤¹¤ë¤Î¤Ë»È¤¨¤ë¡£
¤·¤«¤·°Ü¿¢À­¤Ï¤Ê¤¯¤Ê¤ë¤À¤í¤¦¡£
.SH Îã
¼¡¤Î¥³¡¼¥É¤Ï¡¢¼õ¤±¼è¤Ã¤¿Êä½õ¥Ð¥Ã¥Õ¥¡¤«¤é
.B IP_TTL
¥ª¥×¥·¥ç¥ó¤òõ¤¹¤â¤Î¤Ç¤¢¤ë¡£
.PP
.in +4n
.nf
struct msghdr msgh;
struct cmsghdr *cmsg;
int *ttlptr;
int received_ttl;

/* Receive auxiliary data in msgh */
for (cmsg = CMSG_FIRSTHDR(&msgh); cmsg != NULL;
        cmsg = CMSG_NXTHDR(&msgh,cmsg)) {
    if (cmsg\->cmsg_level == IPPROTO_IP
            && cmsg\->cmsg_type == IP_TTL) {
        ttlptr = (int *) CMSG_DATA(cmsg);
        received_ttl = *ttlptr;
        break;
    }
}
if (cmsg == NULL) {
    /*
     * Error: IP_TTL not enabled or small buffer
     * or I/O error.
     */
}
.fi
.in
.PP
°Ê²¼¤Î¥³¡¼¥É¤Ï¡¢
.B SCM_RIGHTS
¤ò»È¤¤¡¢¥Õ¥¡¥¤¥ë¥Ç¥¹¥¯¥ê¥×¥¿¤ÎÇÛÎó¤ò
UNIX ¥É¥á¥¤¥ó¥½¥±¥Ã¥È¤òÄ̤·¤ÆÁ÷¤ë¤â¤Î¤Ç¤¢¤ë¡£
.PP
.in +4n
.nf
struct msghdr msg = {0};
struct cmsghdr *cmsg;
int myfds[NUM_FD]; /* Contains the file descriptors to pass. */
char buf[CMSG_SPACE(sizeof myfds)];  /* ancillary data buffer */
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);
/* Initialize the payload: */
fdptr = (int *) CMSG_DATA(cmsg);
memcpy(fdptr, myfds, NUM_FD * sizeof(int));
/* Sum of the length of all control messages in the buffer: */
msg.msg_controllen = cmsg\->cmsg_len;
.fi
.in
.SH ´ØÏ¢¹àÌÜ
.BR recvmsg (2),
.BR sendmsg (2)
.PP
RFC\ 2292