18.1. `socket` — 低水準ネットワークインターフェース¶

ソースコード: Lib/socket.py

このモジュールはBSDの ソケット(socket) インターフェースへのアクセスを提供します。これは、近代的なUnixシステム、Windows、MacOS、その他多くのプラットフォームで動作します。

注釈

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

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

参考

Module socketserver: ネットワークサーバの開発を省力化するためのクラス群。
Module ssl: ソケットオブジェクトに対する TLS/SSL ラッパー.

18.1.1. ソケットファミリー¶

どのシステムで実行するかとビルドオプションに依存しますが、このモジュールによって多様なソケットファミリーをサポートします。

特定のソケットオブジェクトによって必要とされるアドレスフォーマットは、ソケットオブジェクトが生成されたときに指定されたアドレスファミリーを元に自動的に選択されます。ソケットアドレスは次の通りです。

ファイルシステム上のノードに束縛された AF_UNIX ソケットのアドレスは、ファイルシステムエンコーディングと 'surrogateescape' エラーハンドラ (PEP 383 を参照) を使って文字列として表現されます。 Linux の抽象名前空間のアドレスは、先頭が null バイトとなる bytes-like object として返されます。この名前空間のソケットは通常のファイルシステム上のソケットと通信できるので、 Linux 上で動作することを意図したプログラムは両方のアドレスを扱う必要がある可能性があります。文字列と bytes-like オブジェクトはどちらのタイプのアドレスにも引数として渡すことができます。

バージョン 3.3 で変更: これまでは AF_UNIX ソケットパスは UTF-8 エンコーディングを使用するものとされていました。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

AF_INET アドレスファミリーには、 (host, port) ペアがアドレスとして利用されます。 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 モジュールのメソッドでは、後方互換性のために flowinfo と scopeid の省略を許しています。しかし、 scopeid を省略すると scope された IPv6 アドレスを操作するときに問題が起こる場合があることに注意してください。
AF_NETLINK ソケットのアドレスは (pid, groups) のペアで表されます。
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であるべきです。
AF_CAN アドレスファミリーには (interface,) というタプルを利用します。 interface は 'can0' のようなネットワークインタフェース名を表す文字列です。このファミリーの全てのネットワークインタフェースからパケットを受信するために、ネットワークインタフェース名 '' を利用できます。
文字列またはタプル (id, unit) は PF_SYSTEM ファミリーの SYSPROTO_CONTROL プロトコルのために使用されます。この文字列は、動的に割り当てられたIDによるカーネルコントロールの名前です。このタプルは、カーネルコントロールのIDとユニット番号が既知の場合、または登録済みIDが使用中の場合に使用することができます。

バージョン 3.3 で追加.
AF_BLUETOOTH は以下のプロトコルとアドレスフォーマットをサポートしています。
- BTPROTO_L2CAP は (bdaddr, psm) を受け取ります。 bdaddr は Bluetooth アドレスを表す文字列で、 psm は整数です。
- BTPROTO_RFCOMM は (bdaddr, channel) を受け取ります。 bdaddr は Bluetooth アドレスを表す文字列で、 channel は整数です。
- BTPROTO_HCI accepts (device_id,) where device_id is either an integer or a string with the Bluetooth address of the interface. (This depends on your OS; NetBSD and DragonFlyBSD expect a Bluetooth address while everything else expects an integer.)
  
  バージョン 3.2 で変更: NetBSD と DragonFlyBSD のサポートが追加されました。
- BTPROTO_SCO accepts bdaddr where bdaddr is a bytes object containing the Bluetooth address in a string format. (ex. b'12:23:34:45:56:67') This protocol is not supported under FreeBSD.
その他の特定のアドレスファミリー (AF_PACKET, AF_CAN) は、それぞれ固有の形式をサポートしています。

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

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

全てのエラーは例外を発生させます。引数型のエラーやメモリ不足の場合には通常の例外が発生し、ソケットやアドレス関連のエラーは Python 3.3 からは OSError かそのサブクラスを発生させます (Python 3.3 以前は socket.error を発生させていました)。

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

