# 7.2 `socket` -- 低レベルネットワークインターフェース

このモジュールは、PythonでBSD ソケット インターフェースを利用する ために使用します。最近のUnixシステム、Windows, MacOS, BeOS, OS/2な ど、多くのプラットフォームで利用可能です。

C言語によるソケットプログラミングの基礎については、以下の資料を参照して ください。 An Introductory 4.3BSD Interprocess Communication Tutorial (Stuart Sechrest), An Advanced 4.3BSD Interprocess Communication Tutorial (Samuel J. Leffler他), Unix Programmer's Manual, Supplementary Documents 1(PS1:7章 PS1:8章)。ソケットの詳細については、 各プラットフォームのソケット関連システムコールに関するドキュメント(Unix では マニュアルページ、WindowsではWinSock(またはWinSock2)仕様書)も参照し てください。IPv6対応のAPIについては、RFC 2553 Basic Socket Interface Extensions for IPv6を参照してくださ い。

Pythonインターフェースは、Unixのソケット用システムコールとライブラリ を、そのままPythonのオブジェクト指向スタイルに変換したものです。各種ソケ ット関連のシステムコールは、`socket()`関数で生成する ソケット オブジェクトのメソッドとして実装されてい ます。メソッドのパラメータはCのインターフェースよりも多少高水準で、例え ば`read()`や`write()`メソッドではファイルオブジェクトと同 様、受信時のバッファ確保や送信時の出力サイズなどは自動的に処理されます。

ソケットのアドレスは以下のように指定します:単一の文字列は、 `AF_UNIX`アドレスファミリを示します。`(host, port)`のペアは`AF_INET`アドレスファミリを示し、host は`'daring.cwi.nl'`のようなインターネットドメイン形式または `'100.50.200.5'`のようなIPv4アドレスを文字列で、portはポート 番号を整数で指定します。`AF_INET6`アドレスファミリは `(host, port, flowinfo, scopeid)`の長さ4の タプルで示し、flowinfoとscopeidにはそれぞれCの `struct sockaddr_in6`における`sin6_flowinfo`と `sin6_scope_id`の値を指定します。後方互換性のため、`socket` モジュールのメソッドでは`sin6_flowinfo`と`sin6_scope_id`を省略 する事ができますが、scopeidを省略するとスコープを持ったIPv6アドレ スの処理で問題が発生する場合があります。現在サポートされているアドレスフ ァミリは以上です。ソケットオブジェクトで利用する事のできるアドレス形式 は、ソケットオブジェクトの作成時に指定したアドレスファミリで決まります。

IPv4アドレスのホストアドレスが空文字列の場合、`INADDR_ANY`とし て処理されます。また、`'<broadcast>'`の場合は `INADDR_BROADCAST`として処理されます。IPv6では後方互換性のため この機能は用意されていませんので、IPv6をサポートするPythonプログラムでは 利用しないで下さい。

IPv4/v6ソケットのhost部にホスト名を指定すると、処理結果が一定では ない場合があります。これはPythonはDNSから取得したアドレスのうち最初のア ドレスを使用するので、DNSの処理やホストの設定によって異なるIPv4/6アドレ スを取得する場合があるためです。常に同じ結果が必要であれば、hostに 数値のアドレスを指定してください。

エラー時には例外が発生します。引数型のエラーやメモリ不足の場合には通常の 例外が発生し、ソケットやアドレス関連のエラーの場合は `socket.error`が発生します。

`setblocking()`メソッドで、非ブロッキングモードを使用することがで きます。また、より汎用的に`settimeout()`メソッドでタイムアウトを 指定する事ができます。

`socket`モジュールでは、以下の定数と関数を提供しています。

exception `error`
  この例外は、ソケット関連のエラーが発生した場合に送出されます。例外の値は 障害の内容を示す文字列か、または`os.error`と同様な `(errno, string)`のペアとなります。オペレーティングシス テムで定義されているエラーコードについては`errno` を参照してください。

exception `herror`
  この例外は、C APIの`gethostbyname_ex()`や `gethostbyaddr()`などで、h_errnoのようなアドレス関連のエ ラーが発生した場合に送出されます。

  例外の値は`(h_errno, string)`のペアで、ライブラリの呼び 出し結果を返します。stringはC関数`hstrerror()`で取得し た、h_errnoの意味を示す文字列です。

