Annotation of OpenXM/src/ox_socket/DOCUMENT.ja, Revision 1.4
1.4 ! maekawa 1: $OpenXM: OpenXM/src/ox_socket/DOCUMENT.ja,v 1.3 2000/11/30 13:05:45 maekawa Exp $
1.2 maekawa 2:
1.3 maekawa 3: Drafts of the specification of the OpenXM standard socket APIs.
4:
5: 1. ox_connect
1.1 maekawa 6:
7: connect(2) の代わりに ox_connet を使うべし.
8:
9: int ox_connect(const char *hostname, int port, struct ox_sockopt *opt);
10:
11: hostname - 接続先のホスト名
12: port - 接続先のポート番号
13: opt - setsockopt(2) へ渡したいオプション群
1.3 maekawa 14: setsockopt(2) の第一引数はソケット番号であるが,
15: これは ox_connect 内で作成される.
1.1 maekawa 16:
17: struct ox_sockopt {
18: ...
19:
20: int level; /* setsockopt(2) の第二引数 */
21: int option_name; /* setsockopt(2) の第三引数 */
22: void *option_value; /* setsockopt(2) の第四引数 */
23: socklen_t option_len; /* setsockopt(2) の第五引数 */
24:
25: ...
26: };
27:
1.3 maekawa 28: setsockopt(2) に渡すべき内容がない場合は, ox_connect に
29: NULL を渡せばよい.
30:
31: 成功すればソケット番号を, 失敗すれば -1 を返す.
1.1 maekawa 32:
1.3 maekawa 33: 2. ox_listen
1.1 maekawa 34:
35: listen(2) の代わりに ox_listen を使うべし.
36:
1.4 ! maekawa 37: struct ox_listen_socks *
1.1 maekawa 38: ox_listen(const char *hostname, int *port, int backlog,
39: struct ox_sockopt *opt);
40:
41: hostname - 接続先のホスト名
42: port - 接続先のポート番号
43: backlog - listen(2) の第二引数
44: opt - setsockopt(2) へ渡したいオプション群 (ox_connect と同様)
45:
1.4 ! maekawa 46: #define OX_MAX_LISTEN_SOCKS 32
! 47:
! 48: struct ox_listen_socks {
! 49: int sock[OX_MAX_LISTEN_SOCKS];
1.1 maekawa 50: int nsocks;
51: };
52:
1.3 maekawa 53: hostname が NULL の場合, ox_listen は任意のホスト
54: (IPv4 においては 0.0.0.0, IPv6 においては ::) からの接続を待ち受ける.
55:
56: 成功すれば listen(2) しているソケットの数と配列への構造体への
57: ポインタを, 失敗すれば NULL を返す.
58:
1.4 ! maekawa 59: ox_listen_socks 構造体を使う理由:
1.1 maekawa 60: 待ち受けているソケットは必ずしもひとつではない.
61: IPv4 と IPv6 双方が利用可能な (デュアルスタックな)
62: マシンにおいて, IPv4 および IPv6 をサポートしている
1.3 maekawa 63: sshd (OpenSSH など) が任意のホストからの接続を
64: 待ち受けている場合は, 以下のようになっている.
1.1 maekawa 65:
66: # sockstat | grep sshd
67: root sshd 177 4 tcp4 *:22 *:*
68: root sshd 177 3 tcp46 *:22 *:*
69:
1.3 maekawa 70: 3. ox_accept
1.1 maekawa 71:
72: accept(2) の代わりに ox_accept を使うべし.
73:
74: int ox_accept(struct listen_socks *socks);
75:
76: socks - ox_listen の戻り値
77:
78: 成功すれば accept(2) されたソケット番号を, 失敗すれば -1 を返す.
79:
1.3 maekawa 80: 4. ox_getsockname
1.1 maekawa 81:
82: getsockname(2) の代わりに ox_getsockname を使うべし.
83:
84: int ox_getsockname(int socket,
85: struct sockaddr **addr, socklen_t *addrlen);
86:
87: socket - 有効なソケット番号
88: addr - sockaddr 構造体へのポインタのポインタ
89: addrlen - sockaddr 構造体の長さ
90:
91: 成功すれば 0 を, 失敗すれば -1 を返す.
1.3 maekawa 92: 取得された sockaddr 構造体は addr に格納され,
1.1 maekawa 93: 長さは addrlen に格納される.
94:
1.3 maekawa 95: getsockname(2) を使わない理由:
1.1 maekawa 96: sockaddr 構造体は, 今日では汎用的なインターフェイスを
97: 提供しているにしかすぎない. 実際のサイズはそれぞれの
98: アドレスファミリごとに違うので, 現在では, 実質的な
99: sockaddr 構造体の placeholder として, sockaddr_storage
100: 構造体が定義されている. ただし, この構造体は, 事実上
101: IPv6 登場以降の OS にしか実装されておらず, OpenXM として
102: 実装を仮定するのはよくない. そこで, ox_getsockname という
103: wrapper を用意し, 実際の挙動を隠蔽することにした.
104: 中身が必要となる場合として, ポート番号の取得があるが,
105: これについては, ox_getport という wrapper を用意し,
106: sockaddr 構造体をさらに隠蔽できるようにしてある.
107:
108: ox_getsockname で取得した sockaddr 構造体へ割り当てたメモリは,
109: 必要がなくなった時点で確実に free(2) されるべきである.
1.3 maekawa 110: GC を用いている場合は, この限りではない. しかし, sockaddr 構造体を
111: 永続的に使用しなければならない状況はまず考えられず, GC を用いて
112: 管理する必要は一切ないと思われる.
1.1 maekawa 113:
1.3 maekawa 114: 5. ox_getport
115:
116: int ox_getport(int socket);
117:
118: socket - 有効なソケット番号
1.1 maekawa 119:
120: ポート番号の取得に関する汎用的なインターフェイスは存在しない.
121: それぞれのアドレスファミリごとに個別に対処する必要がある.
122: この操作を OpenXM として用意したのが, ox_getport である.
123:
124: 成功すればポート番号を, 失敗すれば -1 を返す.
125:
126: 注意事項:
127: 一部の OS には socklen_t が宣言されていない.
128: Single UNIX Specification, version 2 あるいは,
129: POSIX に基づいて 32 ビット符号無し整数と仮定してよいだろう.
1.3 maekawa 130: これ以上の大きさが必要となるときと, 我々の死とどちらが早いだろうか...
131:
132: OpenXM 標準ソケット API は, 現時点で IPv4 もしくは IPv6 での
133: 利用しか想定していない. この制限は, この API 群の拡張性に問題が
134: あるのではなく, これら以外のアドレスファミリにおいては,
135: いくつかの関数の動作を保証できないからである. 将来, 上記以外の
136: アドレスファミリのサポートが必要になった場合は, そのアドレスファミリ
137: において, どのような動作をすべきを十分に考慮した上で,
138: すみやかに拡張される.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>