18.1.2. モジュールの内容¶

socket モジュールは以下の要素を公開しています。

18.1.2.1. 例外¶

exception socket.error¶: OSError の非推奨のエイリアス。

バージョン 3.3 で変更: PEP 3151 に基づき、このクラスは OSError のエイリアスになりました。

exception socket.herror¶: OSError のサブクラス。この例外はアドレス関連のエラー、つまり gethostbyname_ex() と gethostbyaddr() などの、 POSIX C API の h_errno を利用する関数のために利用されます。例外に付随する (h_errno, string) ペアはライブラリの呼び出しによって返されたエラーを表します。 h_errno は数値で、 string は、 hstrerror() C関数によって返される h_errno を説明する文字列です。

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

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

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

exception socket.timeout¶: OSError のサブクラスです。この例外は、あらかじめ settimeout() を呼び出して (あるいは setdefaulttimeout() を利用して暗黙に) タイムアウトを有効にしてあるソケットでタイムアウトが生じた際に送出されます。例外に付属する値は文字列で、その内容は現状では常に “timed out” となります。

バージョン 3.3 で変更: このクラスは OSError のサブクラスになりました。

18.1.2.2. 定数¶

AF_* 定数と SOCK_* 定数は、 AddressFamily と SocketKind IntEnum collection になりました。

バージョン 3.4 で追加.

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 以外は必要ありません。)

socket.SOCK_CLOEXEC¶

socket.SOCK_NONBLOCK¶

この2つの定数が定義されていた場合、ソケットタイプと組み合わせていくつかの flags をアトミックに設定することができます (別の呼び出しを不要にして競合状態を避ける事ができます)。

参考

より完全な説明は Secure File Descriptor Handling を参照してください。

利用できる環境: Linux 2.6.27 以降。

バージョン 3.2 で追加.

SO_*
socket.SOMAXCONN¶
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*: Unixのソケット・IPプロトコルのドキュメントで定義されている各種定数。ソケットオブジェクトの setsockopt() や getsockopt() で使用します。ほとんどのシンボルはUnixのヘッダファイルに従っています。一部のシンボルには、デフォルト値を定義してあります。

socket.AF_CAN¶

socket.PF_CAN¶

SOL_CAN_*

CAN_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

利用できる環境: Linux 2.6.25 以降。

バージョン 3.3 で追加.

socket.CAN_BCM¶

CAN_BCM_*

CANプロトコルファミリーのCAN_BCMは、ブロードキャストマネージャー(BCM)プロトコルです。Linuxドキュメントにあるこの形式の定数は、socketモジュールでも定義されています。

利用できる環境: Linux 2.6.25 以降。

バージョン 3.4 で追加.

socket.CAN_RAW_FD_FRAMES¶

Enables CAN FD support in a CAN_RAW socket. This is disabled by default. This allows your application to send both CAN and CAN FD frames; however, you one must accept both CAN and CAN FD frames when reading from the socket.

この定数は、 Linux のドキュメンテーションで説明されています。

利用できる環境: Linux 3.6 以降。

バージョン 3.5 で追加.

socket.AF_RDS¶

socket.PF_RDS¶

socket.SOL_RDS¶

RDS_*

Linux ドキュメントにあるこの形式の定数は socket モジュールでも定義されています。

利用できる環境: Linux 2.6.30 以降。

バージョン 3.3 で追加.

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

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

socket.AF_LINK¶: 利用可能: BSD, OSX.

バージョン 3.4 で追加.

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

socket.BDADDR_ANY¶
socket.BDADDR_LOCAL¶: These are string constants containing Bluetooth addresses with special meanings. For example, BDADDR_ANY can be used to indicate any address when specifying the binding socket with BTPROTO_RFCOMM.

socket.HCI_FILTER¶
socket.HCI_TIME_STAMP¶
socket.HCI_DATA_DIR¶: For use with BTPROTO_HCI. HCI_FILTER is not available for NetBSD or DragonFlyBSD. HCI_TIME_STAMP and HCI_DATA_DIR are not available for FreeBSD, NetBSD, or DragonFlyBSD.

