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

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

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

注釈

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

このモジュールは WebAssembly では動作しないか、利用不可です。詳しくは、WebAssembly プラットフォームを見てください。

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

参考

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

ソケットファミリー¶

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

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

ファイルシステム上のノードに束縛された 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 は整数です。
- IPv4ではホストアドレスのほかに2つの特別な形式が使用できます。'' はすべてのインターフェイスにバインドされるために使われる INADDR_ANY を表し、'<broadcast>' は INADDR_BROADCAST を表します。これらの動作はIPv6と互換性がありません。そのためもしもあなたがPythonプログラムでIPv6をサポートする予定があるのならばこれらを避けたほうが良いでしょう。
AF_INET6 アドレスファミリーでは、四要素のタプル (host, port, flowinfo, scope_id) を使います。 flowinfo と scope_id は、C の struct sockaddr_in6 の sin6_flowinfo と sin6_scope_id メンバーを表します。 socket モジュールのメソッドでは、後方互換性のために flowinfo と scope_id を省略できます。ただし、scope_id を省略すると、スコープ付き IPv6 アドレスの操作で問題が生じる場合があります。

バージョン 3.7 で変更: マルチキャストアドレス (scope_id に意味がある場合) では、address に %scope_id (または zone id) の部分を含めなくても構いません。この情報は冗長なので、安全に省略できます (省略を推奨します)。
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 はポート番号の下限、 v3 はポート番号の上限です。
  
  addr_type が TIPC_ADDR_ID の場合、 v1 はノード、 v2 は参照、 v3 は0であるべきです。
AF_CAN アドレスファミリーには (interface, ) というタプルを利用します。 interface は 'can0' のようなネットワークインターフェース名を表す文字列です。このファミリーの全てのネットワークインターフェースからパケットを受信するために、ネットワークインターフェース名 '' を利用できます。
- CAN_ISOTP プロトコルにはタプル (interface, rx_addr, tx_addr) が必要です。追加の二つの引数は、標準または拡張の CAN 識別子を表す符号なし long 整数です。
- CAN_J1939 プロトコルにはタプル (interface, name, pgn, addr) が必要です。追加の引数は順に、ECU 名を表す 64 ビット符号なし整数、パラメーターグループ番号 (PGN) を表す 32 ビット符号なし整数、アドレスを表す 8 ビット整数です。
文字列またはタプル (id, unit) は PF_SYSTEM ファミリーの SYSPROTO_CONTROL プロトコルのために使用されます。この文字列は、動的に割り当てられたIDによるカーネルコントロールの名前です。このタプルは、カーネルコントロールのIDとユニット番号が既知の場合、または登録済みIDが使用中の場合に使用することができます。

Added in version 3.3.
AF_BLUETOOTH は以下のプロトコルとアドレスフォーマットをサポートしています。
- BTPROTO_L2CAP はタプル (bdaddr, psm[, cid[, bdaddr_type]]) を受け取り、各要素は次の意味です。
  - bdaddr は Bluetooth アドレスを指定する文字列です。
  - psm は Protocol/Service Multiplexer を指定する整数です。
  - cid は Channel Identifier を指定する、省略可能な整数です。省略した場合はゼロです。
  - bdaddr_type はアドレスの種類を指定する、省略可能な整数です。 BDADDR_BREDR (デフォルト)、BDADDR_LE_PUBLIC、BDADDR_LE_RANDOM のいずれかです。
  バージョン 3.14 で変更: cid と bdaddr_type フィールドが追加されました。
- BTPROTO_RFCOMM は (bdaddr, channel) を受け取ります。 bdaddr は Bluetooth アドレスを表す文字列で、 channel は整数です。
- BTPROTO_HCI が受け取る形式は OS によって異なります。
  - Linux では、整数 device_id またはタプル (device_id, [channel]) を受け取ります。 device_id は Bluetooth デバイスの番号、channel は HCI チャネルを指定する省略可能な整数です (デフォルトは HCI_CHANNEL_RAW)。
  - FreeBSD、NetBSD、DragonFly BSD では、Bluetooth アドレスを表す文字列 bdaddr を受け取ります。
  バージョン 3.2 で変更: NetBSD と DragonFlyBSD のサポートが追加されました。
  
  バージョン 3.13.3 で変更: FreeBSD のサポートが追加されました。
  
  バージョン 3.14 で変更: channel フィールドが追加されました。タプルに格納されていない device_id も受け取れるようになりました。
- BTPROTO_SCO は、Bluetooth アドレスを表す文字列または bytes オブジェクト bdaddr を受け取ります (例えば '12:23:34:45:56:67' や b'12:23:34:45:56:67')。
  
  バージョン 3.14 で変更: FreeBSD のサポートが追加されました。
AF_ALG はカーネル暗号へのソケットベースのインターフェイスで、Linux でのみ使用できます。アルゴリズムソケットは、2 つから 4 つの要素を持つタプル (type, name [, feat [, mask]]) で構成されます。各要素の意味は、以下の通りです。
- type はアルゴリズムタイプを示す文字列です。例: aead, hash, skcipher または rng。
- name はアルゴリズム名及び操作モードを示す文字列です。例: sha256, hmac(sha256), cbc(aes) または drbg_nopr_ctr_aes256。
- feat と mask は、符号を持たない 32 ビットの整数です。
利用可能な環境: Linux >= 2.6.38.

一部のアルゴリズムタイプでは、さらに新しいカーネルが必要です。

Added in version 3.6.
AF_VSOCK は、仮想マシンとそのホストとの通信を可能にします。ソケットは (CID, port) タプルで表し、コンテキスト ID (CID) とポートは整数です。

利用可能な環境: Linux >= 3.9

vsock(7) を参照してください。

Added in version 3.7.
AF_PACKET は、ネットワークデバイスへ直接アクセスする低水準インターフェースです。アドレスはタプル (ifname, proto[, pkttype[, hatype[, addr]]]) で表し、各要素は次の意味です。
- ifname - デバイス名を指定する文字列。
- proto - Ethernet プロトコル番号です。すべてのプロトコルを取得する ETH_P_ALL、ETHERTYPE_* 定数のいずれか、またはその他の Ethernet プロトコル番号を指定できます。
- pkttype - パケットタイプを指定するオプションの整数:
  - PACKET_HOST (デフォルト) - ローカルホスト宛てのパケット。
  - PACKET_BROADCAST - 物理層のブロードキャストパケット。
  - PACKET_MULTICAST - 物理層のマルチキャストアドレスに送信されたパケット。
  - PACKET_OTHERHOST - プロミスキャスモードのデバイスドライバーが取得した、別のホスト宛てのパケット。
  - PACKET_OUTGOING - ローカルホストから送信され、パケットソケットにループバックされたパケット。
- hatype - ARP ハードウェアアドレスの種類を指定する、省略可能な整数です。
- addr - ハードウェアの物理アドレスを指定する、省略可能なバイト列類似オブジェクトです。その解釈はデバイスによって異なります。
利用可能な環境: Linux >= 2.2.
AF_QIPCRTR は、Qualcomm プラットフォームのコプロセッサー上で動作するサービスと通信するための、Linux 限定のソケットベースのインターフェースです。アドレスファミリーは (node, port) タプルで表し、node と port は非負の整数です。

