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

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

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

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

注釈:

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

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* は整数です。

  * For IPv4 addresses, two special forms are accepted instead of a
    host address: "''" represents "INADDR_ANY", which is used to bind
    to all interfaces, and the string "'<broadcast>'" represents
    "INADDR_BROADCAST".  This behavior is not compatible with IPv6,
    therefore, you may want to avoid these if you intend to support
    IPv6 with your Python programs.

* "AF_INET6" アドレスファミリーでは、 "(host, port, flowinfo,
  scopeid)" の4 要素のタプルが利用されます。 *flowinfo* と *scopeid*
  はそれぞれC言語の "struct sockaddr_in6" の "sin6_flowinfo" と
  "sin6_scope_id" メンバーを表します。 "socket" モジュールのメソッドで
  は、後方互換性のために *flowinfo* と *scopeid* の省略を許しています
  。しかし、 *scopeid* を省略すると scope された IPv6 アドレスを操作す
  るときに問題が起こる場合があることに注意してください。

  バージョン 3.7 で変更: For multicast addresses (with *scopeid*
  meaningful) *address* may not contain "%scope" (or "zone id") part.
  This information is superfluous and may be safely omitted
  (recommended).

* "AF_NETLINK" ソケットのアドレスは "(pid, groups)" のペアで表されます
  。

* Linux 限定で、 "AF_TIPC" アドレスファミリーを用いて TIPC がサポート
  されます。 TIPC は、クラスタコンピューティング環境のために設計された
  、IP ベースではないオープンなネットワークプロトコルです。アドレスは
  タプルで表現され、フィールドはアドレスタイプに依存します。一般的なタ
  プルの形式は "(addr_type, v1, v2, v3 [, scope])" で、それぞれは次の
  通りです:

  * *addr_type* は "TIPC_ADDR_NAMESEQ", "TIPC_ADDR_NAME",
    "TIPC_ADDR_ID" の1つ。

  * *scope* は "TIPC_ZONE_SCOPE", "TIPC_CLUSTER_SCOPE",
    "TIPC_NODE_SCOPE" の1つ。

  * *addr_type* が "TIPC_ADDR_NAME" の場合、 *v1* はサーバータイプ、
    *v2* はポートID (the port identifier)、そして *v3* は 0 であるべき
    です。

    *addr_type* が "TIPC_ADDR_NAMESEQ" の場合、 *v1* はサーバータイプ
    、 *v2* はポート番号下位(lower port number)、 *v3* はポート番号上
    位(upper port number) です。

    *addr_type* が "TIPC_ADDR_ID" の場合、 *v1* はノード、 *v2* は参照
    、 *v3* は0であるべきです。

* "AF_CAN" アドレスファミリーには "(interface,)" というタプルを利用し
  ます。 *interface* は "'can0'" のようなネットワークインタフェース名
  を表す文字列です。このファミリーの全てのネットワークインタフェースか
  らパケットを受信するために、ネットワークインタフェース名 "''" を利用
  できます。

  * "CAN_ISOTP" protocol require a tuple "(interface, rx_addr,
    tx_addr)" where both additional parameters are unsigned long
    integer that represent a CAN identifier (standard or extended).

* 文字列またはタプル "(id, unit)" は "PF_SYSTEM" ファミリーの
  "SYSPROTO_CONTROL" プロトコルのために使用されます。この文字列は、動
  的に割り当てられたIDによるカーネルコントロールの名前です。このタプル
  は、カーネルコントロールのIDとユニット番号が既知の場合、または登録済
  みIDが使用中の場合に使用することができます。

  バージョン 3.3 で追加.

