\section{\module{socket} ---
         低レベルネットワークインターフェース}

\declaremodule{builtin}{socket}
\modulesynopsis{低レベルネットワークインターフェース。}

このモジュールは、PythonでBSD \emph{ソケット} インターフェースを利用する
ために使用します。最近の\UNIX{}システム、Windows, MacOS, BeOS, OS/2な
ど、多くのプラットフォームで利用可能です。
\note{いくつかの振る舞いはプラットフォームに依存します。これはオペレーティングシステム
のソケットAPIを呼び出しているためです。}

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

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

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

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

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

\versionadded[AF_NETLINK ソケットが \code{\var{pid}, \var{groups}}
のペアで表現されます]{2.5}

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

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

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

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

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

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

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

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

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


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

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

\begin{datadesc}{SO_*}
\dataline{SOMAXCONN}
\dataline{MSG_*}
\dataline{SOL_*}
\dataline{IPPROTO_*}
\dataline{IPPORT_*}
\dataline{INADDR_*}
\dataline{IP_*}
\dataline{IPV6_*}
\dataline{EAI_*}
\dataline{AI_*}
\dataline{NI_*}
\dataline{TCP_*}

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

\begin{datadesc}{has_ipv6}
現在のプラットフォームでIPv6がサポートされているか否かを示す真偽値。
\versionadded{2.3}
\end{datadesc}

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

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

\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
      \var{sockaddr})}

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

\versionadded{2.2}
\end{funcdesc}

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

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

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

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

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

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

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

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

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

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

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

\warning{証明書の認証は全く行いません。}
\end{funcdesc}

\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}}

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

利用可能: \UNIX.  \versionadded{2.4}
\end{funcdesc}


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

\end{funcdesc}

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

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

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

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

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

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

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

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

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

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

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

利用可能: \UNIX{} (サポートしていないプラットフォームもあります)
\versionadded{2.3}
\end{funcdesc}

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

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

利用可能: \UNIX{} (サポートしていないプラットフォームもあります)
\versionadded{2.3}
\end{funcdesc}

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

\versionadded{2.3}
\end{funcdesc}

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

\versionadded{2.3}
\end{funcdesc}

\begin{datadesc}{SocketType}
ソケットオブジェクトの型を示す型オブジェクト。\code{type(socket(...))}と
同じです。
\end{datadesc}


\begin{seealso}
  \seemodule{SocketServer}{ネットワークサーバの開発を省力化するためのク
  ラス群。}
\end{seealso}


\subsection{socket オブジェクト \label{socket-objects}}

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

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

\begin{methoddesc}[socket]{bind}{address}
ソケットを\var{address}にbindします。bind済みのソケットを再バインドする
事はできません。\var{address}のフォーマットはアドレスファミリによって異
なります(前述)。
\note{本来、このメソッドは単一のタプルのみを引数として受け付けますが、
以前は\constant{AF_INET}アドレスを示す二つの値を指定する事ができました。
これは本来の仕様ではなく、Python 2.0以降では使用することはできません。}
\end{methoddesc}

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

\begin{methoddesc}[socket]{connect}{address}
\var{address}で示されるリモートソケットに接続します。\var{address}のフ
ォーマットはアドレスファミリによって異なります(前述)。
\note{本来、このメソッドは単一のタプルのみを引数として受け付けますが、
以前は\constant{AF_INET}アドレスを示す二つの値を指定する事ができました。
これは本来の仕様ではなく、Python 2.0以降では使用することはできません。}
\end{methoddesc}

\begin{methoddesc}[socket]{connect_ex}{address}
\code{connect(\var{address})}と同様ですが、C言語の\cfunction{connect()}
関数の呼び出しでエラーが発生した場合には例外を送出せずにエラーを戻り値と
して返します。(これ以外の、``host not found,''等のエラーの場合には例外が
発生します。)処理が正常に終了した場合には\code{0}を返し、エラー時には
\cdata{errno}の値を返します。この関数は、非同期接続をサポートする場合な
どに使用することができます。
\note{本来、このメソッドは単一のタプルのみを引数として受け付けますが、
以前は\constant{AF_INET}アドレスを示す二つの値を指定する事ができました。
これは本来の仕様ではなく、Python 2.0以降では使用することはできません。}
\end{methoddesc}

