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

このモジュールは、PythonでBSD ソケット インターフェースを利用する ために使用します。最近のUnixシステム、Windows, MacOS, 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 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の タプルで示し、flowinfoscopeidにはそれぞれCの struct sockaddr_in6におけるsin6_flowinfosin6_scope_idの値を指定します。後方互換性のため、socket モジュールのメソッドではsin6_flowinfosin6_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 のペアで表現されます

エラー時には例外が発生します。引数型のエラーやメモリ不足の場合には通常の 例外が発生し、ソケットやアドレス関連のエラーの場合は 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_STREAMSOCK_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 です。

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

(family, socktype, proto, canonname, sockaddr)

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

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

getfqdn( [name])
nameの完全修飾ドメイン名を返します。nameが空または省略された 場合、ローカルホストを指定したとみなします。完全修飾ドメイン名の取得には まずgethostbyaddr()でチェックし、次に可能であればエイリアスを 調べ、名前にピリオドを含む最初の名前を値として返します。完全修飾ドメイ ン名を取得できない場合、gethostname()で返されるホスト名を返します。 バージョン 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)のタプルで、hostnameip_addressで指定したホストの正式名、aliaslistは同じアドレス の別名のリスト(空の場合もある)、ipaddrlistは同じホスト上の同一イ ンターフェースのIPv4アドレスのリスト(ほとんどの場合は単一のアドレスのみ) を示します。gethostbyname()は、IPv6名前解決をサポートしていま せん。IPv4/v6のデュアルスタックをサポートする場合は getaddrinfo()を使用します。

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

gethostbyaddr( ip_address)
(hostname, aliaslist, ipaddrlist)のタプルを返 し、hostnameip_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'のどちら かを指定することができます。指定がなければどちらのプロトコルにもマッチ します。

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

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

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

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

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

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

利用可能: Unix. バージョン 2.4 で 新たに追加 された仕様です。

fromfd( fd, family, type[, proto])
ファイルディスクリプタ (ファイルオブジェクトのfileno()で返る 整数) fd を複製して、ソケットオブジェクトを構築します。アドレス ファミリとプロトコル番号は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_INETAF_INET6です。ip_stringに不正なIPアドレス文字列を指定す ると、socket.errorが発生します。有効なip_stringは、 address_familyinet_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_INETAF_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:モジュール
ネットワークサーバの開発を省力化するためのク ラス群。.



Subsections
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。