* "AF_BLUETOOTH" は以下のプロトコルとアドレスフォーマットをサポートし
  ています。

  * "BTPROTO_L2CAP" は "(bdaddr, psm)" を受け取ります。 "bdaddr" は
    Bluetooth アドレスを表す文字列で、 "psm" は整数です。

  * "BTPROTO_RFCOMM" は "(bdaddr, channel)" を受け取ります。 "bdaddr"
    は Bluetooth アドレスを表す文字列で、 "channel" は整数です。

  * "BTPROTO_HCI" は "(device_id,)" を受け取ります。 "device_id" は、
    数値またはインターフェイスの Bluetooth アドレスを表す文字列です。
    (OS に依存します。NetBSD と DragonFlyBSD は Bluetooth アドレスを期
    待しますが、その他すべての OS は、数値を期待します。)

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

  * "BTPROTO_SCO" は "bdaddr" を受け取ります。ここで、 "bdaddr" は
    Bluetooth アドレスを文字列形式で持つ "bytes" オブジェクトです (例:
    "b'12:23:34:45:56:67'")。このプロトコルは、  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 ビットの整数です。

  Availability: Linux 2.6.38, some algorithm types require more recent
  Kernels.

  バージョン 3.6 で追加.

* "AF_VSOCK" allows communication between virtual machines and their
  hosts. The sockets are represented as a "(CID, port)" tuple where
  the context ID or CID and port are integers.

  Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >=
  6.5.

  バージョン 3.7 で追加.

* "AF_PACKET" is a low-level interface directly to network devices.
  The packets are represented by the tuple "(ifname, proto[, pkttype[,
  hatype[, addr]]])" where:

  * *ifname* - デバイス名を指定する文字列。

  * *proto* - An in network-byte-order integer specifying the Ethernet
    protocol number.

  * *pkttype* - パケットタイプを指定するオプションの整数:

    * "PACKET_HOST" (the default) - Packet addressed to the local
      host.

    * "PACKET_BROADCAST" - Physical-layer broadcast packet.

    * "PACKET_MULTIHOST" - Packet sent to a physical-layer multicast
      address.

    * "PACKET_OTHERHOST" - Packet to some other host that has been
      caught by a device driver in promiscuous mode.

    * "PACKET_OUTGOING" - Packet originating from the local host that
      is looped back to a packet socket.

  * *hatype* - Optional integer specifying the ARP hardware address
    type.

  * *addr* - Optional bytes-like object specifying the hardware
    physical address, whose interpretation depends on the device.

* "AF_QIPCRTR" is a Linux-only socket based interface for
  communicating with services running on co-processors in Qualcomm
  platforms. The address family is represented as a "(node, port)"
  tuple where the *node* and *port* are non-negative integers.

  バージョン 3.8 で追加.

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

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

"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

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

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


定数
----

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

   バージョン 3.4 で追加.

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

   アドレス (およびプロトコル) ファミリーを示す定数で、 "socket()" の
   最初の引数に指定することができます。 "AF_UNIX" ファミリーをサポート
   しないプラットフォームでは、 "AF_UNIX" は未定義となります。システム
   によってはこれら以外の定数が定義されているかもしれません。

socket.SOCK_STREAM
socket.SOCK_DGRAM
socket.SOCK_RAW
socket.SOCK_RDM
socket.SOCK_SEQPACKET

   ソケットタイプを示す定数で、 "socket()" の2番目の引数に指定すること
   ができます。システムによってはこれら以外の定数が定義されているかも
   しれません。 (ほとんどの場合、 "SOCK_STREAM" と "SOCK_DGRAM" 以外は
   必要ありません。)

socket.SOCK_CLOEXEC
socket.SOCK_NONBLOCK

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

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

   利用可能な環境: Linux 2.6.27以上。

   バージョン 3.2 で追加.

SO_*
socket.SOMAXCONN
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*

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

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

   バージョン 3.6.5 で変更: Windowsでは、実行時のWindowsがサポートして
   いるならば "TCP_FASTOPEN"、 >>``<<TCP_KEEPCNT``が表示されます。

   バージョン 3.7 で変更: >>``<<TCP_NOTSENT_LOWAT``が追加されました。
   Windowsでは、実行時のWindowsがサポートしているならば
   "TCP_KEEPIDLE", "TCP_KEEPINTVL" が表示されます。