exception `gaierror`
  この例外は`getaddrinfo()`と`getnameinfo()`でアドレス関 連のエラーが発生した場合に送出されます。

  例外の値は`(error, string)`のペアで、ライブラリの呼び出 し結果を返します。stringはC関数`gai_strerror()`で取得し た、h_errnoの意味を示す文字列です。 errorの値は、このモジュールで定義される `EAI_*` 定数の何れか となります。

exception `timeout`
  この例外は、あらかじめ `settimeout()` を呼び出してタイムアウトを 有効にしてあるソケットでタイムアウトが生じた際に送出されます。 例外に付属する値は文字列で、その内容は現状では常に ``timed out'' となります。 バージョン2.3 以降で新規追加された 仕様です。

`AF_UNIX`
`AF_INET`
`AF_INET6`
  アドレス（およびプロトコル）ファミリを示す定数で、`socket()`の 最初の引数に指定することができます。`AF_UNIX`ファミリをサポート しないプラットフォームでは、`AF_UNIX`は未定義となります。

`SOCK_STREAM`
`SOCK_DGRAM`
`SOCK_RAW`
`SOCK_RDM`
`SOCK_SEQPACKET`
  ソケットタイプを示す定数で、`socket()`の2番目の引数に指定するこ とができます。(ほとんどの場合、`SOCK_STREAM`と `SOCK_DGRAM`以外は必要ありません。)

`SO_*`
`SOMAXCONN`
`MSG_*`
`SOL_*`
`IPPROTO_*`
`IPPORT_*`
`INADDR_*`
`IP_*`
`IPV6_*`
`EAI_*`
`AI_*`
`NI_*`
`TCP_*`

  Unixのソケット・IPプロトコルのドキュメントで定義されている各種定数。 ソケットオブジェクトの`setsockopt()`や`getsockopt()`で使用 します。ほとんどのシンボルはUnixのヘッダファイルに従っています。一部 のシンボルには、デフォルト値を定義してあります。

`has_ipv6`
  現在のプラットフォームでIPv6がサポートされているか否かを示す真偽値。 バージョン2.3 以降で新規追加された 仕様です。

`getaddrinfo`( | host, port[, family[, socktype[, proto[, flags]]]])

  host/port 引数の指すアドレス情報を解決して、 ソケット操作に必要な全ての引数が入った 5 要素のタプルを返します。 hostはドメイン名、IPv4/v6アドレスの文字列、または`None` です。port は`'http'`のようなサービス名文字列、ポート番号 を表す数値、または`None` です。

  これ以外の引数は省略可能で、指定する場合には数値でなければなりません。 hostとport に空文字列か`None` を指定すると C APIに `NULL`を渡せます。 `getattrinfo()` 関数は以下の構造をとる 5 要素のタプルを返します:

  `(family, socktype, proto, canonname, sockaddr)`

  family・socktype・protoは、`socket()`関数を呼 び出す際に指定する値と同じ整数です。canonnameはhostの規準名 を示す文字列です。`AI_CANONNAME`を指定した場合、数値によるIPv4/ v6アドレスを返します。sockaddrは、ソケットアドレスを上述の形式で表 すタプルです。この関数の使い方については、`httplib`モジュール などのソースを参考にしてください。

  バージョン2.2 以降で新規追加された 仕様です。

`getfqdn`( | [name])

  nameの完全修飾ドメイン名を返します。nameが空または省略された 場合、ローカルホストを指定したとみなします。完全修飾ドメイン名の取得には まず`gethostbyaddr()`でチェックし、次に可能であればエイリアスを 調べ、名前にピリオドを含む最初の名前を値として返します。完全修飾ドメイ ン名を取得できない場合、ホスト名を返します。

  バージョン2.0 以降で新規追加された 仕様です。

`gethostbyname`( | hostname)

  ホスト名を`'100.50.200.5'`のようなIPv4形式のアドレスに変換します。 ホスト名としてIPv4アドレスを指定した場合、その値は変換せずにそのまま返り ます。`gethostbyname()` APIへのより完全なインターフェースが必要 であれば、`gethostbyname_ex()`を参照してください。 `gethostbyname()`は、IPv6名前解決をサポートしていません。IPv4/ v6のデュアルスタックをサポートする場合は`getaddrinfo()`を使用し ます。