\begin{methoddesc}[socket]{fileno}{}
ソケットのファイルディスクリプタを整数型で返します。ファイルディスクリプ
タは、\function{select.select()}などで使用します。

Windowsではこのメソッドで返された小整数をファイルディスクリプタを扱う箇
所(\function{os.fdopen()}など)で利用できません。
\UNIX{} にはこの制限はありません。
\end{methoddesc}

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

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

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

\begin{methoddesc}[socket]{listen}{backlog}
ソケットをListenし、接続を待ちます。引数\var{backlog}には接続キューの最
大の長さ(1以上)を指定します。\var{backlog}の最大数はシステムに依存します
(通常は5)。
\end{methoddesc}

\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}}
ソケットに関連付けられた\dfn{ファイルオブジェクト}を返します(ファイルオ
ブジェクトについては\ref{bltin-file-objects}の``ファイルオブジェクト''を
参照)。ファイルオブジェクトはソケットを\cfunction{dup()}したファイルディ
スクリプタを使用しており、ソケットオブジェクトとファイルオブジェクトは
別々にクローズしたりガベージコレクションで破棄したりする事ができます。ソ
ケットはブロッキングモードでなければなりません。
\index{I/O control!buffering}オプション引数の\var{mode}と\var{bufsize}
には、\function{file()}組み込み関数と同じ値を指定します。
\ref{built-in-funcs}の``組み込み関数''を参照してください。
\end{methoddesc}

\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
ソケットからデータを受信し、文字列として返します。受信する最大バイト数
は、\var{bufsize}で指定します。\var{flags}のデフォルト値は0です。値の意
味については\UNIX{}マニュアルページの\manpage{recv}{2}を参照してくださ
い。
\note{ハードウェアおよびネットワークの現実に最大限マッチするように、
\var{bufsize}の値は比較的小さい2の累乗、たとえば 4096、にすべきです。}
\end{methoddesc}

\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
ソケットからデータを受信し、結果をタプル\code{(\var{string},
\var{address})}として返します。\var{string}は受信データの文字列で、
\var{address}は送信元のアドレスを示します。オプション引数\var{flags}の意
味は、上記\method{recv()}と同じです。\var{address}のフォーマットはアドレ
スファミリによって異なります(前述)。
\end{methoddesc}

\begin{methoddesc}[socket]{send}{string\optional{, flags}}
ソケットにデータを送信します。ソケットはリモートソケットに接続済みでなけ
ればなりません。オプション引数\var{flags}の意味は、上記\method{recv()}と
同じです。戻り値として、送信したバイト数を返します。アプリケーションで
は、必ず戻り値をチェックし、全てのデータが送られた事を確認する必要があり
ます。データの一部だけが送信された場合、アプリケーションで残りのデータを
再送信してください。
\end{methoddesc}

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

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

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

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

\begin{methoddesc}[socket]{gettimeout}{}
ソケットに指定されたタイムアウト値を取得します。タイムアウト値が設定され
ている場合には浮動小数点型で秒数が、設定されていなければ\code{None}が返
ります。この値は、最後に呼び出された\method{setblocking()}または
\method{settimeout()}によって設定されます。\versionadded{2.3}
\end{methoddesc}

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

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

註: \method{connect()}はタイムアウト設定に従います。一般的に、
\method{settimeout()}を\method{connect()}の前に呼ぶことをおすすめします。


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

\begin{methoddesc}[socket]{shutdown}{how}
接続の片方向、または両方向を切断します。\var{how}が\constant{SHUT_RD}の場合、以降
は受信を行えません。\var{how}が\constant{SHUT_WR}の場合、以降は送信を行えません。
\var{how}が\code{SHUT_RDWR}の場合、以降は送受信を行えません。
\end{methoddesc}

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

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