socket.AF_CAN
socket.PF_CAN
SOL_CAN_*
CAN_*

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

   利用可能な環境: Linux 2.6.25以上。

   バージョン 3.3 で追加.

socket.CAN_BCM
CAN_BCM_*

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

   利用可能な環境: Linux 2.6.25以上。

   注釈:

     The "CAN_BCM_CAN_FD_FRAME" flag is only available on Linux >=
     4.8.

   バージョン 3.4 で追加.

socket.CAN_RAW_FD_FRAMES

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

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

   利用可能な環境: Linux 3.6以上。

   バージョン 3.5 で追加.

socket.CAN_ISOTP

   CAN_ISOTP, in the CAN protocol family, is the ISO-TP (ISO 15765-2)
   protocol. ISO-TP constants, documented in the Linux documentation.

   利用可能な環境: Linux 2.6.25以上。

   バージョン 3.7 で追加.

socket.AF_PACKET
socket.PF_PACKET
PACKET_*

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

   利用可能な環境: Linux 2.2以上。

socket.AF_RDS
socket.PF_RDS
socket.SOL_RDS
RDS_*

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

   利用可能な環境: Linux 2.6.30以上。

   バージョン 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以上。

   バージョン 3.6 で追加.

socket.AF_VSOCK
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID
VMADDR*
SO_VM*

   Constants for Linux host/guest communication.

   利用可能な環境: Linux 4.8以上。

   バージョン 3.7 で追加.

socket.AF_LINK

   利用可能な環境: BSD, OSX。

   バージョン 3.4 で追加.

socket.has_ipv6

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

socket.BDADDR_ANY
socket.BDADDR_LOCAL

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

socket.HCI_FILTER
socket.HCI_TIME_STAMP
socket.HCI_DATA_DIR

   "BTPROTO_HCI" で使用します。 "HCI_FILTER" は NetBSD または
   DragonFlyBSD では使用できません。 "HCI_TIME_STAMP" と
   "HCI_DATA_DIR" は FreeBSD, NetBSD, DragonFlyBSD では使用できません
   。

socket.AF_QIPCRTR

   Constant for Qualcomm's IPC router protocol, used to communicate
   with service providing remote processors.

   利用可能な環境: Linux 4.7以上。


関数
----


ソケットの作成
~~~~~~~~~~~~~~

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

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

   Create a new socket using the given address family, socket type and
   protocol number.  The address family should be "AF_INET" (the
   default), "AF_INET6", "AF_UNIX", "AF_CAN", "AF_PACKET", or
   "AF_RDS". The socket type should be "SOCK_STREAM" (the default),
   "SOCK_DGRAM", "SOCK_RAW" or perhaps one of the other "SOCK_"
   constants. The protocol number is usually zero and may be omitted
   or in the case where the address family is "AF_CAN" the protocol
   should be one of "CAN_RAW", "CAN_BCM" or "CAN_ISOTP".

   If *fileno* is specified, the values for *family*, *type*, and
   *proto* are auto-detected from the specified file descriptor.
   Auto-detection can be overruled by calling the function with
   explicit *family*, *type*, or *proto* arguments.  This only affects
   how Python represents e.g. the return value of
   "socket.getpeername()" but not the actual OS resource.  Unlike
   "socket.fromfd()", *fileno* will return the same socket and not a
   duplicate. This may help close a detached socket using
   "socket.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 で変更: When "SOCK_NONBLOCK" or "SOCK_CLOEXEC" bit
   flags are applied to *type* they are cleared, and "socket.type"
   will not reflect them.  They are still passed to the underlying
   system *socket()* call.  Therefore,

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

   will still create a non-blocking socket on OSes that support
   "SOCK_NONBLOCK", but "sock.type" will be set to
   "socket.SOCK_STREAM".

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

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

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

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

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

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