18.1.2.3. 関数¶

18.1.2.3.1. ソケットの作成¶

以下の関数は全て socket object を生成します。

socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)¶

アドレスファミリー、ソケットタイプ、プロトコル番号を指定して新しいソケットを作成します。アドレスファミリーには AF_INET (デフォルト値)、 AF_INET6 、 AF_UNIX 、 AF_CAN 、または AF_RDS を指定します。ソケットタイプには SOCK_STREAM (デフォルト値)、 SOCK_DGRAM 、 SOCK_RAW 、または他の SOCK_ 定数を指定します。プロトコル番号は通常省略するか、または0を指定しますが、アドレスファミリーに AF_CAN を指定した場合は、プロトコル番号には CAN_RAW か CAN_BCM のいずれかを指定すべきです。fileno を指定した場合、別の引数が無視されるため、指定されたファイル記述子のソケットが返ります。fileno は、socket.fromfd() とは異なり、ソケットの複製ではなく、同一のソケットを返します。このことは、切り離されたソケットを socket.close() で閉じるのに役立つ場合があります。

新たに作成されたソケットは継承不可です。

バージョン 3.3 で変更: AF_CAN, AF_RDS ファミリーが追加されました。

バージョン 3.4 で変更: CAN_BCMプロトコルが追加されました。

バージョン 3.4 で変更: 返されるソケットは継承不可になりました。

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

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

新たに作成されたソケットは継承不可です。

バージョン 3.2 で変更: 返されるソケットオブジェクトが、サブセットではなく完全なソケットAPIを提供するようになりました。

バージョン 3.4 で変更: 返されるソケットの組は、どちらも継承不可になりました。

バージョン 3.5 で変更: Windows のサポートが追加されました。

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のデフォルトの動作になります。

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

socket.fromfd(fd, family, type, proto=0)¶

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

新たに作成されたソケットは継承不可です。

バージョン 3.4 で変更: 返されるソケットは継承不可になりました。

socket.fromshare(data)¶

socket.share() メソッドから取得した data からソケットオブジェクトを生成します。ソケットはブロッキングモードだと仮定されます。

利用出来る環境 : Windows.

バージョン 3.3 で追加.

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

18.1.2.3.2. その他の関数¶

socket モジュールはネットワーク関連のサービスを提供しています:

socket.getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)¶

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

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

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

(family, type, proto, canonname, sockaddr)

