=================================================================== RCS file: /home/cvs/OpenXM/src/ox_socket/DOCUMENT.ja,v retrieving revision 1.2 retrieving revision 1.3 diff -u -p -r1.2 -r1.3 --- OpenXM/src/ox_socket/DOCUMENT.ja 2000/11/30 00:51:00 1.2 +++ OpenXM/src/ox_socket/DOCUMENT.ja 2000/11/30 13:05:45 1.3 @@ -1,8 +1,9 @@ -$OpenXM$ +$OpenXM: OpenXM/src/ox_socket/DOCUMENT.ja,v 1.2 2000/11/30 00:51:00 maekawa Exp $ -Drafts of specifications of the OpenXM standard socket functions. +Drafts of the specification of the OpenXM standard socket APIs. -1. connect(2) +1. ox_connect + connect(2) の代わりに ox_connet を使うべし. int ox_connect(const char *hostname, int port, struct ox_sockopt *opt); @@ -10,8 +11,8 @@ Drafts of specifications of the OpenXM standard socket hostname - 接続先のホスト名 port - 接続先のポート番号 opt - setsockopt(2) へ渡したいオプション群 - setsockopt(2) の第一引数は生成されたソケット番号を渡すが, - これは ox_connect 内で生成される. + setsockopt(2) の第一引数はソケット番号であるが, + これは ox_connect 内で作成される. struct ox_sockopt { ... @@ -24,10 +25,13 @@ Drafts of specifications of the OpenXM standard socket ... }; - 成功すれば生成されたソケット番号を, 失敗すれば -1 を返す. + setsockopt(2) に渡すべき内容がない場合は, ox_connect に + NULL を渡せばよい. -2. listen(2) + 成功すればソケット番号を, 失敗すれば -1 を返す. +2. ox_listen + listen(2) の代わりに ox_listen を使うべし. struct listen_socks * @@ -39,26 +43,29 @@ Drafts of specifications of the OpenXM standard socket backlog - listen(2) の第二引数 opt - setsockopt(2) へ渡したいオプション群 (ox_connect と同様) - 成功すれば listen(2) しているソケットの数と配列への構造体への - ポインタを, 失敗すれば NULL を返す. - struct listen_socks { int nsocks; int listen_sock[nsocks]; /* 動的に割り当てられる */ }; - 理由: + hostname が NULL の場合, ox_listen は任意のホスト + (IPv4 においては 0.0.0.0, IPv6 においては ::) からの接続を待ち受ける. + + 成功すれば listen(2) しているソケットの数と配列への構造体への + ポインタを, 失敗すれば NULL を返す. + + listen_socks 構造体を使う理由: 待ち受けているソケットは必ずしもひとつではない. IPv4 と IPv6 双方が利用可能な (デュアルスタックな) マシンにおいて, IPv4 および IPv6 をサポートしている - sshd (OpenSSH など) をワイルドカードアドレスで待ち受けている - 場合は, 以下のようになっている. + sshd (OpenSSH など) が任意のホストからの接続を + 待ち受けている場合は, 以下のようになっている. # sockstat | grep sshd root sshd 177 4 tcp4 *:22 *:* root sshd 177 3 tcp46 *:22 *:* -3. accept(2) +3. ox_accept accept(2) の代わりに ox_accept を使うべし. @@ -68,7 +75,7 @@ Drafts of specifications of the OpenXM standard socket 成功すれば accept(2) されたソケット番号を, 失敗すれば -1 を返す. -4. getsockname(2) +4. ox_getsockname getsockname(2) の代わりに ox_getsockname を使うべし. @@ -80,10 +87,10 @@ Drafts of specifications of the OpenXM standard socket addrlen - sockaddr 構造体の長さ 成功すれば 0 を, 失敗すれば -1 を返す. - 取得できた sockaddr 構造体は addr に格納され, + 取得された sockaddr 構造体は addr に格納され, 長さは addrlen に格納される. - 理由: + getsockname(2) を使わない理由: sockaddr 構造体は, 今日では汎用的なインターフェイスを 提供しているにしかすぎない. 実際のサイズはそれぞれの アドレスファミリごとに違うので, 現在では, 実質的な @@ -98,25 +105,32 @@ Drafts of specifications of the OpenXM standard socket ox_getsockname で取得した sockaddr 構造体へ割り当てたメモリは, 必要がなくなった時点で確実に free(2) されるべきである. - GC を用いている場合は, この限りではない. + GC を用いている場合は, この限りではない. しかし, sockaddr 構造体を + 永続的に使用しなければならない状況はまず考えられず, GC を用いて + 管理する必要は一切ないと思われる. -5. ポート番号の取得 +5. ox_getport - ポート番号の取得に関する汎用的なインターフェイスは存在しない. - それぞれのアドレスファミリごとに個別に対処する必要がある. - この操作を OpenXM として用意したのが, ox_getport である. - int ox_getport(int socket); socket - 有効なソケット番号 + ポート番号の取得に関する汎用的なインターフェイスは存在しない. + それぞれのアドレスファミリごとに個別に対処する必要がある. + この操作を OpenXM として用意したのが, ox_getport である. + 成功すればポート番号を, 失敗すれば -1 を返す. - 現在サポートされているのは, IPv4 および IPv6 だけである. - 事実上これで十分であるが, ox_getport は容易に拡張可能である. - 注意事項: 一部の OS には socklen_t が宣言されていない. Single UNIX Specification, version 2 あるいは, POSIX に基づいて 32 ビット符号無し整数と仮定してよいだろう. - これ以上のサイズが必要となるときと, 我々の死とどちらが早いだろうか... + これ以上の大きさが必要となるときと, 我々の死とどちらが早いだろうか... + + OpenXM 標準ソケット API は, 現時点で IPv4 もしくは IPv6 での + 利用しか想定していない. この制限は, この API 群の拡張性に問題が + あるのではなく, これら以外のアドレスファミリにおいては, + いくつかの関数の動作を保証できないからである. 将来, 上記以外の + アドレスファミリのサポートが必要になった場合は, そのアドレスファミリ + において, どのような動作をすべきを十分に考慮した上で, + すみやかに拡張される.