17.2. "socket" --- 低レベルネットワークインターフェース
*******************************************************

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

注釈: いくつかの振る舞いはプラットフォームに依存します。オペレーティ
  ングシ ステムのソケットAPIを呼び出しているためです。

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 3493** "Basic
Socket Interface Extensions for IPv6" を参照してください。

Pythonインターフェースは、Unixのソケット用システムコールとライブラリを
、そのままPythonのオブジェクト指向スタイルに変換したものです。各種ソケ
ット関連のシステムコールは、 "socket()" 関数で生成する *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* に数値のアドレスを指定してください。

バージョン 2.5 で追加: AF_NETLINK ソケットが "pid, groups" のペアで表
現されます.

バージョン 2.6 で追加: Linuxのみ、 "AF_TIPC" アドレスファミリを使って
TIPC を利用することができます。 TIPCはオープンで、IPベースではないクラ
スターコンピューター環境向けのネットワークプロトコルです。アドレスはタ
プルで表現され、その中身はアドレスタイプに依存します。一般的なタプルの
形は "(addr_type, v1, v2, v3 [, scope])" で、

* *addr_type* は "TIPC_ADDR_NAMESEQ", "TIPC_ADDR_NAME",
  "TIPC_ADDR_ID" の1つ。

* *scope* は "TIPC_ZONE_SCOPE", "TIPC_CLUSTER_SCOPE",
  "TIPC_NODE_SCOPE" の1つ。

* *addr_type* が "TIPC_ADDR_NAME" の場合、 *v1* はサーバータイプ、
  *v2* はポートID (the port identifier)、そして *v3* は 0 であるべきで
  す。

  *addr_type* が "TIPC_ADDR_NAMESEQ" の場合、 *v1* はサーバータイプ、
  *v2* はポート番号下位(lower port number)、 *v3* はポート番号上位
  (upper port number) です。

  *addr_type* が "TIPC_ADDR_ID" の場合、 *v1* はノード、 *v2* は参照、
  *v3* は0であるべきです。

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

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

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

exception socket.error

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

   バージョン 2.6 で変更: "socket.error" は "IOError" の子クラスになり
   ました。

exception socket.herror

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

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

exception socket.gaierror

   この例外は "getaddrinfo()" と "getnameinfo()" でアドレス関連のエラ
   ーが発生した場合に送出されます。例外の値は "(error, string)" のペア
   で、ライブラリの呼び出し結果を返します。 *string* はC関数
   "gai_strerror()" で取得した、 *h_errno* の意味を示す文字列です。
   *error* の値は、このモジュールで定義される "EAI_*" 定数の何れかとな
   ります。

exception socket.timeout

   この例外は、あらかじめ "settimeout()" を呼び出してタイムアウトを有
   効にしてあるソケットでタイムアウトが生じた際に送出されます。例外に
   付属する値は文字列で、その内容は現状では常に "timed out" となります
   。

   バージョン 2.3 で追加.

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

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

socket.SOCK_STREAM
socket.SOCK_DGRAM
socket.SOCK_RAW
socket.SOCK_RDM
socket.SOCK_SEQPACKET

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

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

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

SIO_*
RCVALL_*

   Windows の WSAIoctl() のための定数です。この定数はソケットオブジェ
   クトの "ioctl()" メソッドに引数として渡されます。

   バージョン 2.6 で追加.

TIPC_*

   TIPC 関連の定数で、C のソケットAPIが公開しているものにマッチします
   。詳しい情報は TIPC のドキュメントを参照してください。

   バージョン 2.6 で追加.

socket.has_ipv6

   現在のプラットフォームでIPv6がサポートされているか否かを示す真偽値
   。

   バージョン 2.3 で追加.