このタプルにある family, type, 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, proto=socket.IPPROTO_TCP)
[(<AddressFamily.AF_INET6: 10>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (<AddressFamily.AF_INET: 2>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('93.184.216.34', 80))]

バージョン 3.2 で変更: パラメータをキーワード引数で渡すことができるようになりました。

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

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インタープリタを現在実行しているマシンのホスト名を含む文字列を返します。

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

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 は文字列のポート名または数値のポート番号となります。

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

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

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

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アドレス文字列が不正であれば、 OSError が発生します。このチェックは、この関数で使用しているCの実装 inet_aton() で行われます。

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

socket.inet_ntoa(packed_ip)¶

32 ビットにパックされた IPv4 アドレス (長さ 4 バイトの bytes-like object) を、標準的なドット記法による 4 桁の文字列 ('123.45.67.89' など) に変換します。この関数は、struct in_addr 型を使用する標準 C ライブラリのプログラムとやりとりする場合に便利です。struct in_addr 型は、この関数が引数として受け取る 32 ビットにパックされたバイナリデータに対する C の型です。

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

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

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アドレス文字列を指定すると、 OSError が発生します。有効な ip_string は、 address_family と inet_pton() の実装によって異なります。

利用可能: Unix (一部のプラットフォームを除く)、Windows。

バージョン 3.4 で変更: Windowsで利用可能になりました

socket.inet_ntop(address_family, packed_ip)¶

パックしたIPアドレス (数バイトからなる bytes-like オブジェクト ) を、 '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() の呼び出しでエラーが起こると、 OSError が発生します。

利用可能: Unix (一部のプラットフォームを除く)、Windows。

バージョン 3.4 で変更: Windowsで利用可能になりました

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

socket.CMSG_LEN(length)¶

指定された length にある制御メッセージ（CMSG）から、末尾のパディングを除いた全体の長さを返します。この値は多くの場合、 recvmsg() が制御メッセージの一連の要素を受信するためのバッファサイズとして使用できますが、バッファの末尾が要素である場合であってもパディングは含まれるので、バッファサイズを取得するには RFC 3542 で求められているように、 CMSG_SPACE() を使用した移植可能なアプリケーションが必要です。通常 length は定数であり、許容範囲外の値が指定された場合は OverflowError 例外が送出されます。

利用できる環境: 主な Unix で利用できます。他のプラットフォームでも、利用できる場合があります。

バージョン 3.3 で追加.

socket.CMSG_SPACE(length)¶

指定された length の制御メッセージ（CMSG）の要素を recvmsg() が受信するために必要な、パディングを含めたバッファサイズを返します。複数の項目を受信するために必要なバッファスペースは、 CMSG_SPACE() が返すそれぞれの要素の長さの合計です。通常 length は定数であり、許容範囲外の値が指定された場合は OverflowError 例外が送出されます。

一部のシステムではこの関数を提供せずに制御メッセージをサポートする可能性があることに注意してください。また、この関数の返り値を使用して設定するバッファサイズは、受信する制御メッセージの量を正確に規定しないことがあり、その後に受信するデータがパディング領域に合う場合があることに注意してください。

利用できる環境: 主な Unix で利用できます。他のプラットフォームでも、利用できる場合があります。

バージョン 3.3 で追加.

socket.getdefaulttimeout()¶: 新規に生成されたソケットオブジェクトの、デフォルトのタイムアウト値を秒数 (float 型) で返します。タイムアウトを使用しない場合には None を返します。最初に socket モジュールがインポートされた時の初期値は None です。

socket.setdefaulttimeout(timeout)¶: 新規に生成されるソケットオブジェクトの、デフォルトのタイムアウト値を秒数 (float 型) で設定します。最初に socket モジュールがインポートされた時の初期値は None です。指定可能な値とその意味については settimeout() メソッドを参照してください。

socket.sethostname(name)¶

マシンのホスト名を name に設定します。必要な権限がない場合は OSError を送出します。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

socket.if_nameindex()¶

ネットワークインターフェース情報 (index int, name string)のタプルを返します。システムコールが失敗した場合、 OSError 例外を送出します。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

socket.if_nametoindex(if_name)¶

インターフェース名 if_name に対応するネットワークインターフェースのインデックス番号を返します。対応するインターフェースが存在しない場合は OSError 例外を送出します。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

socket.if_indextoname(if_index)¶

インターフェースインデックス番号 if_index に対応するネットワークインターフェース名を返します。対応するインターフェースが存在しない場合は OSError 例外を送出します。

利用できる環境 : Unix 。

バージョン 3.3 で追加.

18.1.3. socket オブジェクト¶

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

バージョン 3.2 で変更: Support for the context manager protocol was added. Exiting the context manager is equivalent to calling close().

socket.accept()¶

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

新たに作成されたソケットは継承不可です。

バージョン 3.4 で変更: ソケットが継承不可になりました。

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

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

socket.close()¶

ソケットを閉じられたものとしてマークします。 makefile() が返したファイルオブジェクトを閉じる時、対応する下層のシステムリソース（例：ファイル記述子）もすべて閉じます。一度この操作をすると、その後、このソケットオブジェクトに対するすべての操作が失敗します。キューに溜まったデータがフラッシュされた後は、リモート側の端点ではそれ以上のデータを受信しません。

ソケットはガベージコレクション時に自動的にクローズされます。しかし、明示的に close() するか、 with 文の中でソケットを使うことを推奨します。

注釈

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

socket.connect(address)¶

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

If the connection is interrupted by a signal, the method waits until the connection completes, or raise a socket.timeout on timeout, if the signal handler doesn’t raise an exception and the socket is blocking or has a timeout. For non-blocking sockets, the method raises an InterruptedError exception if the connection is interrupted by a signal (or the exception raised by the signal handler).

バージョン 3.5 で変更: The method now waits until the connection completes instead of raising an InterruptedError exception if the connection is interrupted by a signal, the signal handler doesn’t raise an exception and the socket is blocking or has a timeout (see the PEP 475 for the rationale).

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

socket.detach()¶: 実際にファイル記述子を閉じることなく、ソケットオブジェクトを閉じた状態にします。ファイル記述子は返却され、他の目的に再利用することができます。

バージョン 3.2 で追加.

socket.dup()¶

ソケットを複製します。

新たに作成されたソケットは継承不可です。

バージョン 3.4 で変更: ソケットが継承不可になりました。

socket.fileno()¶

ソケットのファイル記述子を短い整数型で返します。失敗時には、-1 を返します。ファイル記述子は、 select.select() などで使用します。

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

socket.get_inheritable()¶: ソケットのファイル記述子またはソケットのハンドルの継承可能フラグを取得します。ソケットが子プロセスへ継承可能なら True 、継承不可なら False を返します。

バージョン 3.4 で追加.

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

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

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

socket.gettimeout()¶: ソケットに設定されたタイムアウト値を取得します。タイムアウト値が設定されていればfloat型で秒数を、設定されていなければ None を返します。この値は、最後に呼び出された setblocking() または settimeout() によって設定されます。

socket.ioctl(control, option)¶

Platform:	Windows

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

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

socket.listen([backlog])¶: Enable a server to accept connections. If backlog is specified, it must be at least 0 (if it is lower, it is set to 0); it specifies the number of unaccepted connections that the system will allow before refusing new connections. If not specified, a default reasonable value is chosen.

バージョン 3.5 で変更: backlog 引数が任意になりました。

socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)¶