利用可能な環境: Linux >= 4.7.

Added in version 3.8.
IPPROTO_UDPLITE is a variant of UDP which allows you to specify what portion of a packet is covered with the checksum. It adds two socket options that you can change. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) will change what portion of outgoing packets are covered by the checksum and self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) will filter out packets which cover too little of their data. In both cases length should be in range(8, 2**16, 8).

IPv4 では socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE)、IPv6 では socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) で、このソケットを作成します。

利用可能な環境: Linux >= 2.6.20, FreeBSD >= 10.1

Added in version 3.9.
AF_HYPERV は、Hyper-V のホストとゲストが通信するための、Windows 限定のソケットベースのインターフェースです。アドレスファミリーは (vm_id, service_id) タプルで表し、vm_id と service_id は UUID 文字列です。

vm_id は仮想マシンの識別子です。対象が特定の仮想マシンでない場合は、あらかじめ定義された VMID 値のいずれかを使います。 socket で定義されている VMID 定数は次のとおりです。
- HV_GUID_ZERO
- HV_GUID_BROADCAST
- HV_GUID_WILDCARD - 自身にバインドし、すべてのパーティションからの接続を受け付けるために使います。
- HV_GUID_CHILDREN - 自身にバインドし、子パーティションからの接続を受け付けるために使います。
- HV_GUID_LOOPBACK - 自身を接続先として指定するために使います。
- HV_GUID_PARENT - バインド先として使うと、親パーティションからの接続を受け付けます。接続先アドレスとして使うと、親パーティションへ接続します。
service_id は登録されたサービスのサービス識別子です。

Added in version 3.12.

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

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

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

モジュールの内容¶

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

例外¶

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¶

TimeoutError の非推奨のエイリアスです。

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

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

バージョン 3.10 で変更: このクラスは TimeoutError のエイリアスになりました。

定数¶

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

Added in version 3.4.

socket.AF_UNIX¶
socket.AF_INET¶
socket.AF_INET6¶: これらの定数はアドレスファミリー (およびプロトコルファミリー) を表し、socket() の最初の引数に使います。 AF_UNIX 定数が定義されていない場合、このプロトコルはサポートされていません。システムによっては、ほかの定数も利用できます。

socket.AF_UNSPEC¶: AF_UNSPEC は、利用可能なアドレスファミリー (IPv4、IPv6、その他) を問わず getaddrinfo() がソケットアドレスを返すことを指定します。

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.

Added in version 3.2.

SO_*
socket.SOMAXCONN¶
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*: Unix のソケットや IP プロトコルのドキュメントで説明されている、この形式の定数の多くも socket モジュールで定義されています。通常、ソケットオブジェクトの setsockopt() メソッドと getsockopt() メソッドの引数に使います。ほとんどの場合、Unix のヘッダーファイルで定義されているシンボルだけが定義されますが、いくつかのシンボルにはデフォルト値が用意されています。

バージョン 3.6 で変更: SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION が追加されました。

バージョン 3.6.5 で変更: Windows プラットフォームで、利用可能な場合に TCP_FASTOPEN と TCP_KEEPCNT をサポートするようになりました。

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

Windows プラットフォームで、利用可能な場合に TCP_KEEPIDLE と TCP_KEEPINTVL をサポートするようになりました。

バージョン 3.10 で変更: IP_RECVTOS が追加されました。 TCP_KEEPALIVE が追加されました。 macOS では、Linux の TCP_KEEPIDLE と同じようにこの定数を使えます。

バージョン 3.11 で変更: TCP_CONNECTION_INFO が追加されました。 macOS では、Linux や BSD の TCP_INFO と同じようにこの定数を使えます。

バージョン 3.12 で変更: SO_RTABLE と SO_USER_COOKIE が追加されました。それぞれ OpenBSD と FreeBSD で、Linux の SO_MARK と同じように使えます。また、欠けていた Linux の TCP ソケットオプションが追加されました: TCP_MD5SIG、TCP_THIN_LINEAR_TIMEOUTS、TCP_THIN_DUPACK、TCP_REPAIR、TCP_REPAIR_QUEUE、TCP_QUEUE_SEQ、TCP_REPAIR_OPTIONS、TCP_TIMESTAMP、TCP_CC_INFO、TCP_SAVE_SYN、TCP_SAVED_SYN、TCP_REPAIR_WINDOW、TCP_FASTOPEN_CONNECT、TCP_ULP、TCP_MD5SIG_EXT、TCP_FASTOPEN_KEY、TCP_FASTOPEN_NO_COOKIE、TCP_ZEROCOPY_RECEIVE、TCP_INQ、TCP_TX_DELAY。 IP_PKTINFO、IP_UNBLOCK_SOURCE、IP_BLOCK_SOURCE、IP_ADD_SOURCE_MEMBERSHIP、IP_DROP_SOURCE_MEMBERSHIP が追加されました。

バージョン 3.13 で変更: SO_BINDTOIFINDEX が追加されました。 Linux では SO_BINDTODEVICE と同じように使えますが、ネットワークインターフェースの名前の代わりにインデックスを指定します。

バージョン 3.14 で変更: Linux で欠けていた IP_FREEBIND、IP_RECVERR、IPV6_RECVERR、IP_RECVTTL、IP_RECVORIGDSTADDR が追加されました。

バージョン 3.14 で変更: Windows プラットフォームで、利用可能な場合に TCP_QUICKACK をサポートするようになりました。

バージョン 3.15 で変更: IPV6_HDRINCL が追加されました。 Linux プラットフォームで、利用可能な場合に SO_PASSRIGHTS をサポートするようになりました。

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

利用可能な環境: Linux >= 2.6.25, NetBSD >= 8.

Added in version 3.3.

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

バージョン 3.14 で変更: Linux で欠けていた CAN_RAW_ERR_FILTER が復元されました。

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

利用可能な環境: Linux >= 2.6.25.

注釈

CAN_BCM_CAN_FD_FRAME フラグは Linux 4.8 以降でのみ利用できます。

Added in version 3.4.

socket.CAN_RAW_FD_FRAMES¶

CAN_RAW ソケットで CAN FD をサポートします。これはデフォルトで無効になっています。これにより、アプリケーションが CAN フレームと CAN FD フレームを送信できるようになります。ただし、ソケットからの読み出し時に、CAN と CAN FD の両方のフレームを受け入れなければなりません。

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

利用可能な環境: Linux >= 3.6.

Added in version 3.5.

socket.CAN_RAW_JOIN_FILTERS¶

適用される CAN フィルターを結合し、指定されたすべての CAN フィルターに一致する CAN フレームだけをユーザー空間に渡します。

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

利用可能な環境: Linux >= 4.1.

Added in version 3.9.

socket.CAN_ISOTP¶: CAN プロトコルファミリーの CAN_ISOTP は ISO-TP (ISO 15765-2) プロトコルです。 ISO-TP の定数は Linux のドキュメントで説明されています。

利用可能な環境: Linux >= 2.6.25.

Added in version 3.7.

socket.CAN_J1939¶: CAN プロトコルファミリーの CAN_J1939 は SAE J1939 プロトコルです。 J1939 の定数は Linux のドキュメントで説明されています。

利用可能な環境: Linux >= 5.4.

Added in version 3.9.

