ソケットファミリー¶

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

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

• ファイルシステム上のノードに束縛された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) の4 要素のタプルが利用されます。flowinfo とscopeid はそれぞれC言語のstructsockaddr_in6 のsin6_flowinfo とsin6_scope_id メンバーを表します。socket モジュールのメソッドでは、後方互換性のためにflowinfo とscope_id の省略を許しています。しかし、scope_id を省略すると scope された IPv6 アドレスを操作するときに問題が起こる場合があることに注意してください。

  バージョン 3.7 で変更:Для багатоадресних адрес (зі значеннямscope_id)address не може містити частину%scope_id (абоzoneid). Ця інформація є зайвою, і її можна сміливо опустити (рекомендовано).

• 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 вимагає кортеж(interface,rx_addr,tx_addr), де обидва додаткові параметри є довгим цілим числом без знаку, що представляє ідентифікатор CAN (стандартний або розширений).

  • ПротоколCAN_J1939 вимагає кортеж(interface,name,pgn,addr), де додаткові параметри є 64-розрядним цілим числом без знака, що представляє назву ECU, 32-розрядним цілим числом без знака, що представляє номер групи параметрів (PGN ) і 8-бітове ціле число, що представляє адресу.

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

  Added in version 3.3.

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

  • BTPROTO_L2CAP accepts(bdaddr,psm) wherebdaddr isthe Bluetooth address as a string andpsm is an integer.

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

  • BTPROTO_HCI accepts a format that depends on your OS.

    • On Linux it accepts a tuple(device_id,) wheredevice_idis an integer specifying the number of the Bluetooth device.

    • On FreeBSD, NetBSD and DragonFly BSD it acceptsbdaddrwherebdaddr is the Bluetooth address as a string.

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

    バージョン 3.13.3 で変更:FreeBSD support added.

  • BTPROTO_SCO acceptsbdaddr wherebdaddr isthe Bluetooth address as a string or abytes object.(ex.'12:23:34:45:56:67' orb'12:23:34:45:56:67')This protocol is not supported under 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.

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

  Added in version 3.6.

• AF_VSOCK дозволяє спілкуватися між віртуальними машинами та їх хостами. Сокети представлені як кортеж(CID,порт), де ідентифікатор контексту або CID і порт є цілими числами.

  Availability: Linux >= 3.9

  Seevsock(7)

  Added in version 3.7.

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

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

  • proto - The Ethernet protocol number.May beETH_P_ALL to capture all protocols,one of theETHERTYPE_* constantsor any other Ethernet protocol number.

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

    • PACKET_HOST (за замовчуванням) - пакет, адресований локальному хосту.

    • PACKET_BROADCAST - широкомовний пакет фізичного рівня.

    • PACKET_MULTICAST - Packet sent to a physical-layer multicast address.

    • PACKET_OTHERHOST - Пакет до іншого хосту, який був перехоплений драйвером пристрою в безладному режимі.

    • PACKET_OUTGOING – Пакет, що надходить від локального хосту і повертається до сокета пакета.

  • hatype – додаткове ціле число, що визначає тип апаратної адреси ARP.

  • addr – необов’язковий байтовий об’єкт, що вказує апаратну фізичну адресу, інтерпретація якої залежить від пристрою.

  Availability: Linux >= 2.2.

• AF_QIPCRTR — це інтерфейс на основі сокетів лише для Linux для зв’язку зі службами, що працюють на співпроцесорах на платформах Qualcomm. Сімейство адрес представлено як кортеж(вузол,порт), девузол іпорт є невід’ємними цілими числами.

  Availability: Linux >= 4.7.

  Added in version 3.8.

• IPPROTO_UDPLITE — це варіант UDP, який дозволяє вказати, яку частину пакету охоплює контрольна сума. Він додає два варіанти розеток, які ви можете змінити.self.setsockopt(IPPROTO_UDPLITE,UDPLITE_SEND_CSCOV,length) змінить частину вихідних пакетів, охоплених контрольною сумою, аself.setsockopt(IPPROTO_UDPLITE,UDPLITE_RECV_CSCOV,length) відфільтровує пакети, які покривають занадто мало їхні дані. В обох випадкахдовжина має бути вдіапазоні(8,2**16,8).

  Такий сокет має бути створений за допомогоюsocket(AF_INET,SOCK_DGRAM,IPPROTO_UDPLITE) для IPv4 абоsocket(AF_INET6,SOCK_DGRAM,IPPROTO_UDPLITE) для IPv6.

  Availability: Linux >= 2.6.20, FreeBSD >= 10.1

  Added in version 3.9.

• AF_HYPERV is a Windows-only socket based interface for communicatingwith Hyper-V hosts and guests. The address family is represented as a(vm_id,service_id) tuple where thevm_id andservice_id areUUID strings.

  Thevm_id is the virtual machine identifier or a set of known VMID valuesif the target is not a specific virtual machine. Known VMID constantsdefined onsocket are:

  • HV_GUID_ZERO

  • HV_GUID_BROADCAST

  • HV_GUID_WILDCARD - Used to bind on itself and accept connections fromall partitions.

  • HV_GUID_CHILDREN - Used to bind on itself and accept connection fromchild partitions.

  • HV_GUID_LOOPBACK - Used as a target to itself.

  • HV_GUID_PARENT - When used as a bind accepts connection from the parentpartition. When used as an address target it will connect to the parent partition.

  Theservice_id is the service identifier of the registered service.

  Added in version 3.12.

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

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

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