ソケットに関連付けられたファイルオブジェクトを返します。戻り値の正確な型は、 makefile() に指定した引数によります。これらの引数は、組み込み関数 open() の引数と同様に解釈されます。ただし、mode の値は 'r' (デフォルト), 'w', 'b' のみがサポートされています。

ソケットはブロッキングモードでなければなりません。タイムアウトを設定することはできますが、タイムアウトが発生すると、ファイルオブジェクトの内部バッファが矛盾した状態になることがあります。

makefile() でファイルオブジェクトにソケットを関連づけた場合、ソケットを閉じるには、関連づけられたすべてのファイルオブジェクトを閉じたあとで、元のソケットの socket.close() を呼び出さなければなりません。

注釈

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

socket.recv(bufsize[, flags])¶: ソケットからデータを受信し、結果を bytes オブジェクトで返します。一度に受信するデータは、最大でも bufsize で指定した量です。オプション引数 flags に指定するフラグの意味については、 Unix のマニュアルページ recv(2) を参照してください。 flags のデフォルトは 0 です。

注釈

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

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

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

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.recvmsg(bufsize[, ancbufsize[, flags]])¶

Receive normal data (up to bufsize bytes) and ancillary data from the socket. The ancbufsize argument sets the size in bytes of the internal buffer used to receive the ancillary data; it defaults to 0, meaning that no ancillary data will be received. Appropriate buffer sizes for ancillary data can be calculated using CMSG_SPACE() or CMSG_LEN(), and items which do not fit into the buffer might be truncated or discarded. The flags argument defaults to 0 and has the same meaning as for recv().

The return value is a 4-tuple: (data, ancdata, msg_flags, address). The data item is a bytes object holding the non-ancillary data received. The ancdata item is a list of zero or more tuples (cmsg_level, cmsg_type, cmsg_data) representing the ancillary data (control messages) received: cmsg_level and cmsg_type are integers specifying the protocol level and protocol-specific type respectively, and cmsg_data is a bytes object holding the associated data. The msg_flags item is the bitwise OR of various flags indicating conditions on the received message; see your system documentation for details. If the receiving socket is unconnected, address is the address of the sending socket, if available; otherwise, its value is unspecified.

