.\" 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 名前
.\"O CMSG_ALIGN, CMSG_SPACE, CMSG_NXTHDR, CMSG_FIRSTHDR \- Access ancillary data
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 説明
.\"O These macros are used to create and access control messages (also called
.\"O ancillary data) that are not a part of the socket payload.
これらのマクロは制御メッセージ
(補助データ (ancillary data) とも呼ばれる) を作り、
それにアクセスするために使われる。
制御メッセージはソケットにのるデータではない。
.\"O This control information may
.\"O include the interface the packet was received on, various rarely used header
.\"O fields, an extended error description, a set of file descriptors or UNIX
.\"O credentials.
.\"O For instance, control messages can be used to send
.\"O additional header fields such as IP options.
この制御情報は、到着したパケットへのインターフェイス、様々なあまり
使われないヘッダーフィールド、エラー記述の拡張、ファイルデスクリ
プタの集合や、UNIXにおける信頼情報 (credential) を含んでいる。
制御メッセージは、例えば IP オプションのような追加ヘッダーフィールドを
送るのに使う事ができる。
.\"O Ancillary data is sent by calling
.\"O .BR sendmsg (2)
.\"O and received by calling
.\"O .BR recvmsg (2).
.\"O See their manual pages for more information.
補助データは、
.BR sendmsg (2)
を呼び出して送り、
.BR recvmsg (2)
を呼び出して受け取る。
詳細はそれらのマニュアルページを参照。
.PP
.\"O Ancillary data is a sequence of
.\"O .I struct cmsghdr
.\"O structures with appended data.
.\"O This sequence should only be accessed
.\"O using the macros described in this manual page and never directly.
補助データは
.I struct cmsghdr
構造体のシーケンスに追加データが付加されたものである。
このシーケンスにはこのマニュアルページに書かれている
マクロを使ってアクセスすべきで、直接アクセスすべきではない。
.\"O See the specific protocol man pages for the available control message types.
使用可能な制御メッセージのタイプについては、
それぞれのプロトコルのマニュアルページを参照のこと。
.\"O The maximum ancillary buffer size allowed per socket can be set using
.\"O .IR /proc/sys/net/core/optmem_max ;
.\"O see
.\"O .BR socket (7).
接続毎の最大補助用バッファサイズは
.I /proc/sys/net/core/optmem_max
を使って設定できる。
.BR socket (7)
を参照。
.PP
.\"O .BR CMSG_FIRSTHDR ()
.\"O returns a pointer to the first
.\"O .I cmsghdr
.\"O in the ancillary
.\"O data buffer associated with the passed
.\"O .IR msghdr .
.BR CMSG_FIRSTHDR ()
は、渡した
.I msghdr
に関連した補助データバッファ中の、最初の
.I cmsghdr
へのポインタを返す。
.PP
.\"O .BR CMSG_NXTHDR ()
.\"O returns the next valid
.\"O .I cmsghdr
.\"O after the passed
.\"O .IR cmsghdr .
.BR CMSG_NXTHDR ()
は、渡した
.I cmsghdr
の次にくる (有効な)
.I cmsghdr
を返す。
.\"O It returns NULL when there isn't enough space left in the buffer.
バッファに十分な空きが無い場合、NULL を返す。
.PP
.\"O .BR CMSG_ALIGN (),
.\"O given a length, returns it including the required alignment.
.\"O This is a
.\"O constant expression.
.BR CMSG_ALIGN ()
に長さを与えると、必要なアラインメントを加味した長さを返してくる。
これは定数式である。
.PP
.\"O .BR CMSG_SPACE ()
.\"O returns the number of bytes an ancillary element with payload of the
.\"O passed data length occupies.
.\"O This is a constant expression.
.BR CMSG_SPACE ()
は、与えたデータ長が占めるのに必要な補助要素 (ancillary element) の
バイト数を返す。これは定数式である。
.PP
.\"O .BR CMSG_DATA ()
.\"O returns a pointer to the data portion of a
.\"O .IR cmsghdr .
.BR CMSG_DATA ()
は、
.I cmsghdr
のデータ部分へのポインタを返す。
.PP
.\"O .BR CMSG_LEN ()
.\"O returns the value to store in the
.\"O .I cmsg_len
.\"O member of the
.\"O .I cmsghdr
.\"O structure, taking into account any necessary
.\"O alignment.
.\"O It takes the data length as an argument.
.\"O This is a constant
.\"O expression.
.BR CMSG_LEN ()
は、
.I cmsghdr
構造体の
.I cmsg_len
メンバにデータを格納する際に必要な値を返す。アラインメントも考慮に入れ
られる。
引数としてデータ長をとる。これは定数式である。
.PP
.\"O To create ancillary data, first initialize the
.\"O .I msg_controllen
.\"O member of the
.\"O .I msghdr
.\"O with the length of the control message buffer.
.\"O Use
.\"O .BR CMSG_FIRSTHDR ()
.\"O on the
.\"O .I msghdr
.\"O to get the first control message and
.\"O .BR CMSG_NEXTHDR ()
.\"O to get all subsequent ones.
補助データを作るためには最初に
.I msghdr
のメンバー
.I msg_controllen
を、制御メッセージバッファの長さで初期化する。
.BR CMSG_FIRSTHDR ()
を
.I msghdr
に用いると最初の制御メッセージが得られ、
.BR CMSG_NEXTHDR ()
を使うと次の制御メッセージが得られる。
.\"O In each control message, initialize
.\"O .I cmsg_len
.\"O (with
.\"O .BR CMSG_LEN ()),
.\"O the other
.\"O .I cmsghdr
.\"O header fields, and the data portion using
.\"O .BR CMSG_DATA ().
それぞれの制御メッセージでは、
.I cmsg_len
を初期化する
.RB ( CMSG_LEN ()
を使う)。
その他の
.I cmsghdr
ヘッダーフィールド、そしてデータ部分に対しても
.BR CMSG_DATA ()
を使って初期化をする。
.\"O Finally, the
.\"O .I msg_controllen
.\"O field of the
.\"O .I msghdr
.\"O should be set to the sum of the
.\"O .BR CMSG_SPACE ()
.\"O of the length of
.\"O all control messages in the buffer.
.\"O For more information on the
.\"O .IR msghdr ,
.\"O see
.\"O .BR recvmsg (2).
最後に
.I msghdr
の
.I msg_controllen
フィールドに、バッファ中の制御メッセージの長さの
.BR CMSG_SPACE ()
の合計がセットされる。
.I msghdr
についての詳細は
.BR recvmsg (2)
を参照。
.PP
.\"O When the control message buffer is too short to store all messages, the
.\"O .B MSG_CTRUNC
.\"O flag is set in the
.\"O .I msg_flags
.\"O member of the
.\"O .IR msghdr .
制御メッセージバッファが全てのメッセージを納めるのには短すぎる場合、
.I msghdr
の
.I msg_flags
メンバーに
.B MSG_CTRUNC
フラグがセットされる。
.\"O .SH "CONFORMING TO"
.SH 準拠
.\"O This ancillary data model conforms to the POSIX.1g draft, 4.4BSD-Lite,
.\"O the IPv6 advanced API described in RFC\ 2292 and the SUSv2.
.\"O .BR CMSG_ALIGN ()
.\"O is a Linux extension.
この補助データモデルは、POSIX.1g draft, 4.4BSD-Lite, RFC\ 2292 に
記述されている IPv6 advanced API, そして SUSv2
に準拠している。
.BR CMSG_ALIGN ()
は Linux の拡張である。
.SH 注意
.\"O For portability, ancillary data should be accessed only using the macros
.\"O described here.
移植性のために、補助データへのアクセスには、
ここで述べられているマクロを使うだけにすべきである。
.BR CMSG_ALIGN ()
.\"O is a Linux extension and should be not used in portable programs.
は Linux での拡張であり、移植性を考えたプログラムでは使うべきではない。
.PP
.\"O In Linux,
.\"O .BR CMSG_LEN (),
.\"O .BR CMSG_DATA (),
.\"O and
.\"O .BR CMSG_ALIGN ()
.\"O are constant expressions (assuming their argument is constant);
.\"O this could be used to declare the size of global
.\"O variables.
.\"O This may be not portable, however.
Linux では
.BR CMSG_LEN (),
.BR CMSG_DATA (),
.BR CMSG_ALIGN ()
は定数式である (それらの引数が定数とみなされる)。
このことは、大域変数のサイズを宣言するのに使える。
しかし移植性はなくなるだろう。
.SH 例
.\"O This code looks for the
.\"O .B IP_TTL
.\"O option in a received ancillary buffer:
次のコードは、受け取った補助バッファから
.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
.\"O The code below passes an array of file descriptors over a
.\"O UNIX domain socket using
.\"O .BR SCM_RIGHTS :
以下のコードは、
.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