Return to DOCUMENT.ja CVS log

Up to [local] / OpenXM / src / ox_socket

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

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