On some systems, sendmsg() and recvmsg() can be used to pass file descriptors between processes over an AF_UNIX socket. When this facility is used (it is often restricted to SOCK_STREAM sockets), recvmsg() will return, in its ancillary data, items of the form (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds), where fds is a bytes object representing the new file descriptors as a binary array of the native C int type. If recvmsg() raises an exception after the system call returns, it will first attempt to close any file descriptors received via this mechanism.

Some systems do not indicate the truncated length of ancillary data items which have been only partially received. If an item appears to extend beyond the end of the buffer, recvmsg() will issue a RuntimeWarning, and will return the part of it which is inside the buffer provided it has not been truncated before the start of its associated data.

On systems which support the SCM_RIGHTS mechanism, the following function will receive up to maxfds file descriptors, returning the message data and a list containing the descriptors (while ignoring unexpected conditions such as unrelated control messages being received). See also sendmsg().

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if (cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS):
            # Append data, ignoring any truncated integers at the end.
            fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

利用できる環境: 主な Unix で利用できます。他のプラットフォームでも、利用できる場合があります。

バージョン 3.3 で追加.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.recvmsg_into(buffers[, ancbufsize[, flags]])¶

Receive normal data and ancillary data from the socket, behaving as recvmsg() would, but scatter the non-ancillary data into a series of buffers instead of returning a new bytes object. The buffers argument must be an iterable of objects that export writable buffers (e.g. bytearray objects); these will be filled with successive chunks of the non-ancillary data until it has all been written or there are no more buffers. The operating system may set a limit (sysconf() value SC_IOV_MAX) on the number of buffers that can be used. The ancbufsize and flags arguments have the same meaning as for recvmsg().

The return value is a 4-tuple: (nbytes, ancdata, msg_flags, address), where nbytes is the total number of bytes of non-ancillary data written into the buffers, and ancdata, msg_flags and address are the same as for recvmsg().

例

>>> import socket
>>> s1, s2 = socket.socketpair()
>>> b1 = bytearray(b'----')
>>> b2 = bytearray(b'0123456789')
>>> b3 = bytearray(b'--------------')
>>> s1.send(b'Mary had a little lamb')
22
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
(22, [], 0, None)
>>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]

利用できる環境: 主な Unix で利用できます。他のプラットフォームでも、利用できる場合があります。

バージョン 3.3 で追加.

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

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

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

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

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

バージョン 3.5 で変更: The socket timeout is no more reset each time data is sent successfully. The socket timeout is now the maximum total duration to send all data.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

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

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.sendmsg(buffers[, ancdata[, flags[, address]]])¶

Send normal and ancillary data to the socket, gathering the non-ancillary data from a series of buffers and concatenating it into a single message. The buffers argument specifies the non-ancillary data as an iterable of bytes-like objects (e.g. bytes objects); the operating system may set a limit (sysconf() value SC_IOV_MAX) on the number of buffers that can be used. The ancdata argument specifies the ancillary data (control messages) as an iterable of zero or more tuples (cmsg_level, cmsg_type, cmsg_data), where cmsg_level and cmsg_type are integers specifying the protocol level and protocol-specific type respectively, and cmsg_data is a bytes-like object holding the associated data. Note that some systems (in particular, systems without CMSG_SPACE()) might support sending only one control message per call. The flags argument defaults to 0 and has the same meaning as for send(). If address is supplied and not None, it sets a destination address for the message. The return value is the number of bytes of non-ancillary data sent.

The following function sends the list of file descriptors fds over an AF_UNIX socket, on systems which support the SCM_RIGHTS mechanism. See also recvmsg().

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

利用できる環境: 主な Unix で利用できます。他のプラットフォームでも、利用できる場合があります。

バージョン 3.3 で追加.