socket.AF_DIVERT¶
socket.PF_DIVERT¶: FreeBSD の divert(4) マニュアルページで説明されているこの 2 つの定数も、socket モジュールで定義されています。

利用可能な環境: FreeBSD >= 14.0.

Added in version 3.12.

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

利用可能な環境: Linux >= 2.2.

socket.ETH_P_ALL¶

AF_PACKET ファミリーの socket コンストラクターの proto に ETH_P_ALL を使うと、プロトコルを問わずすべてのパケットを取得できます。

詳しくは packet(7) マニュアルページを参照してください。

利用可能な環境: Linux.

Added in version 3.12.

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

利用可能な環境: Linux >= 2.6.30.

Added in version 3.3.

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

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

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

socket.AF_ALG¶
socket.SOL_ALG¶
ALG_*: Linux カーネル暗号用の定数です。

利用可能な環境: Linux >= 2.6.38.

Added in version 3.6.

socket.AF_VSOCK¶
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID¶
VMADDR*
SO_VM*: Linux のホストとゲスト間の通信用の定数です。

利用可能な環境: Linux >= 4.8.

Added in version 3.7.

socket.AF_LINK¶: 利用可能な環境: BSD, macOS.

Added in version 3.4.

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

socket.AF_BLUETOOTH¶
socket.BTPROTO_L2CAP¶
socket.BTPROTO_RFCOMM¶
socket.BTPROTO_HCI¶
socket.BTPROTO_SCO¶: Bluetooth アドレスに使う整数定数です。

socket.BDADDR_ANY¶
socket.BDADDR_LOCAL¶: これらは、特別な意味を持つ Bluetooth アドレスを含む文字列定数です。例えば、BDADDR_ANY を使用すると、 BTPROTO_RFCOMM で束縛ソケットを指定する際に、任意のアドレスを指し示すことができます。

socket.BDADDR_BREDR¶
socket.BDADDR_LE_PUBLIC¶
socket.BDADDR_LE_RANDOM¶: これらの定数は、BTPROTO_L2CAP ソケットのバインドや接続に使う Bluetooth アドレスの種類を表します。

利用可能な環境: Linux, FreeBSD

Added in version 3.14.

socket.SOL_RFCOMM¶

socket.SOL_L2CAP¶

socket.SOL_HCI¶

socket.SOL_SCO¶

socket.SOL_BLUETOOTH¶

Bluetooth ソケットオブジェクトの setsockopt() メソッドと getsockopt() メソッドの level 引数に使います。

SOL_BLUETOOTH は Linux でのみ利用できます。ほかの定数は、対応するプロトコルがサポートされている場合に利用できます。

SO_L2CAP_*

socket.L2CAP_LM¶

L2CAP_LM_*

SO_RFCOMM_*

RFCOMM_LM_*

SO_SCO_*

SO_BTH_*

BT_*

Bluetooth ソケットオブジェクトの setsockopt() メソッドと getsockopt() メソッドで、オプション名や値を指定する引数に使います。

BT_* と L2CAP_LM は Linux でのみ利用できます。 SO_BTH_* は Windows でのみ利用できます。ほかの定数は Linux や各種 BSD プラットフォームで利用できる場合があります。

Added in version 3.14.

socket.HCI_FILTER¶
socket.HCI_TIME_STAMP¶
socket.HCI_DATA_DIR¶
socket.SO_HCI_EVT_FILTER¶
socket.SO_HCI_PKT_FILTER¶: BTPROTO_HCI に使うオプション名です。利用できるオプションとその値の形式はプラットフォームによって異なります。

バージョン 3.14 で変更: NetBSD と DragonFly BSD に SO_HCI_EVT_FILTER と SO_HCI_PKT_FILTER が追加されました。 FreeBSD、NetBSD、DragonFly BSD に HCI_DATA_DIR が追加されました。

socket.HCI_DEV_NONE¶: 単一の Bluetooth アダプターに限定されない HCI ソケットを作成するための device_id の値です。

利用可能な環境: Linux

Added in version 3.14.

socket.HCI_CHANNEL_RAW¶
socket.HCI_CHANNEL_USER¶
socket.HCI_CHANNEL_MONITOR¶
socket.HCI_CHANNEL_CONTROL¶
socket.HCI_CHANNEL_LOGGING¶: BTPROTO_HCI アドレスの channel フィールドに指定できる値です。

利用可能な環境: Linux

Added in version 3.14.

socket.AF_QIPCRTR¶: サービスを提供するリモートプロセッサーとの通信に使う、Qualcomm の IPC ルータープロトコルの定数です。

利用可能な環境: Linux >= 4.7.

socket.SCM_CREDS2¶
socket.LOCAL_CREDS¶
socket.LOCAL_CREDS_PERSISTENT¶: LOCAL_CREDS と LOCAL_CREDS_PERSISTENT は SOCK_DGRAM ソケットと SOCK_STREAM ソケットで使え、Linux や DragonFlyBSD の SO_PASSCRED に相当します。 LOCAL_CREDS は最初の読み取り時に認証情報を送信し、LOCAL_CREDS_PERSISTENT は読み取りのたびに送信します。後者ではメッセージの種類に SCM_CREDS2 を使う必要があります。

Added in version 3.11.

利用可能な環境: FreeBSD.

socket.SO_INCOMING_CPU¶: CPU の局所性を最適化するための定数で、SO_REUSEPORT と組み合わせて使います。

Added in version 3.11.

利用可能な環境: Linux >= 3.9

socket.SO_REUSEPORT_LB¶: 同じアドレスとポートへの複数のバインドと負荷分散を有効にする定数です。

Added in version 3.14.

利用可能な環境: FreeBSD >= 12.0

socket.AF_HYPERV¶
socket.HV_PROTOCOL_RAW¶
socket.HVSOCKET_CONNECT_TIMEOUT¶
socket.HVSOCKET_CONNECT_TIMEOUT_MAX¶
socket.HVSOCKET_CONNECTED_SUSPEND¶
socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU¶
socket.HV_GUID_ZERO¶
socket.HV_GUID_WILDCARD¶
socket.HV_GUID_BROADCAST¶
socket.HV_GUID_CHILDREN¶
socket.HV_GUID_LOOPBACK¶
socket.HV_GUID_PARENT¶: ホストとゲスト間の通信に使う Windows Hyper-V ソケットの定数です。

利用可能な環境: Windows.

Added in version 3.12.

socket.ETHERTYPE_ARP¶
socket.ETHERTYPE_IP¶
socket.ETHERTYPE_IPV6¶
socket.ETHERTYPE_VLAN¶: IEEE 802.3 プロトコル番号の定数です。

利用可能な環境: Linux, FreeBSD, macOS.

Added in version 3.12.

socket.SHUT_RD¶
socket.SHUT_WR¶
socket.SHUT_RDWR¶: これらの定数はソケットオブジェクトの shutdown() メソッドで使います。

利用可能な環境: not WASI.

関数¶

ソケットの作成¶

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

socket クラスのコンストラクターは、新しいソケットを直接作成します。引数と詳しい説明は socket オブジェクトを参照してください。

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

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

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

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

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

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

socket.create_connection(address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)¶

インターネット 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のデフォルトの動作になります。