socket.create_connection(address[, timeout[, source_address]])

   *address* ("(host, port)" ペア) で listen しているTCPサービスに接続
   し、ソケットオブジェクトを返します。これは "socket.connect()" を高
   級にした関数です。 *host* が数値でないホスト名の場合、 "AF_INET" と
   "AF_INET6" の両方で名前解決を試み、得られた全てのアドレスに対して成
   功するまで接続を試みます。この関数を使って IPv4 と IPv6 に両対応し
   たクライアントを簡単に書くことができます。

   オプションの *timeout* 引数を指定すると、接続を試みる前にソケットオ
   ブジェクトのタイムアウトを設定します。 *timeout* が指定されない場合
   、 "getdefaulttimeout()" が返すデフォルトのタイムアウト設定値を利用
   します。

   *source_address* は接続する前にバインドするソースアドレスを指定する
   オプション引数で、指定する場合は "(host, port)" の2要素タプルでなけ
   ればなりません。 host や port が '' か 0 だった場合は、OSのデフォル
   トの動作になります。

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

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

   Convenience function which creates a TCP socket bound to *address*
   (a 2-tuple "(host, port)") and return the socket object.

   *family* should be either "AF_INET" or "AF_INET6". *backlog* is the
   queue size passed to "socket.listen()"; when "0" a default
   reasonable value is chosen. *reuse_port* dictates whether to set
   the "SO_REUSEPORT" socket option.

   If *dualstack_ipv6* is true and the platform supports it the socket
   will be able to accept both IPv4 and IPv6 connections, else it will
   raise "ValueError". Most POSIX platforms and Windows are supposed
   to support this functionality. When this functionality is enabled
   the address returned by "socket.getpeername()" when an IPv4
   connection occurs will be an IPv6 address represented as an
   IPv4-mapped IPv6 address. If *dualstack_ipv6* is false it will
   explicitly disable this functionality on platforms that enable it
   by default (e.g. Linux). This parameter can be used in conjunction
   with "has_dualstack_ipv6()":

      import socket

      addr = ("", 8080)  # all interfaces, port 8080
      if socket.has_dualstack_ipv6():
          s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
      else:
          s = socket.create_server(addr)

   注釈:

     On POSIX platforms the "SO_REUSEADDR" socket option is set in
     order to immediately reuse previous sockets which were bound on
     the same *address* and remained in TIME_WAIT state.

   バージョン 3.8 で追加.

socket.has_dualstack_ipv6()

   Return "True" if the platform supports creating a TCP socket which
   can handle both IPv4 and IPv6 connections.

   バージョン 3.8 で追加.

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

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

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

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

socket.fromshare(data)

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

   利用可能な環境: Windows 。

   バージョン 3.3 で追加.

socket.SocketType

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


その他の関数
~~~~~~~~~~~~

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

socket.close(fd)

   Close a socket file descriptor. This is like "os.close()", but for
   sockets. On some platforms (most noticeable Windows) "os.close()"
   does not work for socket file descriptors.

   バージョン 3.7 で追加.

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

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

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

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

   "(family, type, proto, canonname, sockaddr)"

   このタプルにある *family*, *type*, *proto* は、 "socket()" 関数を呼
   び出す際に指定する値と同じ整数です。 "AI_CANONNAME" を含んだ
   *flags* を指定した場合、 *canonname* は *host* の canonical name を
   示す文字列です。そうでない場合は *canonname* は空文字列です。
   *sockaddr* は、ソケットアドレスを *family* に依存した形式で表すタプ
   ルで、 ("AF_INET" の場合は 2 要素のタプル "(address, port)" 、
   "AF_INET6" の場合は 4 要素のタプル "(address, port, flow info,
   scope id)") "socket.connect()" メソッドに渡すためのものです。

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

   次の例では "example.org" の 80 番ポートポートへの TCP 接続を得るた
   めのアドレス情報を取得しようとしています。 (結果は IPv6 をサポート
   しているかどうかで変わります):

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

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

   バージョン 3.7 で変更: for IPv6 multicast addresses, string
   representing an address will not contain "%scope" part.