\begin{memberdesc}[socket]{family}
ソケットファミリー。
\versionadded{2.5}
\end{memberdesc}

\begin{memberdesc}[socket]{type}
ソケットタイプ。
\versionadded{2.5}
\end{memberdesc}

\begin{memberdesc}[socket]{proto}
ソケットプロトコル。
\versionadded{2.5}
\end{memberdesc}


\subsection{SSL オブジェクト \label{ssl-objects}}

SSLオブジェクトには、以下のメソッドがあります。

\begin{methoddesc}[SSL]{write}{s}
文字列\var{s}をSSL接続で出力します。戻り値として、送信したバイト数を返し
ます。
\end{methoddesc}

\begin{methoddesc}[SSL]{read}{\optional{n}}
SSL接続からデータを受信します。\var{n}を指定した場合は指定したバイト数の
データを受信し、省略時はEOFまで読み込みます。戻り値として、受信したバイ
ト列の文字列を返します。
\end{methoddesc}

\begin{methoddesc}[SSL]{server}{}
サーバの証明書を特定するための ASN.1 識別名(distinguished name)を含む文字列を
返します。(下の例を見ると識別名がどう見えるものか判ります。)
\end{methoddesc}

\begin{methoddesc}[SSL]{issuer}{}
サーバの証明書の発行者を特定するための ASN.1 識別名(distinguished
name)を含む文字列を返します。
\end{methoddesc}

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

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

\begin{verbatim}
# Echo server program
import socket

HOST = ''                 # Symbolic name meaning the local host
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.send(data)
conn.close()
\end{verbatim}

\begin{verbatim}
# 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.send('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', repr(data)
\end{verbatim}

The next two examples are identical to the above two, but support both
IPv4 and IPv6.
The server side will listen to the first address family available
(it should listen to both instead).
On most of IPv6-ready systems, IPv6 will take precedence
and the server may not accept IPv4 traffic.
The client side will try to connect to the all addresses returned as a result
of the name resolution, and sends traffic to the first one connected
successfully.

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


\begin{verbatim}
# Echo server program
import socket
import sys

HOST = ''                 # Symbolic name meaning the local host
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, msg:
	s = None
	continue
    try:
	s.bind(sa)
	s.listen(1)
    except socket.error, 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()
\end{verbatim}

\begin{verbatim}
# 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, msg:
	s = None
	continue
    try:
	s.connect(sa)
    except socket.error, msg:
	s.close()
	s = None
	continue
    break
if s is None:
    print 'could not open socket'
    sys.exit(1)
s.send('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', repr(data)
\end{verbatim}


次の例ではSSLサーバに接続し、サーバおよび発行者の識別名(distinguished name)
を表示し、いくらかのバイトを送り、レスポンスの一部を読みます:

\begin{verbatim}
import socket

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect(('www.verisign.com', 443))

ssl_sock = socket.ssl(s)

print repr(ssl_sock.server())
print repr(ssl_sock.issuer())

# Set a simple HTTP request -- use httplib in actual code.
ssl_sock.write("""GET / HTTP/1.0\r
Host: www.verisign.com\r\n\r\n""")

# Read a chunk of data.  Will not necessarily
# read all the data returned by the server.
data = ssl_sock.read()

# Note that you need to close the underlying socket, not the SSL object.
del ssl_sock
s.close()
\end{verbatim}

執筆時点で、このSSL実行例は次のような出力を表示しました
(読み易いように改行は入れてあります):

\begin{verbatim}
'/C=US/ST=California/L=Mountain View/
 O=VeriSign, Inc./OU=Production Services/
 OU=Terms of use at www.verisign.com/rpa (c)00/
 CN=www.verisign.com'
'/O=VeriSign Trust Network/OU=VeriSign, Inc./
 OU=VeriSign International Server CA - Class 3/
 OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
\end{verbatim}