接続を確立できない場合は例外を送出します。デフォルトでは、リスト内の最後のアドレスで発生した例外を送出します。 all_errors が True の場合は、すべての接続試行のエラーを含む ExceptionGroup を送出します。

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

バージョン 3.11 で変更: all_errors が追加されました

socket.create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)¶

address ((host, port) という 2 要素のタプル) にバインドされた TCP ソケットを作成し、そのソケットオブジェクトを返す便利な関数です。

family は AF_INET または AF_INET6 でなければなりません。 backlog は socket.listen() に渡すキューのサイズです。指定しない場合は、適切なデフォルト値が選ばれます。 reuse_port はソケットオプション SO_REUSEPORT を設定するかどうかを指定します。

dualstack_ipv6 が真の場合、family が AF_INET6 でプラットフォームがこの機能をサポートしていれば、ソケットは IPv4 と IPv6 の両方の接続を受け入れられます。そうでなければ ValueError を送出します。ほとんどの POSIX プラットフォームと Windows はこの機能をサポートしているはずです。この機能が有効な場合、IPv4 接続に対して socket.getpeername() が返すアドレスは、IPv4 射影 IPv6 アドレスとして表された IPv6 アドレスになります。 dualstack_ipv6 が偽の場合、この機能をデフォルトで有効にするプラットフォーム (Linux など) でも明示的に無効にします。この引数は has_dualstack_ipv6() と組み合わせて使えます:

import socket

addr = ("", 8080)  # すべてのインターフェース、ポート 8080
if socket.has_dualstack_ipv6():
    s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
    s = socket.create_server(addr)

注釈

POSIX プラットフォームでは、同じ address にバインドされて TIME_WAIT 状態で残っている以前のソケットをすぐに再利用できるよう、ソケットオプション SO_REUSEADDR を設定します。

Added in version 3.8.

socket.has_dualstack_ipv6()¶: プラットフォームが IPv4 と IPv6 の両方の接続を扱える TCP ソケットの作成をサポートしていれば、True を返します。

Added in version 3.8.

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

ファイル記述子 fd (ファイルオブジェクトの fileno() メソッドが返す整数) を複製し、その結果からソケットオブジェクトを作成します。アドレスファミリー、ソケットの種類、プロトコル番号は socket() 関数と同じです。ファイル記述子はソケットを指す必要がありますが、これは検査されません。ファイル記述子が無効な場合、その後のオブジェクトへの操作が失敗することがあります。この関数が必要になることはまれですが、プログラムに標準入力や標準出力として渡されたソケット (Unix の inet デーモンから起動されたサーバなど) のソケットオプションを取得・設定するために使えます。ソケットはブロッキングモードであると仮定されます。

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

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

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

利用可能な環境: Windows.

Added in version 3.3.

その他の関数¶

socket モジュールは、ネットワーク関連のさまざまなサービスも提供します:

socket.close(fd)¶: ソケットのファイル記述子を閉じます。 os.close() のソケット版です。一部のプラットフォーム (特に Windows) では、os.close() はソケットのファイル記述子には使えません。

Added in version 3.7.

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

この関数は、基盤となるシステムの C 関数 getaddrinfo をラップします。

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

family、type、proto 引数を指定すると、オプションを設定して、返されるアドレスのリストを制限できます。結果を制限しない場合は、それぞれのデフォルト値 (AF_UNSPEC、0、0) を渡してください。詳しくは後述の注記を参照してください。

flags 引数には AI_* 定数を 1 つ、または複数組み合わせて指定でき、結果の計算方法と返し方に影響します。例えば AI_NUMERICHOST はドメイン名の解決を無効にし、host がドメイン名の場合にエラーを送出します。

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

(family, type, proto, canonname, sockaddr)

このタプルの family、type、proto はすべて整数で、socket() 関数に渡すための値です。 flags 引数に AI_CANONNAME が含まれる場合、canonname は host の正規名を表す文字列になります。そうでなければ canonname は空になります。 sockaddr はソケットアドレスを表すタプルで、返された family と Python のコンパイル時のフラグによって形式が決まります。 socket.connect() メソッドに渡すための値です。

sockaddr は次のいずれかです:

AF_INET の場合は、2 要素のタプル (address, port)
AF_INET6 で Python が --enable-ipv6 (デフォルト) でコンパイルされた場合は、4 要素のタプル (address, port, flowinfo, scope_id)
AF_INET6 で Python が --disable-ipv6 でコンパイルされた場合は、生のデータを含む 2 要素のタプル

注釈

getaddrinfo() の結果を使ってソケットを作成する場合 (例えば canonname の取得だけが目的ではない場合) は、アプリケーションで扱える type (SOCK_STREAM や SOCK_DGRAM など) や proto (IPPROTO_TCP や IPPROTO_UDP など) で結果を制限することを検討してください。

family、type、proto、flags がデフォルト値の場合の動作は、システムによって異なります。

多くのシステム (例えば、ほとんどの Linux 構成) は、一致するすべてのアドレスをソートしたリストを返します。通常、接続が成功するまでこの順序でアドレスへの接続を試みてください (Happy Eyeballs アルゴリズムなどを使い、並行して試すこともできます)。このようなシステムでは、type や proto を制限すると、失敗する接続や利用できない接続を試すことを避けやすくなります。

一方、アドレスを 1 つしか返さないシステムもあります (例えば、Solaris や AIX の構成で報告されています)。このようなシステムでは、type や proto を制限すると、利用可能なアドレスを得やすくなります。

引数 host, port, family, type, protocol 付きで監査イベント socket.getaddrinfo を送出します。

次の例では、example.org の 80 番ポートに TCP 接続するとした場合のアドレス情報を取得します (IPv6 が有効でなければ、システムによって結果が異なることがあります)。

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

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

バージョン 3.7 で変更: IPv6 マルチキャストアドレスでは、アドレスを表す文字列に %scope_id 部分が含まれなくなりました。

socket.getfqdn([name])¶: name の完全修飾ドメイン名を返します。 name が省略された場合や空の場合は、ローカルホストと解釈します。完全修飾名を探すため、gethostbyaddr() が返すホスト名を調べ、次にホストの別名があればそれらを調べます。ピリオドを含む最初の名前が選ばれます。完全修飾ドメイン名が得られず、name が指定されていれば、name をそのまま返します。 name が空または '0.0.0.0' の場合は、gethostname() が返すホスト名を返します。

socket.gethostbyname(hostname)¶

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

引数 hostname を指定して監査イベント socket.gethostbyname を送出します。

利用可能な環境: not WASI.

socket.gethostbyname_ex(hostname)¶

ホスト名を IPv4 アドレス形式に変換する拡張インターフェースです。 3 要素のタプル (hostname, aliaslist, ipaddrlist) を返します。 hostname はそのホストの主なホスト名、aliaslist は同じアドレスを指す別のホスト名のリスト (空の場合もあります)、 ipaddrlist は同じホストの同じインターフェースの IPv4 アドレスのリストです (多くの場合はアドレス 1 つですが、常にそうとは限りません)。 gethostbyname_ex() は IPv6 の名前解決をサポートしていません。 IPv4/v6 デュアルスタックをサポートするには、代わりに getaddrinfo() を使ってください。

引数 hostname を指定して監査イベント socket.gethostbyname を送出します。

利用可能な環境: not WASI.

socket.gethostname()¶