バージョン 3.5 で変更: システムコールが中断されシグナルハンドラが例外を送出しなかった場合、このメソッドは InterruptedError 例外を送出する代わりにシステムコールを再試行するようになりました (論拠については PEP 475 を参照してください)。

socket.sendfile(file, offset=0, count=None)¶: Send a file until EOF is reached by using high-performance os.sendfile and return the total number of bytes which were sent. file must be a regular file object opened in binary mode. If os.sendfile is not available (e.g. Windows) or file is not a regular file send() will be used instead. offset tells from where to start reading the file. If specified, count is the total number of bytes to transmit as opposed to sending the file until EOF is reached. File position is updated on return or also in case of error in which case file.tell() can be used to figure out the number of bytes which were sent. The socket must be of SOCK_STREAM type. Non-blocking sockets are not supported.

バージョン 3.5 で追加.

socket.set_inheritable(inheritable)¶: ソケットのファイル記述子、またはソケットのハンドルの、継承可能フラグを立てます。

バージョン 3.4 で追加.

socket.setblocking(flag)¶

ソケットをブロッキングモード、または非ブロッキングモードに設定します。flag が False ならばソケットは非ブロッキングモードになり、さもなくばブロッキングモードになります。

このメソッドは、次の settimeout() 呼び出しの省略表記です:

sock.setblocking(True) は sock.settimeout(None) と等価です
sock.setblocking(False) は sock.settimeout(0.0) と等価です

socket.settimeout(value)¶

ソケットのブロッキング処理のタイムアウト値を指定します。 value には float 型で秒数を指定するか、 None を指定します。float を指定したならば、ソケットの操作が完了する前に value で指定した秒数が経過すれば timeout 例外を送出します。 None を指定すると、ソケットのタイムアウトを無効にします。

詳しくはソケットタイムアウトの注意事項を参照してください。

socket.setsockopt(level, optname, value)¶: 指定したソケットオプションの値を設定します (Unixのマニュアルページ setsockopt(2) を参照)。SO_* などの必要なシンボリック定数は、 socket モジュールで定義されています。値には、整数または bytes-like オブジェクトをバッファとして指定する事ができます。bytes-like オブジェクトを指定する場合、呼び出し側が責任を持ってバイト文字列に適切なビットが含まれるようにします (組み込みの struct モジュールを利用すれば、Cの構造体をバイト文字列としてエンコードする事ができます)。

バージョン 3.5 で変更: 書き込み可能な bytes-like object を使用できるようになりました。

socket.shutdown(how)¶: 接続の片方向、または両方向を切断します。 how が SHUT_RD の場合、以降は受信を行えません。 how が SHUT_WR の場合、以降は送信を行えません。 how が SHUT_RDWR の場合、以降は送受信を行えません。

socket.share(process_id)¶

ソケットを複製し、対象のプロセスと共有するための bytes オブジェクトを返します。対象のプロセスを process_id で指定しなければなりません。戻り値の bytes オブジェクトは、何らかのプロセス間通信を使って対象のプロセスに伝えます。対象のプロセス側では、 fromshare() を使って複製されたソケットをとらえます。オペレーティング・システムは対象のプロセスに対してソケットを複製するため、このメソッドを呼び出した後であれば、元のソケットをクローズしても、対象のプロセスに渡ったソケットには影響がありません。

利用出来る環境 : Windows.

バージョン 3.3 で追加.

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

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

socket.family¶: ソケットファミリー。

socket.type¶: ソケットタイプ。

socket.proto¶: ソケットプロトコル。

18.1.4. ソケットタイムアウトの注意事項¶

ソケットオブジェクトは、ブロッキングモード、非ブロッキングモード、タイムアウトモードのうち、いずれか1つのモードをとります。デフォルトでは、ソケットは常にブロッキングモードで作成されますが、 setdefaulttimeout() で標準のモードを変更することができます。

