Return to DOCUMENT.ja CVS log

Up to [local] / OpenXM / src / ox_socket

Annotation of OpenXM/src/ox_socket/DOCUMENT.ja, Revision 1.6

1.6     ! maekawa     1: $OpenXM: OpenXM/src/ox_socket/DOCUMENT.ja,v 1.5 2000/12/01 07:47:17 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.5       maekawa    37:        struct ox_sockarray *
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.6     ! maekawa    46:        #define OX_MAXSOCKS     32
1.4       maekawa    47:
1.5       maekawa    48:        struct ox_sockarray {
1.6     ! maekawa    49:                int     sock[OX_MAXSOCKS];
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.5       maekawa    59:        ox_sockarray 構造体を使う理由:
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:
1.5       maekawa    74:        int ox_accept(struct ox_sockarray *socks);
1.1       maekawa    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:        すみやかに拡張される.