Pythonインタープリタを現在実行しているマシンのホスト名を含む文字列を返します。

引数無しで監査イベント socket.gethostname を送出します。

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

利用可能な環境: not WASI.

socket.gethostbyaddr(ip_address)¶

3 要素のタプル (hostname, aliaslist, ipaddrlist) を返します。 hostname は指定された ip_address に対応する主なホスト名、aliaslist は同じアドレスを指す別のホスト名のリスト (空の場合もあります)、 ipaddrlist は同じホストの同じインターフェースの IPv4/v6 アドレスのリストです (ほとんどの場合、アドレスは 1 つだけです)。完全修飾ドメイン名を得るには getfqdn() 関数を使ってください。 gethostbyaddr() は IPv4 と IPv6 の両方をサポートしています。

引数 ip_address を指定して監査イベント socket.gethostbyaddr を送出します。

利用可能な環境: not WASI.

socket.getnameinfo(sockaddr, flags)¶

ソケットアドレス sockaddr を 2 要素のタプル (host, port) に変換します。 flags の設定に応じて、結果の host には完全修飾ドメイン名または数値表記のアドレスが入ります。同様に、port には文字列のポート名または数値のポート番号が入ります。

IPv6 アドレスで、sockaddr に意味のある scope_id が含まれている場合は、ホスト部分に %scope_id が追加されます。通常、マルチキャストアドレスの場合にこうなります。

flags について詳しくは getnameinfo(3) を参照してください。

引数 sockaddr を指定して監査イベント socket.getnameinfo を送出します。

利用可能な環境: not WASI.

socket.getprotobyname(protocolname)¶: インターネットプロトコル名 ('icmp' など) を、socket() 関数の省略可能な 3 番目の引数に渡せる定数に変換します。通常、これは "raw" モード (SOCK_RAW) で開くソケットでのみ必要です。通常のソケットモードでは、プロトコルを省略するかゼロを指定すると、適切なプロトコルが自動的に選ばれます。

利用可能な環境: not WASI.

socket.getservbyname(servicename[, protocolname])¶

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

引数 servicename, protocolname を指定して監査イベント socket.getservbyname を送出します。

利用可能な環境: not WASI.

socket.getservbyport(port[, protocolname])¶

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

引数 port, protocolname を指定して監査イベント socket.getservbyport を送出します。

利用可能な環境: not WASI.

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

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

バージョン 3.10 で変更: x が 16 ビット符号なし整数に収まらない場合は、OverflowError を送出します。

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

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

バージョン 3.10 で変更: x が 16 ビット符号なし整数に収まらない場合は、OverflowError を送出します。

socket.inet_aton(ip_string)¶

ドット記法によるIPv4アドレス('123.45.67.89' など)を32ビットにパックしたバイナリ形式に変換し、長さ4のバイト列オブジェクトとして返します。この関数が返す値は、標準Cライブラリの 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' など) に変換します。この関数は、in_addr 型、つまりこの関数が引数として受け取る 32 ビットにパックされたバイナリデータに対する C の型、を使用する標準 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() は、 in_addr 型 (inet_aton() と同様)や 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() と同様に)、 in_addr 型や 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 のデータを伴う制御メッセージ (補助データ) 1 件について、末尾のパディングを除いた全体の長さを返します。この値は、recvmsg() で制御メッセージを 1 件受信するためのバッファサイズとして使える場合が多くあります。ただし RFC 3542 では、移植可能なアプリケーションは CMSG_SPACE() を使い、バッファの最後のメッセージであってもパディング用の領域を含める必要があると定めています。 length が許容範囲外の場合は OverflowError を送出します。

利用可能な環境: Unix, not WASI.

ほとんどの Unix プラットフォーム。

Added in version 3.3.

socket.CMSG_SPACE(length)¶

長さ length のデータを伴う制御メッセージ (補助データ) 1 件を recvmsg() で受信するために必要な、末尾のパディングを含むバッファサイズを返します。複数件を受信するには、それぞれのデータ長に対する CMSG_SPACE() の戻り値を合計したバッファサイズが必要です。 length が許容範囲外の場合は OverflowError を送出します。

この関数を提供せずに制御メッセージをサポートするシステムもあります。また、パディング領域に追加のデータが収まることがあるため、この関数の結果でバッファサイズを設定しても、受信できる制御メッセージの量を厳密に制限できるとは限りません。

利用可能な環境: Unix, not WASI.

ほとんどの Unix プラットフォーム。

Added in version 3.3.

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

socket.setdefaulttimeout(timeout)¶: 新しいソケットオブジェクトのデフォルトのタイムアウトを秒数 (実数) で設定します。 socket モジュールの初回のインポート時には、デフォルトは None です。指定できる値とそれぞれの意味は settimeout() を参照してください。

バージョン 3.15 で変更: 整数や浮動小数点数に限らず、任意の実数を受け付けるようになりました。

socket.sethostname(name)¶

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

引数 name を指定して監査イベント socket.sethostname を送出します。

利用可能な環境: Unix, not Android.

Added in version 3.3.

socket.if_nameindex()¶

ネットワークインターフェース情報を表すタプル (インデックスの整数、名前の文字列) のリストを返します。システムコールが失敗した場合、 OSError 例外を送出します。

利用可能な環境: Unix, Windows, not WASI.

Added in version 3.3.

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

注釈

Windows のネットワークインターフェースには、文脈によって異なる名前があります (以下の名前はすべて例です):

UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}
名前: ethernet_32770
表示名: vEthernet (nat)
説明: Hyper-V Virtual Ethernet Adapter

この関数は上記の 2 番目の形式の名前を返します。この例では ethernet_32770 です。

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

利用可能な環境: Unix, Windows, not WASI.

Added in version 3.3.

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

参考

「インターフェース名」は if_nameindex() で説明している名前です。

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

利用可能な環境: Unix, Windows, not WASI.

Added in version 3.3.

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

参考

「インターフェース名」は if_nameindex() で説明している名前です。

socket.send_fds(sock, buffers, fds[, flags[, address]])¶: AF_UNIX ソケット sock を通じて、ファイル記述子のリスト fds を送信します。 fds 引数はファイル記述子のシーケンスです。引数の説明は sendmsg() を参照してください。

利用可能な環境: Unix, not WASI.

sendmsg() と SCM_RIGHTS の仕組みをサポートする Unix プラットフォーム。

Added in version 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])¶: AF_UNIX ソケット sock から最大 maxfds 個のファイル記述子を受信します。 (msg, list(fds), flags, addr) を返します。引数の説明は recvmsg() を参照してください。

利用可能な環境: Unix, not WASI.

recvmsg() と SCM_RIGHTS の仕組みをサポートする Unix プラットフォーム。

Added in version 3.9.

注釈

Any truncated integers at the end of the list of file descriptors.

socket オブジェクト¶

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

アドレスファミリー、ソケットタイプ、プロトコル番号を指定してソケットを作成します。アドレスファミリーには AF_INET (デフォルト値), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET, AF_RDS を指定することができます。ソケットタイプには SOCK_STREAM (デフォルト値), SOCK_DGRAM, SOCK_RAW または他の SOCK_ 定数の何れかを指定します。プロトコル番号は通常省略するか、または0を指定しますが、アドレスファミリーに AF_CAN を指定した場合は、プロトコル番号には CAN_RAW, CAN_BCM, CAN_ISOTP, CAN_J1939 のいずれかを指定すべきです。