socket.create_connection(address[, timeout[, source_address]])

   *address* ("(host, port)" ペア) で listen しているTCPサービスに接続
   し、ソケットオブジェクトを返します。これは "socket.connect()" を高
   級にした関数です。 *host* が数値でないホスト名の場合、 "AF_INET" と
   "AF_INET6" の両方で名前解決を試み、得られた全てのアドレスに対して成
   功するまで接続を試みます。この関数を使って IPv4 と IPv6 に両対応し
   たクライアントを簡単に書くことができます。

   オプションの *timeout* 引数を指定すると、接続を試みる前にソケットオ
   ブジェクトのタイムアウトを設定します。 *timeout* が指定されない場合
   、 "getdefaulttimeout()" が返すデフォルトのタイムアウト設定値を利用
   します。

   *source_address* は接続する前にバインドするソースアドレスを指定する
   オプション引数で、指定する場合は "(host, port)" の2要素タプルでなけ
   ればなりません。 host や port が '' か 0 だった場合は、OSのデフォル
   トの動作になります。

   バージョン 2.6 で追加.

   バージョン 2.7 で変更: *source_address* が追加されました。

socket.getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])

   *host* / *port* 引数の指すアドレス情報を、そのサービスに接続された
   ソケットを作成するために必要な全ての引数が入った 5 要素のタプルに変
   換します。 *host* はドメイン名、IPv4/v6アドレスの文字列、または
   "None" です。 *port* は "'http'" のようなサービス名文字列、ポート番
   号を表す数値、または "None" です。 *host* と *port* に "None" を指
   定すると C APIに "NULL" を渡せます。

   オプションの *family* 、 *socktype* 、 *proto* 引数を指定すると、返
   されるアドレスのリストを絞り込むことができます。デフォルトではこれ
   らの値は "0" で、絞り込まずに全て取得することを意味します。 *flags*
   引数には "AI_*" 定数のうち 1 つ以上が指定でき、結果の取り方を変える
   ことができます。デフォルトではこれは "0" です。例えば、
   "AI_NUMERICHOST" を指定するとドメイン名解決を行わないようにし、
   *host* がドメイン名だった場合には例外を送出します。

   この関数は以下の構造をとる 5 要素のタプルのリストを返します:

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

   このタプルにある *family*, *socktype*, *proto* は、 "socket()" 関数
   を呼び出す際に指定する値と同じ整数です。 "AI_CANONNAME" を含んだ
   *flags* を指定した場合、 *canonname* は *host* の canonical name を
   示す文字列です。そうでない場合は *canonname* は空文字列です。
   *sockaddr* は、ソケットアドレスを *family* に依存した形式で表すタプ
   ルで、 ("AF_INET" の場合は 2 要素のタプル "(address, port)" 、
   "AF_INET6" の場合は 4 要素のタプル "(address, port, flow info,
   scope id)") "socket.connect()" メソッドに渡すためのものです。

   次の例では "example.org" の 80 番ポートポートへの TCP 接続を得るた
   めのアドレス情報を取得しようとしています。 (結果は IPv6 をサポート
   しているかどうかで変わります):

      >>> socket.getaddrinfo("example.org", 80, 0, 0, socket.IPPROTO_TCP)
      [(10, 1, 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
       (2, 1, 6, '', ('93.184.216.34', 80))]

   バージョン 2.2 で追加.

socket.getfqdn([name])

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

   バージョン 2.0 で追加.

socket.gethostbyname(hostname)

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

socket.gethostbyname_ex(hostname)

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

socket.gethostname()

   Pythonインタープリタを現在実行中のマシンのホスト名を示す文字列を取
   得します。

   実行中マシンのIPアドレスが必要であれば、
   "gethostbyname(gethostname())" を使用してください。この処理は実行中
   ホストのアドレス-ホスト名変換が可能であることを前提としていますが、
   常に変換可能であるとは限りません。

   注意: "gethostname()" は完全修飾ドメイン名を返すとは限りません。完
   全修飾ドメイン名が必要であれば、 "gethostbyaddr(gethostname())" と
   してください(下記参照)。

socket.gethostbyaddr(ip_address)

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

socket.getnameinfo(sockaddr, flags)

   ソケットアドレス *sockaddr* から、 "(host, port)" のタプルを取得し
   ます。 *flags* の設定に従い、 *host* は完全修飾ドメイン名または数値
   形式アドレスとなります。同様に、 *port* は文字列のポート名または数
   値のポート番号となります。

   バージョン 2.2 で追加.

socket.getprotobyname(protocolname)

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

socket.getservbyname(servicename[, protocolname])

   インターネットサービス名とプロトコルから、そのサービスのポート番号
   を取得します。省略可能なプロトコル名として、 "'tcp'" か "'udp'" の
   どちらかを指定することができます。指定がなければどちらのプロトコル
   にもマッチします。

socket.getservbyport(port[, protocolname])

   インターネットポート番号とプロトコル名から、サービス名を取得します
   。省略可能なプロトコル名として、 "'tcp'" か "'udp'" のどちらかを指
   定することができます。指定がなければどちらのプロトコルにもマッチし
   ます。

socket.socket([family[, type[, proto]]])

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

socket.socketpair([family[, type[, proto]]])

   指定されたアドレスファミリー、ソケットタイプ、プロトコル番号から、
   接続されたソケットのペアを作成します。アドレスファミリー、ソケット
   タイプ、プロトコル番号は "socket()" 関数と同様に指定します。デフォ
   ルトのアドレスファミリは、プラットフォームで定義されていれば
   "AF_UNIX", そうでなければ "AF_INET" が使われます。

   バージョン 2.4 で追加.

socket.fromfd(fd, family, type[, proto])

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

socket.ntohl(x)

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

socket.ntohs(x)

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

socket.htonl(x)

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

socket.htons(x)

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

socket.inet_aton(ip_string)

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

   "inet_aton()" はドットが 3 個以下の文字列も受け取ります; 詳細につい
   ては Unix のマニュアル *inet(3)* を参照してください。

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

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

socket.inet_ntoa(packed_ip)

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

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

socket.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 で追加.

socket.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 で追加.

socket.getdefaulttimeout()

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

   バージョン 2.3 で追加.

socket.setdefaulttimeout(timeout)

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

   バージョン 2.3 で追加.

socket.SocketType

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

参考:

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

  Module "ssl"
     ソケットオブジェクトに対する TLS/SSL ラッパー.


17.2.1. socket オブジェクト
===========================

ソケットオブジェクトは以下のメソッドを持ちます。 "makefile()" 以外のメ
ソッドは、Unixのソケット用システムコールに対応しています。

socket.accept()

   接続を受け付けます。ソケットはアドレスにbind済みで、listen中である
   必要があります。戻り値は "(conn, address)" のペアで、 *conn* は接続
   を通じてデータの送受信を行うための *新しい* ソケットオブジェクト、
   *address* は接続先でソケットにbindしているアドレスを示します。

socket.bind(address)

   ソケットを *address* にbindします。bind済みのソケットを再バインドす
   る事はできません。(*address* のフォーマットはアドレスファミリによっ
   て異なります -- 前述。)

   注釈: 本来、このメソッドは単一のタプルのみを引数として受け付けま
     すが、 以前は "AF_INET" アドレスを示す二つの値を指定する事ができ
     ました。 これは本来の仕様ではなく、Python 2.0以降では使用すること
     はできま せん。

socket.close()

   ソケットをクローズします。以降、このソケットでは全ての操作が失敗し
   ます。リモート端点ではキューに溜まったデータがフラッシュされた後は
   それ以上のデータを受信しません。ソケットはガベージコレクション時に
   自動的にクローズされます。

   注釈: "close()" は接続に関連付けられたリソースを解放しますが、接
     続をす ぐに切断するとは限りません。接続を即座に切断したい場合は、
     "close()" の前に "shutdown()" を呼び出してください。

socket.connect(address)

   *address* で示されるリモートソケットに接続します。(*address* のフォ
   ーマットはアドレスファミリによって異なります --- 前述。)

   注釈: 本来、このメソッドは単一のタプルのみを引数として受け付けま
     すが、 以前は "AF_INET" アドレスを示す二つの値を指定する事ができ
     ました。 これは本来の仕様ではなく、Python 2.0以降では使用すること
     はできま せん。

socket.connect_ex(address)

   "connect(address)" と同様ですが、C言語の "connect()" 関数の呼び出し
   でエラーが発生した場合には例外を送出せずにエラーを戻り値として返し
   ます。(これ以外の、"host not found,"等のエラーの場合には例外が発生
   します。)処理が正常に終了した場合には "0" を返し、エラー時には
   "errno" の値を返します。この関数は、非同期接続をサポートする場合な
   どに使用することができます。

   注釈: 本来、このメソッドは単一のタプルのみを引数として受け付けま
     すが、 以前は "AF_INET" アドレスを示す二つの値を指定する事ができ
     ました。 これは本来の仕様ではなく、Python 2.0以降では使用すること
     はできま せん。

socket.fileno()

   ソケットのファイル記述子を整数型で返します。ファイル記述子は、
   "select.select()" などで使用します。

   Windowsではこのメソッドで返された小整数をファイル記述子を扱う箇所
   ("os.fdopen()" など) で利用できません。 Unix にはこの制限はありませ
   ん。

socket.getpeername()

   ソケットが接続しているリモートアドレスを返します。この関数は、リモ
   ート IPv4/v6ソケットのポート番号を調べる場合などに使用します。
   *address* のフォーマットはアドレスファミリによって異なります(前述)
   。この関数をサポートしていないシステムも存在します。

socket.getsockname()

   ソケット自身のアドレスを返します。この関数は、IPv4/v6ソケットのポー
   ト番号を調べる場合などに使用します。(*address* のフォーマットはアド
   レスファミリによって異なります --- 前述。)

socket.getsockopt(level, optname[, buflen])

   ソケットに指定されたオプションを返します(Unixのマニュアルページ
   *getsockopt(2)* を参照)。 "SO_*" 等のシンボルは、このモジュールで定
   義しています。 *buflen* を省略した場合、取得するオブションは整数と
   みなし、整数型の値を戻り値とします。 *buflen* を指定した場合、長さ
   *buflen* のバッファでオプションを受け取り、このバッファを文字列とし
   て返します。このバッファは、呼び出し元プログラムで "struct" モジュ
   ール等を利用して内容を読み取ることができます。

socket.ioctl(control, option)

   プラットフォーム:
      Windows

   "ioctl()" メソッドは WSAIoctl システムインタフェースへの制限された
   インタフェースです。詳しい情報については、 Win32 documentation を参
   照してください。

   他のプラットフォームでは一般的な "fcntl.fcntl()" と "fcntl.ioctl()"
   が使われるでしょう; これらの関数は第 1 引数としてソケットオブジェク
   トを取ります。

   バージョン 2.6 で追加.

socket.listen(backlog)

   ソケットをListenし、接続を待ちます。引数 *backlog* には接続キューの
   最大の長さ(0以上)を指定します。 *backlog* の最大数はシステムに依存
   します (通常は5)。最小値は必ず 0 です。

socket.makefile([mode[, bufsize]])

   ソケットに関連付けられた *ファイルオブジェクト* を返します (ファイ
   ルオブジェクトについては ファイルオブジェクト を参照)。ファイルオブ
   ジェクトはその "close()" メソッドが呼ばれた際もソケットを明示的にク
   ローズせずにソケットオブジェクトへの参照を削除するだけです。このた
   め、ソケットは、どこからも参照されなくなってからクローズされます。

   ソケットはブロッキングモードでなければなりません(タイムアウトを設定
   することもできません)。オプション引数の *mode* と *bufsize* には、
   "file()" 組み込み関数と同じ値を指定します。

   注釈: Windows では、 "makefile()" によって作成される file-like オ
     ブジェ クトは、 "subprocess.Popen()" などのファイル記述子のある
     file オ ブジェクトを期待している場所で利用することはできません。

socket.recv(bufsize[, flags])

   ソケットからデータを受信し、文字列として返します。受信する最大バイ
   ト数は、 *bufsize* で指定します。 *flags* のデフォルト値は0です。値
   の意味についてはUnixマニュアルページの *recv(2)* を参照してください
   。

   注釈: ハードウェアおよびネットワークの現実に最大限マッチするよう
     に、 *bufsize* の値は比較的小さい2の累乗、たとえば 4096、にすべき
     です 。

socket.recvfrom(bufsize[, flags])

   ソケットからデータを受信し、結果をタプル "(string, address)" として
   返します。 *string* は受信データの文字列で、 *address* は送信元のア
   ドレスを示します。オプション引数 *flags* については、 Unix のマニュ
   アルページ *recv(2)* を参照してください。デフォルトは0です。
   (*address* のフォーマットはアドレスファミリによって異なります(前述
   ))

socket.recvfrom_into(buffer[, nbytes[, flags]])

   ソケットからデータを受信し、そのデータを新しい文字列として返す代わ
   りに *buffer* に書きます。戻り値は "(nbytes, address)" のペアで、
   *nbytes* は受信したデータのバイト数を、 *address* はデータを送信し
   たソケットのアドレスです。オプション引数 *flags* (デフォルト:0) の
   意味については、 Unix マニュアルページ *recv(2)* を参照してください
   。(*address* のフォーマットは前述のとおりアドレスファミリーに依存し
   ます。)

   バージョン 2.5 で追加.

socket.recv_into(buffer[, nbytes[, flags]])

   *nbytes* バイトまでのデータをソケットから受信して、そのデータを新し
   い文字列にするのではなく *buffer* に保存します。 *nbytes* が指定さ
   れない(あるいは0が指定された)場合、 *buffer* の利用可能なサイズまで
   受信します。受信したバイト数を返り値として返します。オプション引数
   *flags* (デフォルト:0) の意味については、 Unix マニュアルページ
   *recv(2)* を参照してください。

   バージョン 2.5 で追加.

socket.send(string[, flags])

   ソケットにデータを送信します。ソケットはリモートソケットに接続済み
   でなければなりません。オプション引数 *flags* の意味は、上記
   "recv()" と同じです。戻り値として、送信したバイト数を返します。アプ
   リケーションでは、必ず戻り値をチェックし、全てのデータが送られた事
   を確認する必要があります。データの一部だけが送信された場合、アプリ
   ケーションで残りのデータを再送信してください。 ソケットプログラミン
   グ HOWTO に、さらに詳しい情報があります。

socket.sendall(string[, flags])

   ソケットにデータを送信します。ソケットはリモートソケットに接続済み
   でなければなりません。オプション引数 *flags* の意味は、上記
   "recv()" と同じです。 "send()" と異なり、このメソッドは *string* の
   全データを送信するか、エラーが発生するまで処理を継続します。正常終
   了の場合は "None" を返し、エラー発生時には例外が発生します。エラー
   発生時、送信されたバイト数を調べる事はできません。

socket.sendto(string, address)
socket.sendto(string, flags, address)

   ソケットにデータを送信します。このメソッドでは接続先を *address* で
   指定するので、接続済みではいけません。オプション引数 *flags* の意味
   は、上記 "recv()" と同じです。戻り値として、送信したバイト数を返し
   ます。(*address* のフォーマットはアドレスファミリによって異なります
   --- 前述。)

socket.setblocking(flag)

   ソケットのブロッキング・非ブロッキングモードを指定します。 *flag*
   が0 の場合は非ブロッキングモード、0以外の場合はブロッキングモードと
   なります。全てのソケットは、初期状態ではブロッキングモードです。非
   ブロッキングモードでは、 "recv()" メソッド呼び出し時に読み込みデー
   タが無かったり "send()" メソッド呼び出し時にデータを処理する事がで
   きないような場合に "error" 例外が発生します。しかし、ブロッキングモ
   ードでは呼び出しは処理が行われるまでブロックされます。
   "s.setblocking(0)" は "s.settimeout(0.0)" と、 "s.setblocking(1)"
   は "s.settimeout(None)" とそれぞれ同じ意味を持ちます。

socket.settimeout(value)

   ソケットのブロッキング処理のタイムアウト値を指定します。 *value* に
   は、正の浮動小数点で秒数を指定するか、もしくは "None" を指定します
   。浮動小数点値を指定した場合、操作が完了する前に *value* で指定した
   秒数が経過すると "timeout" が発生します。タイムアウト値に "None" を
   指定すると、ソケットのタイムアウトを無効にします。
   "s.settimeout(0.0)" は "s.setblocking(0)" と、 "s.settimeout(None)"
   は "s.setblocking(1)" とそれぞれ同じ意味を持ちます。

   バージョン 2.3 で追加.

socket.gettimeout()

   ソケットに指定されたタイムアウト値を取得します。タイムアウト値が設
   定されている場合には浮動小数点型で秒数が、設定されていなければ
   "None" が返ります。この値は、最後に呼び出された "setblocking()" ま
   たは "settimeout()" によって設定されます。

   バージョン 2.3 で追加.

ソケットのブロッキングとタイムアウトについて: ソケットオブジェクトのモ
ードは、ブロッキング・非ブロッキング・タイムアウトの何れかとなります。
初期状態では常にブロッキングモードです。ブロッキングモードでは、処理が
完了するまで、もしくはシステムが (接続タイムアウトなどの) エラーを返す
までブロックされます。非ブロッキングモードでは、処理を行う事ができなけ
れば(不幸にもシステムによって異なる値の)エラーとなります。タイムアウト
モードでは、ソケットに指定したタイムアウトまで、もしくはシステムがエラ
ーを返すまでに完了しなければ処理は失敗となります。 "setblocking()" メ
ソッドは、 "settimeout()" の省略形式です。

内部的には、タイムアウトモードではソケットを非ブロッキングモードに設定
します。ブロッキングとタイムアウトの設定は、ソケットと同じネットワーク
端点へ接続するファイル記述子にも反映されます。この結果、 "makefile()"
で作成したファイルオブジェクトはブロッキングモードでのみ使用することが
できます。これは非ブロッキングモードとタイムアウトモードでは、即座に完
了しないファイル操作はエラーとなるためです。

註: "connect()" はタイムアウト設定に従います。一般的に、
"settimeout()" を "connect()" の前に呼ぶかタイムアウト値を
"create_connection()" に渡すことをおすすめします。システムのネットワー
クスタックは Python のソケットタイムアウトの設定を無視して、自身のコネ
クションタイムアウトエラーを返すこともあります。

socket.setsockopt(level, optname, value)

   ソケットのオプションを設定します(Unixのマニュアルページ
   *setsockopt(2)* を参照)。 "SO_*" 等のシンボルは、このモジュールで定
   義しています。 "value" には、整数または文字列をバッファとして指定す
   る事ができます。文字列を指定する場合、文字列には適切なビットを設定
   するようにします。("struct" モジュールを利用すれば、Cの構造体を文字
   列にエンコードする事ができます。)

socket.shutdown(how)

   接続の片方向、または両方向を切断します。 *how* が "SHUT_RD" の場合
   、以降は受信を行えません。 *how* が "SHUT_WR" の場合、以降は送信を
   行えません。 *how* が "SHUT_RDWR" の場合、以降は送受信を行えません
   。プラットフォームによっては、接続の片方向をシャットダウンすると相
   手側も閉じられます。(例えば、 Mac OS X では、 "shutdown(SHUT_WR)"
   をすると、接続の相手側はもう read ができなくなります)

"read()" メソッドと "write()" メソッドは存在しませんので注意してくださ
い。代わりに *flags* を省略した "recv()" と "send()" を使うことができ
ます。

ソケットオブジェクトには以下の "socket" コンストラクタに渡された値に対
応した (読み出し専用) 属性があります。

socket.family

   ソケットファミリー。

   バージョン 2.5 で追加.

socket.type

   ソケットタイプ。

   バージョン 2.5 で追加.

socket.proto

   ソケットプロトコル。

   バージョン 2.5 で追加.


17.2.2. 例
==========

以下は TCP/IP プロトコルの簡単なサンプルとして、受信したデータをクライ
アントにそのまま返送するサーバ (接続可能なクライアントは一件のみ) と、
サーバに接続するクライアントの例を示します。サーバでは、 "socket()" ・
"bind()" ・ "listen()" ・ "accept()" を実行し (複数のクライアントから
の接続を受け付ける場合、 "accept()" を複数回呼び出します)、クライアン
トでは "socket()" と "connect()" だけを呼び出しています。サーバでは
"sendall()" / "recv()" メソッドは listen 中のソケットで実行するのでは
なく、 "accept()" で取得したソケットに対して実行している点にも注意して
ください。

次のクライアントとサーバは、IPv4 のみをサポートしています。

   # Echo server program
   import socket

   HOST = ''                 # Symbolic name meaning all available interfaces
   PORT = 50007              # Arbitrary non-privileged port
   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
   s.bind((HOST, PORT))
   s.listen(1)
   conn, addr = s.accept()
   print 'Connected by', addr
   while 1:
       data = conn.recv(1024)
       if not data: break
       conn.sendall(data)
   conn.close()

   # Echo client program
   import socket

   HOST = 'daring.cwi.nl'    # The remote host
   PORT = 50007              # The same port as used by the server
   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
   s.connect((HOST, PORT))
   s.sendall('Hello, world')
   data = s.recv(1024)
   s.close()
   print 'Received', repr(data)

次のサンプルは上記のサンプルとほとんど同じですが、IPv4 と IPv6 の両方
をサポートしています。サーバでは、IPv4/v6 の両方ではなく、利用可能な最
初のアドレスファミリだけを listen しています。ほとんどの IPv6 対応シス
テムでは IPv6 が先に現れるため、サーバは IPv4 には応答しません。クライ
アントでは名前解決の結果として取得したアドレスに順次接続を試み、最初に
接続に成功したソケットにデータを送信しています。

   # Echo server program
   import socket
   import sys

   HOST = None               # Symbolic name meaning all available interfaces
   PORT = 50007              # Arbitrary non-privileged port
   s = None
   for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                                 socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
       af, socktype, proto, canonname, sa = res
       try:
           s = socket.socket(af, socktype, proto)
       except socket.error as msg:
           s = None
           continue
       try:
           s.bind(sa)
           s.listen(1)
       except socket.error as msg:
           s.close()
           s = None
           continue
       break
   if s is None:
       print 'could not open socket'
       sys.exit(1)
   conn, addr = s.accept()
   print 'Connected by', addr
   while 1:
       data = conn.recv(1024)
       if not data: break
       conn.send(data)
   conn.close()

   # Echo client program
   import socket
   import sys

   HOST = 'daring.cwi.nl'    # The remote host
   PORT = 50007              # The same port as used by the server
   s = None
   for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
       af, socktype, proto, canonname, sa = res
       try:
           s = socket.socket(af, socktype, proto)
       except socket.error as msg:
           s = None
           continue
       try:
           s.connect(sa)
       except socket.error as msg:
           s.close()
           s = None
           continue
       break
   if s is None:
       print 'could not open socket'
       sys.exit(1)
   s.sendall('Hello, world')
   data = s.recv(1024)
   s.close()
   print 'Received', repr(data)

最後の例は、Windowsで raw socket を利用して非常にシンプルなネットワー
クスニファーを書きます。このサンプルを実行するには、インタフェースを操
作するための管理者権限が必要です。

   import socket

   # the public network interface
   HOST = socket.gethostbyname(socket.gethostname())

   # create a raw socket and bind it to the public interface
   s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
   s.bind((HOST, 0))

   # Include IP headers
   s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

   # receive all packages
   s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

   # receive a package
   print s.recvfrom(65565)

   # disabled promiscuous mode
   s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

この例の実行を、ほとんど間を空けずに何度も実行すると、以下のエラーが起
こるかもしれません:

   socket.error: [Errno 98] Address already in use

これは以前の実行がソケットを "TIME_WAIT" 状態のままにし、すぐには再利
用出来ないことで起こります。

これを防ぐのに、 "socket" フラグの "socket.SO_REUSEADDR" があります:

   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
   s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
   s.bind((HOST, PORT))

"SO_REUSEADDR" フラグは、 "TIME_WAIT" 状態にあるローカルソケットをその
タイムアウト期限が自然に切れるのを待つことなく再利用することをカーネル
に伝えます。
