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

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

======================================================================

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

注釈:

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

利用可能な環境: not WASI.

このモジュールは 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" を参照してください。