fileno を指定すると、family、type、proto の値を指定されたファイル記述子から自動検出します。 family、type、proto 引数を明示的に指定して呼び出すと、自動検出された値を上書きできます。これは、例えば socket.getpeername() の戻り値を Python でどう表すかにだけ影響し、実際の OS のリソースには影響しません。 socket.fromfd() と異なり、fileno を指定した場合はソケットを複製せず、同じソケットを使います。これは、切り離したソケットを close() で閉じる場合などに役立ちます。

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

引数 self, family, type, protocol 付きで監査イベント socket.__new__ を送出します。

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

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

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

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

バージョン 3.7 で変更: type に SOCK_NONBLOCK や SOCK_CLOEXEC のビットフラグを指定しても、それらはクリアされ、socket.type には反映されません。ただし、基盤となるシステムの socket() 呼び出しには渡されます。したがって、

sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

は、SOCK_NONBLOCK をサポートする OS では非ブロッキングソケットを作成しますが、sock.type は socket.SOCK_STREAM に設定されます。

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

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

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

バージョン 3.2 で変更: コンテキストマネージャープロトコルをサポートするようになりました。コンテキストマネージャーを終了することは、close() を呼び出すことに相当します。

accept()¶

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

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

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

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

bind(address)¶

ソケットを address にバインドします。ソケットはまだバインドされていない必要があります。 address の形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。

引数 self, address を指定して監査イベント socket.bind を送出します。

利用可能な環境: not WASI.

close()¶

ソケットを閉じた状態にします。 makefile() で作成されたファイルオブジェクトがすべて閉じられると、基盤となるシステムリソース (ファイル記述子など) も閉じられます。それ以降、ソケットオブジェクトへの操作はすべて失敗します。相手側は、キューに残ったデータがフラッシュされた後は、それ以上データを受信しません。

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

バージョン 3.6 で変更: 基盤となる close() 呼び出しでエラーが発生した場合、OSError を送出するようになりました。

注釈

close() は接続に関連するリソースを解放しますが、接続を直ちに閉じるとは限りません。接続を速やかに閉じたい場合は、close() の前に shutdown() を呼び出してください。

connect(address)¶

address のリモートソケットに接続します。 address の形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。

接続がシグナルによって中断されても、シグナルハンドラーが例外を送出せず、ソケットがブロッキングモードまたはタイムアウト付きであれば、このメソッドは接続が完了するまで待機するか、タイムアウト時に TimeoutError を送出します。非ブロッキングソケットで接続がシグナルによって中断された場合は、InterruptedError (またはシグナルハンドラーが送出した例外) を送出します。

引数 self, address を指定して監査イベント socket.connect を送出します。

バージョン 3.5 で変更: このメソッドは、接続が信号によって中断され、信号ハンドラが例外を送出せず、ソケットがブロックであるかタイムアウトが設定されている場合、InterruptedError 例外を送出する代わりに、接続を完了するまで待機するようになりました (論拠については PEP 475 を参照してください)。

利用可能な環境: not WASI.

connect_ex(address)¶

connect(address) と同様ですが、C レベルの connect() 呼び出しが返すエラーに対して、例外を送出する代わりにエラーを示す値を返します (「ホストが見つからない」など、ほかの問題では例外が送出されることがあります)。この値は、操作に成功した場合は 0、そうでなければ errno 変数の値です。例えば、非同期接続のサポートに役立ちます。

引数 self, address を指定して監査イベント socket.connect を送出します。

利用可能な環境: not WASI.

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

Added in version 3.2.

dup()¶

ソケットを複製します。

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

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

利用可能な環境: not WASI.

fileno()¶

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

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

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

Added in version 3.4.

getpeername()¶: ソケットの接続先のリモートアドレスを返します。例えば、リモートの IPv4/v6 ソケットのポート番号を調べる際に役立ちます。返されるアドレスの形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。一部のシステムでは、この関数はサポートされていません。

getsockname()¶: ソケット自身のアドレスを返します。例えば、IPv4/v6 ソケットのポート番号を調べる際に役立ちます。返されるアドレスの形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。

getsockopt(level, optname[, buflen])¶: 指定されたソケットオプションの値を返します (Unix のマニュアルページ getsockopt(2) を参照)。必要なシンボル定数 (SO_* など) はこのモジュールで定義されています。 buflen を省略すると、整数のオプションと仮定して整数値を返します。 buflen を指定すると、オプションの値を受け取るバッファの最大長となり、そのバッファを bytes オブジェクトとして返します。バッファの内容のデコードは呼び出し側で行う必要があります (バイト列にエンコードされた C の構造体をデコードする方法は、オプションの組み込みモジュール struct を参照してください)。

利用可能な環境: not WASI.

getblocking()¶

ソケットがブロッキングモードなら True、非ブロッキングモードなら False を返します。

これは socket.gettimeout() != 0 の検査と同等です。

Added in version 3.7.

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

ioctl(control, option)¶

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

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

現在、以下のコントロールコードのみがサポートされています。 SIO_RCVALL, SIO_KEEPALIVE_VALS, SIO_LOOPBACK_FAST_PATH。

利用可能な環境: Windows

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

listen([backlog])¶: サーバーを有効にして、接続を受け付けるようにします。backlog が指定されている場合、少なくとも 0 以上でなければなりません (それより低い場合、0 に設定されます)。システムが新しい接続を拒否するまでに許可する未受付の接続の数を指定します。指定しない場合、デフォルトの妥当な値が選択されます。

利用可能な環境: not WASI.

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

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

ソケットに関連付けられたファイルオブジェクトを返します。返される具体的な型は makefile() に渡す引数によって異なります。引数は組み込み関数 open() と同じように解釈されますが、サポートされる mode の値は 'r' (デフォルト)、'w'、'b'、またはその組み合わせだけです。

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

makefile() が返すファイルオブジェクトを閉じても、ほかのすべてのファイルオブジェクトが閉じられ、かつソケットオブジェクトの close() が呼び出されていなければ、元のソケットは閉じられません。

注釈

Windows では subprocess.Popen() の stream 引数などファイルディスクリプタつき file オブジェクトが期待されている場所では、 makefile() によって作成される file-like オブジェクトは使用できません。

recv(bufsize[, flags])¶: Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received at once is specified by bufsize. A returned empty bytes object indicates that the client has disconnected. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero.

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

recvfrom(bufsize[, flags])¶: ソケットからデータを受信します。戻り値は (bytes, address) のペアです。 bytes は受信したデータを表す bytes オブジェクトで、address はデータを送信したソケットのアドレスです。省略可能な引数 flags の意味は、Unix のマニュアルページ recv(2) を参照してください。デフォルト値はゼロです。 address の形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。

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

バージョン 3.7 で変更: IPv6 マルチキャストアドレスでは、address の最初の要素に %scope_id 部分が含まれなくなりました。完全な IPv6 アドレスを得るには getnameinfo() を使ってください。

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

