Return to DOCUMENT.ja CVS log

Up to [local] / OpenXM / src / ox_socket

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

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