`gethostbyname_ex`( | hostname)

  ホスト名から、IPv4形式の各種アドレス情報を取得します。戻り値は `(hostname, aliaslist, ipaddrlist)`のタプルで、hostnameは ip_addressで指定したホストの正式名、aliaslistは同じアドレス の別名のリスト(空の場合もある)、ipaddrlistは同じホスト上の同一イ ンターフェースのIPv4アドレスのリスト(ほとんどの場合は単一のアドレスのみ) を示します。`gethostbyname()`は、IPv6名前解決をサポートしていま せん。IPv4/v6のデュアルスタックをサポートする場合は `getaddrinfo()`を使用します。

`gethostname`( | )

  Pythonインタープリタを現在実行中のマシンのホスト名を示す文字列を取得しま す。実行中マシンのIPアドレスが必要であれば、 `gethostbyname(gethostname())`を使用してください。この処理は実行中 ホストのアドレス-ホスト名変換が可能であることを前提としていますが、常に 変換可能であるとは限りません。注意: `gethostname()`は完全修飾ド メイン名を返すとは限りません。完全修飾ドメイン名が必要であれば、 `gethostbyaddr(gethostname())`としてください(下記参照)。

`gethostbyaddr`( | ip_address)

  `(hostname, aliaslist, ipaddrlist)`のタプルを返 し、hostnameはip_addressで指定したホストの正式名、 `aliaslist`は同じアドレスの別名のリスト(空の場合もある)、 `ipaddrlist`は同じホスト上の同一インターフェースのIPv4アドレスのリ スト(ほとんどの場合は単一のアドレスのみ)を示します。完全修飾ドメイン名が 必要であれば、`getfqdn()`を使用してください。 `gethostbyaddr`は、IPv4/IPv6の両方をサポートしています。

`getnameinfo`( | sockaddr, flags)

  ソケットアドレスsockaddrから、`(host, port)`のタ プルを取得します。flagsの設定に従い、hostは完全修飾ドメイン 名または数値形式アドレスとなります。同様に、portは文字列のポート名 または数値のポート番号となります。 バージョン2.2 以降で新規追加された 仕様です。

`getprotobyname`( | protocolname)

  `'icmp'`のようなインターネットプロトコル名を、`socket()`の 第三引数として指定する事ができる定数に変換します。これは主にソケットを`` raw''モード(`SOCK_RAW`)でオープンする場合には必要ですが、通常の ソケットモードでは第三引数に0を指定するか省略すれば正しいプロトコルが自 動的に選択されます。

`getservbyname`( | servicename, protocolname)

  インターネットサービス名とプロトコルから、そのサービスのポート番号を取得 します。プロトコル名として、`'tcp'`か`'udp'`を指定することがで きます。

`socket`( | family, type[, proto])

  アドレスファミリ、ソケットタイプ、プロトコル番号を指定してソケットを作成 します。アドレスファミリには`AF_INET`・`AF_INET6`・ `AF_UNIX`を指定することができます。ソケットタイプには `SOCK_STREAM`・`SOCK_DGRAM`・または"`SOCK_`"の何れ かを指定します。プロトコル番号には通常省略するか、または0を指定します。

`ssl`( | sock[, keyfile, certfile])

  ソケットsockによるSSL接続を初期化します。keyfileには、PEMフ ォーマットのプライベートキーファイル名を指定します。certfileには、 PEMフォーマットの認証チェーンファイル名を指定します。処理が成功すると、 新しい`SSLObject`が返ります。

  警告: 証明書の認証は全く行いません。

`fromfd`( | fd, family, type[, proto])

  既存のファイルディスクリプタ(ファイルオブジェクトの`fileno()`で返 る整数)から、ソケットオブジェクトを構築します。アドレスファミリとプロト コル番号は`socket()`と同様に指定します。ファイルディスクリプタ はソケットを指していなければなりませんが、実際にソケットであるかどうかの チェックは行っていません。このため、ソケット以外のファイルディスクリプタ を指定するとその後の処理が失敗する場合があります。この関数が必要な事はあ まりありませんが、Unixのinetデーモンのようにソケットを標準入力や標準 出力として使用するプログラムで使われます。この関数で使用するソケットは、 ブロッキングモードと想定しています。 利用可能:Unix