socket.getfqdn([name])

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

socket.gethostbyname(hostname)

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

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

socket.gethostbyname_ex(hostname)

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

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

socket.gethostname()

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

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

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

socket.gethostbyaddr(ip_address)

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

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

socket.getnameinfo(sockaddr, flags)

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

   For IPv6 addresses, "%scope" is appended to the host part if
   *sockaddr* contains meaningful *scopeid*. Usually this happens for
   multicast addresses.

   For more information about *flags* you can consult
   *getnameinfo(3)*.

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

socket.getprotobyname(protocolname)

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

socket.getservbyname(servicename[, protocolname])

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

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

socket.getservbyport(port[, protocolname])

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

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

socket.ntohl(x)

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

socket.ntohs(x)

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

   バージョン 3.7 で非推奨: In case *x* does not fit in 16-bit
   unsigned integer, but does fit in a positive C int, it is silently
   truncated to 16-bit unsigned integer. This silent truncation
   feature is deprecated, and will raise an exception in future
   versions of Python.

socket.htonl(x)

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

socket.htons(x)

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

   バージョン 3.7 で非推奨: In case *x* does not fit in 16-bit
   unsigned integer, but does fit in a positive C int, it is silently
   truncated to 16-bit unsigned integer. This silent truncation
   feature is deprecated, and will raise an exception in future
   versions of Python.

socket.inet_aton(ip_string)

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

   "inet_aton()" はドットが 3 個以下の文字列も受け取ります; 詳細につい
   ては Unix のマニュアル *inet(3)* を参照してください。

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

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

socket.inet_ntoa(packed_ip)

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

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

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

socket.inet_pton(address_family, ip_string)

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

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

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

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

socket.inet_ntop(address_family, packed_ip)

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

   現在サポートされている *address_family* の値は、 "AF_INET" と
   "AF_INET6" です。バイトオブジェクトの *packed_ip* の長さが、指定し
   たアドレスファミリで適切な長さでない場合、 "ValueError" が発生しま
   す。 "inet_ntop()" の呼び出しでエラーが起こると、 "OSError" が発生
   します。

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

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

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

socket.CMSG_LEN(length)

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

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

   バージョン 3.3 で追加.

socket.CMSG_SPACE(length)

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

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

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

   バージョン 3.3 で追加.

socket.getdefaulttimeout()

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

socket.setdefaulttimeout(timeout)

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

socket.sethostname(name)

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

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

   利用可能な環境: Unix。

   バージョン 3.3 で追加.

socket.if_nameindex()

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

   Availability: Unix, Windows。

   バージョン 3.3 で追加.

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

   注釈:

     On Windows network interfaces have different names in different
     contexts (all names are examples):

     * UUID: "{FB605B73-AAC2-49A6-9A2F-25416AEA0573}"

     * name: "ethernet_32770"

     * friendly name: "vEthernet (nat)"

     * description: "Hyper-V Virtual Ethernet Adapter"

     This function returns names of the second form from the list,
     "ethernet_32770" in this example case.

socket.if_nametoindex(if_name)

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

   Availability: Unix, Windows。

   バージョン 3.3 で追加.

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

   参考: "Interface name" is a name as documented in "if_nameindex()".

socket.if_indextoname(if_index)

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

   Availability: Unix, Windows。

   バージョン 3.3 で追加.

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

   参考: "Interface name" is a name as documented in "if_nameindex()".


socket オブジェクト
===================

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

バージョン 3.2 で変更: *context manager* プロトコルのサポートが追加さ
れました。コンテキストマネージャを終了することは、 "close()" を呼ぶこ
とと同一です。

socket.accept()

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

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

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

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

socket.bind(address)

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

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