モジュールの内容¶

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

socket オブジェクト¶

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

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 を送出します。

Availability: not WASI.

socket.close()¶

Mark the socket closed. The underlying system resource (e.g. a filedescriptor) is also closed when all file objects frommakefile()are closed. Once that happens, all future operations on the socketobject will fail. The remote end will receive no more data (afterqueued data is flushed).

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

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

注釈

close() releases the resource associated with a connection butdoes not necessarily close the connection immediately. If you wantto close the connection in a timely fashion, callshutdown()beforeclose().

socket.connect(address)¶

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

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

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

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

Availability: not WASI.

socket.connect_ex(address)¶

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

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

Availability: not WASI.

socket.detach()¶

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

Added in version 3.2.

socket.dup()¶

ソケットを複製します。

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

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

Availability: not WASI.

socket.fileno()¶

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

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

socket.get_inheritable()¶

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

Added in version 3.4.

socket.getpeername()¶

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

socket.getsockname()¶

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

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

Return the value of the given socket option (see the Unix man pagegetsockopt(2)). The needed symbolic constants (SO_* etc.)are defined in this module. Ifbuflen is absent, an integer option is assumedand its integer value is returned by the function. Ifbuflen is present, itspecifies the maximum length of the buffer used to receive the option in, andthis buffer is returned as a bytes object. It is up to the caller to decode thecontents of the buffer (see the optional built-in modulestruct for a wayto decode C structures encoded as byte strings).

Availability: not WASI.

socket.getblocking()¶

ПовертаєTrue, якщо сокет знаходиться в режимі блокування,False, якщо він не блокується.

This is equivalent to checkingsocket.gettimeout()!=0.

Added in version 3.7.

socket.gettimeout()¶

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

socket.ioctl(control,option)¶

Platform:

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 に設定されます)。システムが新しい接続を拒否するまでに許可する未受付の接続の数を指定します。指定しない場合、デフォルトの妥当な値が選択されます。

Availability: not WASI.

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

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

Return afile object associated with the socket. The exact returnedtype depends on the arguments given tomakefile(). These arguments areinterpreted the same way as by the built-inopen() function, exceptthe only supportedmode values are'r' (default),'w','b', ora combination of those.

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

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

注釈

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

socket.recv(bufsize[,flags])¶

Receive data from the socket. The return value is a bytes object representing thedata received. The maximum amount of data to be received at once is specifiedbybufsize. A returned empty bytes object indicates that the client has disconnected.See the Unix manual pagerecv(2) for the meaning of the optional argumentflags; it defaults to zero.

バージョン 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 で変更:Для багатоадресної адреси IPv6 перший елементaddress більше не містить частини%scope_id. Щоб отримати повну адресу IPv6, використовуйте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 型のバイナリ配列として表すbytes オブジェクトです。システムコールが返った後recvmsg() が例外を送出する場合、まずこのメカニズムを経由して受信したファイル記述子を全て閉じようと試みます。

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

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

importsocket,arraydefrecv_fds(sock,msglen,maxfds):fds=array.array("i")# Array of intsmsg,ancdata,flags,addr=sock.recvmsg(msglen,socket.CMSG_LEN(maxfds*fds.itemsize))forcmsg_level,cmsg_type,cmsg_datainancdata:ifcmsg_level==socket.SOL_SOCKETandcmsg_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)])returnmsg,list(fds)

Availability: Unix.

Unix プラットフォーム。

Added in version 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() と同様です。

以下はプログラム例です:

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

Availability: Unix.

Unix プラットフォーム。

Added in version 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() も参照してください。

importsocket,arraydefsend_fds(sock,msg,fds):returnsock.sendmsg([msg],[(socket.SOL_SOCKET,socket.SCM_RIGHTS,array.array("i",fds))])

Availability: Unix, not WASI.

Unix プラットフォーム。

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

Added in version 3.3.

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

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

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

Availability: Linux >= 2.6.38.

Added in version 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 タイプでなければなりません。非ブロックソケットはサポートされていません。

Added in version 3.5.

socket.set_inheritable(inheritable)¶

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

Added in version 3.4.

socket.setblocking(flag)¶

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

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

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

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

バージョン 3.7 で変更:Метод більше не застосовує прапорSOCK_NONBLOCK доsocket.type.

socket.settimeout(value)¶

Set a timeout on blocking socket operations. Thevalue argument can be anonnegative floating-point number expressing seconds, orNone.If a non-zero value is given, subsequent socket operations will raise atimeout exception if the timeout periodvalue has elapsed beforethe operation has completed. If zero is given, the socket is put innon-blocking mode. IfNone is given, the socket is put in blocking mode.

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

