.\" .\" epoll by Davide Libenzi ( efficient event notification retrieval ) .\" Copyright (C) 2003 Davide Libenzi .\" .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public License .\" along with this program; if not, write to the Free Software .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA .\" .\" Davide Libenzi .\" .\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO .\" all rights reserved. .\" Translated 2004-06-15, Yuichi SATO .\" Updated & Modified 2004-12-29, Yuichi SATO .\" Updated & Modified 2005-04-20, Yuichi SATO .\" Updated & Modified 2005-09-06, Akihiro MOTOKI .\" Updated 2006-07-19, Akihiro MOTOKI , LDP v2.36 .\" Updated 2009-02-23, Akihiro MOTOKI , LDP v3.19 .\" .TH EPOLL_CTL 2 2010-08-29 "Linux" "Linux Programmer's Manual" .SH 名前 epoll_ctl \- epoll ディスクリプタのインタフェースを操作する .SH 書式 .B #include .sp .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \ ", struct epoll_event *" event ); .SH 説明 このシステムコールは、ファイルディスクリプタ .I epfd が参照する epoll インスタンスに対する操作を行う。 対象のファイルディスクリプタ .I fd に対して、操作 .I op の実行が要求される。 .I op 引き数に指定できる有効な値は以下の通りである。 .TP .B EPOLL_CTL_ADD 対象のファイルディスクリプタ .I fd をファイルディスクリプタ .I epfd が参照する .B epoll インスタンスに登録し、イベント .I event を .I fd に結び付けられた内部ファイルに関連付ける。 .TP .B EPOLL_CTL_MOD イベント .I event を対象のファイルディスクリプタ .I fd に関連付けるように変更する。 .TP .B EPOLL_CTL_DEL 対象のファイルディスクリプタ .I fd を .I epfd が参照する .B epoll インスタンスから削除する。 .I event 引き数は無視されるので、NULL にすることもできる (但し、下記の「バグ」を参照)。 .PP .I event 引き数は、ファイルディスクリプタ .I fd にリンクされたオブジェクトを表す。 .I struct epoll_event は以下のように定義される: .sp .in +4n .nf typedef union epoll_data { void *ptr; int fd; uint32_t u32; uint64_t u64; } epoll_data_t; struct epoll_event { uint32_t events; /* epoll イベント */ epoll_data_t data; /* ユーザデータ変数 */ }; .fi .in .I events メンバは、以下のような使用可能なイベントタイプを使って構成された ビットセットである。 .TP .B EPOLLIN 関連付けられたファイルに対して、 .BR read (2) 操作が可能である。 .TP .B EPOLLOUT 関連付けられたファイルに対して、 .BR write (2) 操作が可能である。 .TP .BR EPOLLRDHUP" (Linux 2.6.17 以降)" ストリームソケットの他端が、コネクションの close 、 またはコネクションの書き込み側の shutdown を行った。 (このフラグを使うと、エッジトリガの監視を行う場合に、 通信のもう一端が閉じられたことを検知するコードを 非常に簡潔に書くことができる。) .TP .B EPOLLPRI .BR read (2) 操作が可能な緊急 (urgent) データがある。 .TP .B EPOLLERR 関連付けられたファイルディスクリプタにエラー条件が起こった。 .BR epoll_wait (2) は常にこのイベントを待つので、 .I events に設定する必要はない。 .TP .B EPOLLHUP 関連付けられたファイルディスクリプタにハングアップが起こった。 .BR epoll_wait (2) は常にこのイベントを待つので、 .I events に設定する必要はない。 .TP .B EPOLLET 関連付けられたファイルディスクリプタに エッジトリガ動作 (Edge Triggered behavior) を設定する。 .B epoll のデフォルトの動作は、レベルトリガ (Level Triggered) である。 エッジトリガとレベルトリガによるイベント分配機構 (event distribution architectures) についての詳細な情報は、 .BR epoll (7) を参照すること。 .TP .BR EPOLLONESHOT " (Linux 2.6.2 以降)" 関連付けられたファイルディスクリプタに 一撃動作 (One-Shot behavior) を設定する。 これはイベントが .BR epoll_wait (2) によって引き出された後、 関連付けられたファイルディスクリプタが内部的に破棄され、 .B epoll インタフェースによってイベントが報告されなくなることを意味する。 新しいイベントマスクでファイルディスクリプタを再度有効にするためには、 .BR epoll_ctl () に .B EPOLL_CTL_MOD を指定して呼び出さなければならない。 .I op 引き数に指定できる有効な値は、以下の通り: .SH 返り値 成功した場合、 .BR epoll_ctl () は 0 を返す。 エラーが起こった場合、 .BR epoll_ctl () は \-1 を返し、 .I errno を適切に設定する。 .SH エラー .TP .B EBADF .I epfd か .I fd が有効なファイルディスクリプタでない。 .TP .B EEXIST .I op が .B EPOLL_CTL_ADD であり、かつ与えられたファイルディスクリプタ .I fd がこの epoll インスタンスに既に登録されている。 .TP .B EINVAL .I epfd が .B epoll ファイルディスクリプタでない。 または .I fd が .I epfd と同一である。 または要求された操作 .I op がこのインタフェースでサポートされていない。 .TP .B ENOENT .I op が .B EPOLL_CTL_MOD または .B EPOLL_CTL_DEL で、かつ .I fd がこの epoll インスタンスに登録されていない。 .TP .B ENOMEM 要求された .I op 制御操作を扱うのに十分なメモリがない。 .TP .B ENOSPC epoll インスタンスに新しいファイルディスクリプタを登録 .RB ( EPOLL_CTL_ADD ) しようとした際に、 .I /proc/sys/fs/epoll/max_user_watches で決まる上限に達した。 詳細は .BR epoll (7) を参照。 .TP .B EPERM 対象ファイル .I fd が .B epoll をサポートしていない。 .SH 準拠 .BR epoll_ctl () は Linux 独自であり、カーネル 2.5.44 で導入された。 .\" インタフェースは Linux カーネル 2.5.66 で確定されるべきである。 .SH 備考 .B epoll インタフェースは、 .BR poll (2) に対応している全てのファイルディスクリプタに対応している。 .SH バグ Linux 2.6.9 より前では、 .B EPOLL_CTL_DEL 操作の際、引き数 .I event に (たとえ無視される場合であっても) NULL でないポインタを渡す必要があった。 カーネル 2.6.9 以降では、 .B EPOLL_CTL_DEL を使う際に .I event に NULL を指定できるようになっている。 2.6.9 より前のカーネルへの移植性が必要なアプリケーションでは、 .I event に NULL でないポインタを指定すべきである。 .SH 関連項目 .BR epoll_create (2), .BR epoll_wait (2), .BR poll (2), .BR epoll (7)