socket.close()

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

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

   バージョン 3.6 で変更: 下層の "close()" が呼び出される時、"OSError"
   が送出されるようになりました。

   注釈:

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

socket.connect(address)

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

   接続が信号によって中断された場合、このメソッドは接続が完了するまで
   待機するか、タイムアウト時に "socket.timeout" を送出します。タイム
   アウトは、信号ハンドラが例外を送出せず、ソケットがブロックするかタ
   イムアウトが設定されている場合に起こります。非ブロックソケットでは
   、接続が信号によって中断された場合 (あるいは信号ハンドラにより例外
   が送出された場合)、このメソッドは "InterruptedError" 例外を送出しま
   す。

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

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

socket.connect_ex(address)

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

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

socket.detach()

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

   バージョン 3.2 で追加.

socket.dup()

   ソケットを複製します。

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

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

socket.fileno()

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

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

socket.get_inheritable()

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

   バージョン 3.4 で追加.

socket.getpeername()

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

socket.getsockname()

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

socket.getsockopt(level, optname[, buflen])

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

socket.getblocking()

   Return "True" if socket is in blocking mode, "False" if in non-
   blocking.

   This is equivalent to checking "socket.gettimeout() == 0".

   バージョン 3.7 で追加.

socket.gettimeout()

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

socket.ioctl(control, option)

   プラットフォーム:
      Windows

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

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

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

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

socket.listen([backlog])

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

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

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

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

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

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

   注釈:

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

socket.recv(bufsize[, flags])

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

   注釈:

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

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

socket.recvfrom(bufsize[, flags])

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

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

   バージョン 3.7 で変更: For multicast IPv6 address, first item of
   *address* does not contain "%scope" part anymore. In order to get
   full IPv6 address use "getnameinfo()".

socket.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" 型のバイナリ
   配列として表します。システムコールが返った後 "recvmsg()" が例外を送
   出する場合、まずこのメカニズムを経由して受信したファイル記述子を全
   て閉じようと試みます。

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

   "SCM_RIGHTS" メカニズムをサポートするシステム上では、次の関数が最大
   *maxfds* のファイル記述子を受信し、メッセージデータと記述子を含むリ
   ストを返しま(無関係な制御メッセージを受信した場合など、予期しない条
   件は無視します)。 "sendmsg()" も参照してください。

      import socket, array

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

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

   バージョン 3.3 で追加.

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

socket.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---')]

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

   バージョン 3.3 で追加.

socket.recvfrom_into(buffer[, nbytes[, flags]])

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

socket.recv_into(buffer[, nbytes[, flags]])

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

socket.send(bytes[, flags])

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

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

socket.sendall(bytes[, flags])

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

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

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

socket.sendto(bytes, address)
socket.sendto(bytes, flags, address)

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

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

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

socket.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" メカニズムをサポートするシステムで、ファ
   イル記述子 *fds* を "AF_UNIX" ソケット経由で送信します。"recvmsg()"
   も参照してください。

      import socket, array

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

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

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

   バージョン 3.3 で追加.

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

socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]])

   "sendmsg()" の "AF_ALG" ソケット用に特化したバージョンです。
   "AF_ALG" ソケットの、モード、IV、AEAD に関連づけられたデータ長、フ
   ラグを設定します。

   利用可能な環境: Linux 2.6.38以上。

   バージョン 3.6 で追加.

socket.sendfile(file, offset=0, count=None)

   高性能の "os.sendfile" を使用して、ファイルを EOF まで送信し、送信
   されたバイトの総数を返します。*file* は、バイナリモードで開かれた標
   準的なファイルオブジェクトです。"os.sendfile" が使用できない場合 (
   例: Windows)、または *file* が標準的なファイルでない場合、代わりに
   "send()" が使用されます。*offset* は、ファイルの読み出し開始位置を
   指定します。*count* が指定されている場合、ファイルを EOF まで送信す
   るのではなく、転送するバイトの総数を指定します。ファイルの位置は、
   返る時に更新されます。あるいは、エラー時には "file.tell()"  を使用
   して送信されたバイトの数を確認することができます。ソケットは
   "SOCK_STREAM" タイプでなければなりません。非ブロックソケットはサポ
   ートされていません。

   バージョン 3.5 で追加.

