Return to DOCUMENT.ja CVS log

Up to [local] / OpenXM / src / ox_socket

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

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