ソケットから通常のデータ (最大 bufsize バイト) と補助的なデータを受信します。ancbufsize 引数により、補助的なデータの受信に使用される内部バッファのバイト数として、サイズが設定されます。このデフォルトは 0 で、補助的なデータを受信しないことを意味します。CMSG_SPACE() または CMSG_LEN() を使用して、補助的なデータの適切なサイズを計算することができ、バッファ内に収まらないアイテムは、短縮されるか破棄されます。flags 引数はデフォルトでは 0 で、recv() での意味と同じ意味を持ちます。

戻り値は 4 要素のタプル (data, ancdata, msg_flags, address) です。data アイテムは、受信した非付属的データを保持する bytes オブジェクトです。ancdata アイテムは、ゼロ以上のタプル (cmsg_level, cmsg_type, cmsg_data) からなるリストで、受信する付属的なデータ (制御メッセージ) を表します。cmsg_level と cmsg_type はそれぞれ、プロトコルレベルとプロトコル固有のタイプを指定する整数で、cmsg_data は関連するデータを保持する bytes オブジェクトです。msg_flags アイテムは、受信したメッセージの条件を示す様々なフラグのビット OR です。詳細は、システムのドキュメントを参照してください。受信ソケットが接続されていない場合、address は、送信ソケットが利用できる場合にはそのアドレスで、利用できない場合、その値は未指定になります。

一部のシステムでは、sendmsg() と recvmsg() を使用して、プロセス間で AF_UNIX ソケットを経由してファイル記述子を渡すことができます。この機能を使用する場合 (しばしば SOCK_STREAM ソケットに限定されます)、recvmsg() は、付属的なデータ中に、(socket.SOL_SOCKET, socket.SCM_RIGHTS, fds) という形式のアイテムを返します。ここで、fds は、新しいファイル記述子をネイティブ C の int 型のバイナリ配列として表す bytes オブジェクトです。システムコールが返った後 recvmsg() が例外を送出する場合、まずこのメカニズムを経由して受信したファイル記述子を全て閉じようと試みます。

一部のシステムでは、部分的に受信した付属的なデータアイテムの短縮された長さが示されません。アイテムがバッファの末尾を超えているようである場合、recvmsg() は RuntimeWarning を送出し、関連するデータの開始位置より前で途切れていない場合、バッファ内の付属的なデータの一部を返します。

SCM_RIGHTS の仕組みをサポートするシステムでは、以下の関数で最大 maxfds 個のファイル記述子を受信し、メッセージデータと記述子のリストを返せます (無関係な制御メッセージを受信するなど、想定外の状況は無視します)。 sendmsg() も参照してください。

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # int の配列
    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:
            # 末尾の不完全な整数を無視してデータを追加する。
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

利用可能な環境: Unix.

ほとんどの Unix プラットフォーム。

Added in version 3.3.

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

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

recvmsg() と同様に動作してソケットから通常のデータと付属的なデータを受信しますが、非付属的データは新しいバイトオブジェクトとして返すのではなく、指定された一連のバッファに分散して書き込みます。 buffers 引数は書き込み可能なバッファをエクスポートするオブジェクトのイテラブルでなければなりません (例: bytearray オブジェクト)。これらは、全てに書き込まれるか、残りバッファがなくなるまで、非付属的データの連続チャンクで埋められます。オペレーティングシステムによって、使用できるバッファの数が制限 (sysconf() 値 SC_IOV_MAX) されている場合があります。 ancbufsize 引数と flags 引数は、recvmsg() での意味と同じ意味を持ちます。

戻り値は 4 要素のタプル (nbytes, ancdata, msg_flags, address) です。ここで、nbytes はバッファに書き込まれた非付属的データの総バイト数で、ancdata、msg_flags、address は 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.

ほとんどの Unix プラットフォーム。

Added in version 3.3.

recvfrom_into(buffer[, nbytes[, flags]])¶: ソケットからデータを受信し、新しいバイト列を作る代わりに buffer に書き込みます。戻り値は (nbytes, address) のペアです。 nbytes は受信したバイト数で、address はデータを送信したソケットのアドレスです。省略可能な引数 flags の意味は、Unix のマニュアルページ recv(2) を参照してください。デフォルト値はゼロです。 address の形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。

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

send(bytes[, flags])¶: ソケットにデータを送信します。ソケットはリモートソケットに接続されている必要があります。省略可能な flags 引数の意味は recv() と同じです。送信したバイト数を返します。すべてのデータを送信できたかどうかは、アプリケーション側で確認する必要があります。データの一部だけを送信した場合は、残りのデータの送信を試みる必要があります。この点について詳しくはソケットプログラミング HOWTO を参照してください。

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

sendall(bytes[, flags])¶: ソケットにデータを送信します。ソケットはリモートソケットに接続されている必要があります。省略可能な flags 引数の意味は recv() と同じです。 send() と異なり、このメソッドはすべてのデータを送信するかエラーが発生するまで、bytes のデータを送信し続けます。成功すると None を返します。エラー時は例外を送出しますが、データをどこまで正常に送信できたか、または全く送信できなかったかを知る方法はありません。

バージョン 3.5 で変更: ソケットのタイムアウトは、データが正常に送信される度にリセットされなくなりました。ソケットのタイムアウトは、すべてのデータを送る最大の合計時間となります。

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

sendto(bytes, address)¶

sendto(bytes, flags, address)

ソケットにデータを送信します。送信先のソケットは address で指定するため、ソケットはリモートソケットに接続しておかないでください。省略可能な flags 引数の意味は recv() と同じです。送信したバイト数を返します。 address の形式はアドレスファミリーによって異なります。ソケットファミリーを参照してください。

引数 self, address を指定して監査イベント socket.sendto を送出します。

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

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

非付属的なデータを一連のバッファから集め、単一のメッセージにまとめることで、通常のデータと付属的なデータをソケットに送信します。buffers 引数は、非付属的なデータを bytes-like objects (例: bytes オブジェクト) のイテラブルとして指定します。オペレーティングシステムによって、使用できるバッファの数が制限 (sysconf() 値 SC_IOV_MAX) されている場合があります。ancdata 引数は付属的なデータ (制御メッセージ) をゼロ以上のタプル (cmsg_level, cmsg_type, cmsg_data) のイテラブルとして指定します。ここで、cmsg_level と cmsg_type はそれぞれプロトコルレベルとプロトコル固有のタイプを指定する整数で、cmsg_data は関連データを保持するバイトライクオブジェクトです。一部のシステム (特に CMSG_SPACE() を持たないシステム) では、一度の呼び出しで一つの制御メッセージの送信しかサポートされていない場合があります。flags 引数のデフォルトは 0 であり、send() での意味と同じ意味を持ちます。None 以外の address が渡された場合、メッセージの目的地のアドレスを設定します。戻り値は、送信された非付属的データのバイト数です。

SCM_RIGHTS の仕組みをサポートするシステムでは、以下の関数で AF_UNIX ソケットを通じてファイル記述子のリスト fds を送信できます。 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, not WASI.

ほとんどの Unix プラットフォーム。

引数 self, address を指定して監査イベント socket.sendmsg を送出します。

Added in version 3.3.

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

sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])¶: sendmsg() の AF_ALG ソケット用に特化したバージョンです。AF_ALG ソケットの、モード、IV、AEAD に関連づけられたデータ長、フラグを設定します。

利用可能な環境: Linux >= 2.6.38.

Added in version 3.6.