socket.set_inheritable(inheritable)

   ソケットのファイル記述子、またはソケットのハンドルの、 継承可能フラ
   グ を立てます。

   バージョン 3.4 で追加.

socket.setblocking(flag)

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

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

   * "sock.setblocking(True)" は "sock.settimeout(None)" と等価です

   * "sock.setblocking(False)" は "sock.settimeout(0.0)" と等価です

   バージョン 3.7 で変更: The method no longer applies "SOCK_NONBLOCK"
   flag on "socket.type".

socket.settimeout(value)

   ブロッキングソケットの処理のタイムアウト値を指定します。 *value* に
   は float 型で非負の秒数を指定するか、 "None" を指定します。ゼロ以外
   の値を指定した場合、ソケットの処理が完了する前に *value* で指定した
   秒数が経過すれば "timeout" 例外を送出します。ゼロを指定した場合、ソ
   ケットは非ブロッキングモード状態に置かれます。 "None" を指定した場
   合、ソケットのタイムアウトを無効にします。

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

   バージョン 3.7 で変更: The method no longer toggles "SOCK_NONBLOCK"
   flag on "socket.type".

socket.setsockopt(level, optname, value: int)

socket.setsockopt(level, optname, value: buffer)

socket.setsockopt(level, optname, None, optlen: int)

   指定されたソケットオプションの値を設定します (Unix のマニュアルペー
   ジ *setsockopt(2)* を参照)。必要なシンボリック定数は、"socket" モジ
   ュール ("SO_*" など) で定義されています。この値は、整数、"None"、ま
   たはバッファを表す *bytes-like object* のいずれかです。バイトライク
   オブジェクトの場合、バイト文字列に適切なビットが含まれていることを
   確認するのは呼び出し元の仕事です (C 構造をバイト文字列としてエンコ
   ードする方法については、オプションの組み込みモジュール "struct" を
   参照)。値が "None" に設定されている場合、optlen 引数が必須です。こ
   れは、 "optval=NULL" と "optlen=optlen" で "setsockopt()" C 関数を
   呼び出すのと同一です。

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

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

socket.shutdown(how)

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

socket.share(process_id)

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

   利用可能な環境: Windows 。

   バージョン 3.3 で追加.

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

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

socket.family

   ソケットファミリー。

socket.type

   ソケットタイプ。

socket.proto

   ソケットプロトコル。


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

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

* *ブロッキングモード* での操作は、完了するか、または（接続がタイムア
  ウトするなどして）システムがエラーを返すまで、ブロックされます。

* *非ブロッキングモード* での操作は、ただちに完了できない場合、例外を
  送出して失敗します。この場合の例外の種類は、システムに依存するため、
  ここに記すことができません。 "select" モジュールの関数を使って、ソケ
  ットの読み書きが利用可能かどうか、可能な場合はいつ利用できるかを調べ
  ることができます。

* *タイムアウトモード* での操作は、指定されたタイムアウトの時間内に完
  了しなければ、 "timeout" 例外を送出します。タイムアウトの時間内にシ
  ステムがエラーを返した場合は、そのエラーを返します。

注釈:

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


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

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


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

"getdefaulttimeout()" が "None" でない場合、 "accept()" メソッドが返す
ソケットでは、そのタイムアウトが継承されます。 "None" である場合、待機
中のソケットの設定によって動作は異なります。

* 待機中のソケットが *ブロッキングモード* または *タイムアウトモード*
  である場合、"accept()" が返すソケットは、*ブロッキングモード* になり
  ます。

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