`ntohl`( | x)

  32ビット整数のバイトオーダを、ネットワークバイトオーダからホストバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップ を行います。

`ntohs`( | x)

  16ビット整数のバイトオーダを、ネットワークバイトオーダからホストバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップ を行います。

`htonl`( | x)

  32ビット整数のバイトオーダを、ホストバイトオーダからネットワークバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は4バイトのスワップ を行います。

`htons`( | x)

  16ビット整数のバイトオーダを、ホストバイトオーダからネットワークバイト オーダに変換します。ホストバイトオーダとネットワークバイトオーダが一致す るマシンでは、この関数は何もしません。それ以外の場合は2バイトのスワップ を行います。

`inet_aton`( | ip_string)

  ドット記法によるIPv4アドレス(`'123.45.67.89'`など)を32ビットにパッ クしたバイナリ形式に変換し、長さ4の文字列として返します。この関数が返す 値は、標準Cライブラリの`struct in_addr`型を使用する関数に渡す事がで きます。

  IPv4アドレス文字列が不正であれば、`socket.error`が発生します。 このチェックは、この関数で使用しているCの実装 `inet_aton()`で 行われます。

  `inet_aton()`は、IPv6をサポートしません。IPv4/v6のデュアルスタ ックをサポートする場合は`getnameinfo()`を使用します。

`inet_ntoa`( | packed_ip)

  32ビットにパックしたバイナリ形式のIPv4アドレスを、ドット記法による文字列 (`'123.45.67.89'`など)に変換します。この関数が返す値は、標準Cライブ ラリの`struct in_addr`型を使用する関数に渡す事ができます。

  この関数に渡す文字列の長さが4バイト以外であれば、 `socket.error`が発生します。 `inet_ntoa()`は、IPv6をサポートしません。IPv4/v6のデュアルスタ ックをサポートする場合は`getnameinfo()`を使用します。

`inet_pton`( | address_family, ip_string)

  IPアドレスを、アドレスファミリ固有の文字列からパックしたバイナリ形式に変 換します。`inet_pton()`は、`struct in_addr`型 (`inet_aton()`と同様)や`struct in6_addr`を使用するライブ ラリやネットワークプロトコルを呼び出す際に使用することができます。

  現在サポートされているaddress_familyは、`AF_INET`と `AF_INET6`です。ip_stringに不正なIPアドレス文字列を指定す ると、`socket.error`が発生します。有効なip_stringは、 address_familyと`inet_pton()`の実装によって異なります。

  利用可能: Unix (サポートしていないプラットフォームもあります) バージョン2.3 以降で新規追加された 仕様です。

`inet_ntop`( | address_family, packed_ip)

  パックしたIPアドレス(数文字の文字列)を、`'7.10.0.5'`や `'5aef:2b::8'`などの標準的な、アドレスファミリ固有の文字列形式に変 換します。`inet_ntop()`は(`inet_ntoa()`と同様に) `struct in_addr`型や`struct in6_addr`型のオブジェクトを返す ライブラリやネットワークプロトコル等で使用することができます。

  現在サポートされているaddress_familyは、`AF_INET`と `AF_INET6`です。packed_ipの長さが指定したアドレスファミリ で適切な長さでなければ、`ValueError`が発生します。 `inet_ntop()`でエラーとなると、`socket.error`が発生し ます。

  利用可能: Unix (サポートしていないプラットフォームもあります) バージョン2.3 以降で新規追加された 仕様です。

`getdefaulttimeout`( | )

  新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を浮動 小数点形式の秒数で返します。タイプアウトを使用しない場合には`None` を返します。最初にsocketモジュールがインポートされた時の初期値は `None`です。

  バージョン2.3 以降で新規追加された 仕様です。

`setdefaulttimeout`( | timeout)

  新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を浮動 小数点形式の秒数で指定します。タイムアウトを使用しない場合には `None`を指定します。最初にsocketモジュールがインポートされた時の初 期値は`None`です。

  バージョン2.3 以降で新規追加された 仕様です。

`SocketType`
  ソケットオブジェクトの型を示す型オブジェクト。`type(socket(...))`と 同じです。

参考資料:

`SocketServer`モジュール:
  ネットワークサーバの開発を省力化するためのク ラス群。.