sendfile(file, offset=0, count=None)¶: 高性能な os.sendfile を使ってファイルを EOF まで送信し、送信した総バイト数を返します。 file はバイナリモードで開いた通常ファイルのオブジェクトでなければなりません。 os.sendfile が利用できない場合 (Windows など) や、file が通常ファイルでない場合は、代わりに send() を使います。 offset はファイルの読み取り開始位置を指定します。 count を指定すると、EOF まで送信する代わりに、指定されたバイト数を送信します。正常に戻る場合もエラーが起きた場合もファイル位置は更新されます。エラー時には file.tell() で送信したバイト数を調べられます。ソケットは SOCK_STREAM 型でなければなりません。非ブロッキングソケットはサポートされていません。

Added in version 3.5.

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

Added in version 3.4.

setblocking(flag)¶

ソケットをブロッキングモード、または非ブロッキングモードに設定します。flag が False の場合にはソケットは非ブロッキングモードになり、True の場合にはブロッキングモードになります。

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

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

バージョン 3.7 で変更: socket.type に SOCK_NONBLOCK フラグを適用しなくなりました。

settimeout(value)¶

ブロックするソケット操作にタイムアウトを設定します。 value 引数には、秒数を表す非負の実数または None を指定できます。ゼロ以外の値を指定すると、それ以降のソケット操作は、完了する前に value 秒が経過した場合に timeout 例外を送出します。ゼロを指定すると、ソケットは非ブロッキングモードになります。 None を指定すると、ソケットはブロッキングモードになります。

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

バージョン 3.7 で変更: socket.type の SOCK_NONBLOCK フラグを切り替えなくなりました。

バージョン 3.15 で変更: 整数や浮動小数点数に限らず、任意の実数を受け付けるようになりました。

setsockopt(level, optname, value: int | Buffer)¶
setsockopt(level, optname, None, optlen: int): 指定されたソケットオプションの値を設定します (Unix のマニュアルページ setsockopt(2) を参照)。必要なシンボル定数 (SO_* など <socket-unix-constants>) はこのモジュールで定義されています。値には、整数、None、またはバッファを表すバイト列類似オブジェクトを指定できます。最後の場合、バイト列に適切なビットが含まれていることを呼び出し側で保証する必要があります (C の構造体をバイト列にエンコードする方法は、オプションの組み込みモジュール struct を参照してください)。 value が None の場合は optlen 引数が必要です。これは、C 関数 setsockopt() を optval=NULL、optlen=optlen で呼び出すことに相当します。

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

バージョン 3.6 で変更: setsockopt(level, optname, None, optlen: int) の形式が追加されました。

利用可能な環境: not WASI.

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

利用可能な環境: not WASI.

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

利用可能な環境: Windows.

Added in version 3.3.

read() メソッドや write() メソッドはありません。代わりに flags 引数を付けずに recv() と send() を使ってください。

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

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

type¶: ソケットタイプ。

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

class socket.SocketType¶: _socket から再公開された socket 型の基底クラスです。 isinstance(socket(...), SocketType) のようなインスタンス検査は真になりますが、SocketType は type(socket(...)) と同じではありません。後者は socket 自身です。

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

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

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

注釈

At the operating system level, sockets in timeout mode are internally set in non-blocking mode. Also, the blocking and timeout modes are shared between file descriptors and socket objects that refer to the same network endpoint. This implementation detail can have visible consequences if e.g. you decide to use the fileno() of a socket.

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

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

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

getdefaulttimeout() の戻り値が None でなければ、accept() メソッドが返すソケットはそのタイムアウトを引き継ぎます。そうでなければ、動作は接続を待ち受けるソケットの設定によって異なります:

待機中のソケットが ブロッキングモード または タイムアウトモード である場合、accept() が返すソケットは、ブロッキングモード になります。
待機中のソケットが 非ブロッキングモード である場合、accept() が返すソケットは、オペレーティングシステムによってブロッキングモードまたは非ブロッキングモードになります。クロスプラットフォームの動作を確保したい場合、この設定を手動でオーバーライドすることをお勧めします。

使用例¶

以下に TCP/IP プロトコルを使う最小限のサンプルプログラムを 4 つ示します。受信したすべてのデータをそのまま送り返すサーバ (クライアント 1 つだけを処理) と、それを使うクライアントです。サーバでは socket()、bind()、listen()、accept() の順に実行する必要があります (複数のクライアントを処理するには accept() を繰り返します)。一方、クライアントで必要なのは socket()、connect() の順に実行することだけです。また、サーバは接続を待ち受けるソケットではなく、accept() が返した新しいソケットで sendall() と recv() を行うことにも注意してください。

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

# エコーサーバのプログラム
import socket

HOST = ''                 # 利用可能なすべてのインターフェースを表す名前
PORT = 50007              # 特権を必要としない任意のポート
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)

# エコークライアントのプログラム
import socket

HOST = 'daring.cwi.nl'    # リモートホスト
PORT = 50007              # サーバが使うポートと同じ番号
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))

次の 2 つの例は上の 2 つと同じですが、IPv4 と IPv6 の両方をサポートします。サーバ側は最初に利用できたアドレスファミリーで接続を待ち受けます (本来は両方で待ち受けるべきです)。 IPv6 対応のほとんどのシステムでは IPv6 が優先されるため、サーバが IPv4 の通信を受け入れないことがあります。クライアント側は名前解決で得られたすべてのアドレスへの接続を試み、最初に接続できたアドレスにデータを送信します。

# エコーサーバのプログラム
import socket
import sys

HOST = None               # 利用可能なすべてのインターフェースを表す名前
PORT = 50007              # 特権を必要としない任意のポート
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)

# エコークライアントのプログラム
import socket
import sys

HOST = 'daring.cwi.nl'    # リモートホスト
PORT = 50007              # サーバが使うポートと同じ番号
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

# 外部向けのネットワークインターフェース
HOST = socket.gethostbyname(socket.gethostname())

# raw ソケットを作成し、外部向けのインターフェースにバインドする
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# IP ヘッダーを含める
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# すべてのパケットを受信する
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# パケットを 1 つ受信する
print(s.recvfrom(65565))

# プロミスキャスモードを無効にする
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

次の例では、ソケットインターフェースを使用してローソケットプロトコルを使用する CAN ネットワークと通信する方法を説明します。ブロードキャストマネージャプロトコルで CAN を使用するには、以下でソケットを開きます。

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

ソケットの束縛 (CAN_RAW) または (CAN_BCM) 接続を行ったあと、ソケットオブジェクトで socket.send() と socket.recv() 操作 (とそのカウンターパート) を通常通りに使用することができます。

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

import socket
import struct


# CAN フレームのパックとアンパック (<linux/can.h> の 'struct can_frame' を参照)

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])


# raw ソケットを作成し、'vcan0' インターフェースにバインドする
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" を参照してください。

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

ソケットファミリー¶

モジュールの内容¶

例外¶

定数¶

関数¶

ソケットの作成¶

その他の関数¶

socket オブジェクト¶

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

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

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

使用例¶

目次

前のトピックへ

次のトピックへ

このページ

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

ソケットファミリー¶

モジュールの内容¶

例外¶

定数¶

関数¶

ソケットの作成¶

その他の関数¶

socket オブジェクト¶

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

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

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

使用例¶

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

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

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