使用例
======

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

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

   # Echo server program
   import socket

   HOST = ''                 # Symbolic name meaning all available interfaces
   PORT = 50007              # Arbitrary non-privileged port
   with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
       s.bind((HOST, PORT))
       s.listen(1)
       conn, addr = s.accept()
       with conn:
           print('Connected by', addr)
           while True:
               data = conn.recv(1024)
               if not data: break
               conn.sendall(data)

   # Echo client program
   import socket

   HOST = 'daring.cwi.nl'    # The remote host
   PORT = 50007              # The same port as used by the server
   with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
       s.connect((HOST, PORT))
       s.sendall(b'Hello, world')
       data = s.recv(1024)
   print('Received', repr(data))

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

   # Echo server program
   import socket
   import sys

   HOST = None               # Symbolic name meaning all available interfaces
   PORT = 50007              # Arbitrary non-privileged port
   s = None
   for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                                 socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
       af, socktype, proto, canonname, sa = res
       try:
           s = socket.socket(af, socktype, proto)
       except OSError as msg:
           s = None
           continue
       try:
           s.bind(sa)
           s.listen(1)
       except OSError as msg:
           s.close()
           s = None
           continue
       break
   if s is None:
       print('could not open socket')
       sys.exit(1)
   conn, addr = s.accept()
   with conn:
       print('Connected by', addr)
       while True:
           data = conn.recv(1024)
           if not data: break
           conn.send(data)

   # Echo client program
   import socket
   import sys

   HOST = 'daring.cwi.nl'    # The remote host
   PORT = 50007              # The same port as used by the server
   s = None
   for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
       af, socktype, proto, canonname, sa = res
       try:
           s = socket.socket(af, socktype, proto)
       except OSError as msg:
           s = None
           continue
       try:
           s.connect(sa)
       except OSError as msg:
           s.close()
           s = None
           continue
       break
   if s is None:
       print('could not open socket')
       sys.exit(1)
   with s:
       s.sendall(b'Hello, world')
       data = s.recv(1024)
   print('Received', repr(data))

次の例は、Windowsで raw socket を利用して非常にシンプルなネットワーク
スニファーを書きます。このサンプルを実行するには、インタフェースを操作
するための管理者権限が必要です:

   import socket

   # the public network interface
   HOST = socket.gethostbyname(socket.gethostname())

   # create a raw socket and bind it to the public interface
   s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
   s.bind((HOST, 0))

   # Include IP headers
   s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

   # receive all packages
   s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

   # receive a package
   print(s.recvfrom(65565))

   # disabled promiscuous mode
   s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

次の例では、ソケットインターフェースを使用してローソケットプロトコルを
使用する 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 frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

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

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

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


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

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

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

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

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

この例を、ほとんど間を空けずに複数回実行すると、以下のエラーが発生する
場合があります:

   OSError: [Errno 98] Address already in use

これは以前の実行がソケットを "TIME_WAIT" 状態のままにし、すぐには再利
用できないことで起こります。

これを防ぐのに、 "socket" フラグの "socket.SO_REUSEADDR" があります:

   s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
   s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
   s.bind((HOST, PORT))

"SO_REUSEADDR" フラグは、 "TIME_WAIT" 状態にあるローカルソケットをその
タイムアウト期限が自然に切れるのを待つことなく再利用することをカーネル
に伝えます。

参考:

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

  * *An Introductory 4.3BSD Interprocess Communication Tutorial*, by
    Stuart Sechrest

  * *An Advanced 4.3BSD Interprocess Communication Tutorial*, by
    Samuel J.  Leffler et al,

  両書とも UNIX Programmer's Manual, Supplementary Documents 1 (PS1:7
  章 PS1:8章)。ソケットの詳細については、各プラットフォームのソケット
  関連システムコールに関するドキュメントも参照してください。Unix では
  マニュアルページ、WindowsではWinSock (または WinSock2) 仕様書をご覧
  ください。IPv6 対応の API については、 **RFC 3493** "Basic Socket
  Interface Extensions for IPv6" を参照してください。