ブロッキングモード での操作は、完了するか、または（接続がタイムアウトするなどして）システムがエラーを返すまで、ブロックされます。
非ブロッキングモード での操作は、ただちに完了できない場合、例外を送出して失敗します。この場合の例外の種類は、システムに依存するため、ここに記すことができません。 select モジュールの関数を使って、ソケットの読み書きが利用可能かどうか、可能な場合はいつ利用できるかを調べることができます。
タイムアウトモード での操作は、指定されたタイムアウトの時間内に完了しなければ、 timeout 例外を送出します。タイムアウトの時間内にシステムがエラーを返した場合は、そのエラーを返します。

注釈

オペレーティング・システムのレベルでは、 タイムアウトモード のソケットには、内部的に非ブロッキングモードが設定されています。またブロッキングモードとタイムアウトモードの指定は、ファイル記述子と、「そのファイル記述子と同じネットワーク端点を参照するソケットオブジェクト」との間で共有されます。このことは、例えばソケットの fileno() を使うことにした場合に、明らかな影響を与えます。

18.1.4.1. タイムアウトと `connect` メソッド¶

connect() もタイムアウト設定に従います。一般的に、 settimeout() を connect() の前に呼ぶか、 create_connection() にタイムアウト引数を渡すことが推奨されます。ただし、システムのネットワークスタックが Python のソケットタイムアウトの設定を無視して、自身の接続タイムアウトエラーを返すこともあります。

18.1.4.2. タイムアウトと `accept` メソッド¶

If getdefaulttimeout() is not None, sockets returned by the accept() method inherit that timeout. Otherwise, the behaviour depends on settings of the listening socket:

if the listening socket is in blocking mode or in timeout mode, the socket returned by accept() is in blocking mode;
if the listening socket is in non-blocking mode, whether the socket returned by accept() is in blocking or non-blocking mode is operating system-dependent. If you want to ensure cross-platform behaviour, it is recommended you manually override this setting.

18.1.5. 例¶

以下は 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
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
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 OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)

# 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 OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
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)

The last example shows how to use the socket interface to communicate to a CAN network using the raw socket protocol. To use CAN with the broadcast manager protocol instead, open a socket with:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

After binding (CAN_RAW) or connecting (CAN_BCM) the socket, you can use the socket.send(), and the socket.recv() operations (and their counterparts) on the socket object as usual.

次の例では、特権が必要になるかもしれません:

import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')

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

OSError: [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 状態にあるローカルソケットをそのタイムアウト期限が自然に切れるのを待つことなく再利用することをカーネルに伝えます。

参考

C 言語によるソケットプログラミングの基礎については、以下の資料を参照してください。

An Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest
An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et al,

両書とも 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” を参照してください。

18.1. `socket` — 低水準ネットワークインターフェース¶

18.1.1. ソケットファミリー¶

18.1.2. モジュールの内容¶

18.1.2.1. 例外¶

18.1.2.2. 定数¶

18.1.2.3. 関数¶

18.1.2.3.1. ソケットの作成¶

18.1.2.3.2. その他の関数¶

18.1.3. socket オブジェクト¶

18.1.4. ソケットタイムアウトの注意事項¶

18.1.4.1. タイムアウトと `connect` メソッド¶

18.1.4.2. タイムアウトと `accept` メソッド¶

18.1.5. 例¶

目次

前のトピックへ

次のトピックへ

このページ

18.1. socket — 低水準ネットワークインターフェース¶

18.1.1. ソケットファミリー¶

18.1.2. モジュールの内容¶

18.1.2.1. 例外¶

18.1.2.2. 定数¶

18.1.2.3. 関数¶

18.1.2.3.1. ソケットの作成¶

18.1.2.3.2. その他の関数¶

18.1.3. socket オブジェクト¶

18.1.4. ソケットタイムアウトの注意事項¶

18.1.4.1. タイムアウトと connect メソッド¶

18.1.4.2. タイムアウトと accept メソッド¶

18.1.5. 例¶

18.1. `socket` — 低水準ネットワークインターフェース¶

18.1.4.1. タイムアウトと `connect` メソッド¶

18.1.4.2. タイムアウトと `accept` メソッド¶