バージョン 3.7 で変更:Метод більше не вмикає прапорSOCK_NONBLOCK наsocket.type.

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

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

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

Set the value of the given socket option (see the Unix manual pagesetsockopt(2)). The needed symbolic constants are defined in thismodule (SO_* etc. <socket-unix-constants>). The value can be an integer,None or abytes-like object representing a buffer. In the latercase it is up to the caller to ensure that the bytestring contains theproper bits (see the optional built-in modulestruct for a way toencode C structures as bytestrings). Whenvalue is set toNone,optlen argument is required. It's equivalent to callsetsockopt() Cfunction withoptval=NULL andoptlen=optlen.

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

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

Availability: not WASI.

socket.shutdown(how)¶

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

Availability: not WASI.

socket.share(process_id)¶

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

Availability: Windows.

Added in version 3.3.

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

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

socket.family¶

ソケットファミリー。

socket.type¶

ソケットタイプ。

socket.proto¶

ソケットプロトコル。

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

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

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

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

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

使用例¶

Here are four minimal example programs using the TCP/IP protocol: a server thatechoes all data that it receives back (servicing only one client), and a clientusing it. Note that a server must perform the sequencesocket(),bind(),listen(),accept() (possiblyrepeating theaccept() to service more than one client), while aclient only needs the sequencesocket(),connect(). Alsonote that the server does notsendall()/recv() onthe socket it is listening on but on the new socket returned byaccept().

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

# Echo server programimportsocketHOST=''# Symbolic name meaning all available interfacesPORT=50007# Arbitrary non-privileged portwithsocket.socket(socket.AF_INET,socket.SOCK_STREAM)ass:s.bind((HOST,PORT))s.listen(1)conn,addr=s.accept()withconn:print('Connected by',addr)whileTrue:data=conn.recv(1024)ifnotdata:breakconn.sendall(data)

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

The next two examples are identical to the above two, but support both IPv4 andIPv6. The server side will listen to the first address family available (itshould listen to both instead). On most of IPv6-ready systems, IPv6 will takeprecedence and the server may not accept IPv4 traffic. The client side will tryto connect to all the addresses returned as a result of the name resolution, andsends traffic to the first one connected successfully.

# Echo server programimportsocketimportsysHOST=None# Symbolic name meaning all available interfacesPORT=50007# Arbitrary non-privileged ports=Noneforresinsocket.getaddrinfo(HOST,PORT,socket.AF_UNSPEC,socket.SOCK_STREAM,0,socket.AI_PASSIVE):af,socktype,proto,canonname,sa=restry:s=socket.socket(af,socktype,proto)exceptOSErrorasmsg:s=Nonecontinuetry:s.bind(sa)s.listen(1)exceptOSErrorasmsg:s.close()s=NonecontinuebreakifsisNone:print('could not open socket')sys.exit(1)conn,addr=s.accept()withconn:print('Connected by',addr)whileTrue:data=conn.recv(1024)ifnotdata:breakconn.send(data)

# Echo client programimportsocketimportsysHOST='daring.cwi.nl'# The remote hostPORT=50007# The same port as used by the servers=Noneforresinsocket.getaddrinfo(HOST,PORT,socket.AF_UNSPEC,socket.SOCK_STREAM):af,socktype,proto,canonname,sa=restry:s=socket.socket(af,socktype,proto)exceptOSErrorasmsg:s=Nonecontinuetry:s.connect(sa)exceptOSErrorasmsg:s.close()s=NonecontinuebreakifsisNone:print('could not open socket')sys.exit(1)withs:s.sendall(b'Hello, world')data=s.recv(1024)print('Received',repr(data))

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

importsocket# the public network interfaceHOST=socket.gethostbyname(socket.gethostname())# create a raw socket and bind it to the public interfaces=socket.socket(socket.AF_INET,socket.SOCK_RAW,socket.IPPROTO_IP)s.bind((HOST,0))# Include IP headerss.setsockopt(socket.IPPROTO_IP,socket.IP_HDRINCL,1)# receive all packetss.ioctl(socket.SIO_RCVALL,socket.RCVALL_ON)# receive a packetprint(s.recvfrom(65565))# disabled promiscuous modes.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() 操作 (とそのカウンターパート) を通常通りに使用することができます。

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

importsocketimportstruct# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)can_frame_fmt="=IB3x8s"can_frame_size=struct.calcsize(can_frame_fmt)defbuild_can_frame(can_id,data):can_dlc=len(data)data=data.ljust(8,b'\x00')returnstruct.pack(can_frame_fmt,can_id,can_dlc,data)defdissect_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' interfaces=socket.socket(socket.AF_CAN,socket.SOCK_RAW,socket.CAN_RAW)s.bind(('vcan0',))whileTrue: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)exceptOSError:print('Error sending CAN frame')try:s.send(build_can_frame(0x01,b'\x01\x02\x03'))exceptOSError:print('Error sending CAN frame')

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

OSError:[Errno98]Addressalreadyinuse

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

There is asocket flag to set, in order to prevent this,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 状態にあるローカルソケットをそのタイムアウト期限が自然に切れるのを待つことなく再利用することをカーネルに伝えます。