18.1. socket

: Lib/socket.py

---

BSD (socket) UnixWindowsMacOS

API

PythonUnixPython socket() socket C read() write()

Module socketserver

Module ssl

TLS/SSL .

18.1.1.

• AF_UNIX 'surrogateescape' (PEP 383 ) Linux null bytes-like object Linux bytes-like

  3.3 : AF_UNIX UTF-8

  3.5 : bytes-like object

• AF_INET (host, port) host 'daring.cwi.nl' '100.50.200.5' IPv4 port

• AF_INET6 (host, port, flowinfo, scopeid) 4 flowinfo scopeid C struct sockaddr_in6 sin6_flowinfo sin6_scope_id socket flowinfo scopeid scopeid scope IPv6

• AF_NETLINK (pid, groups)

• Linux AF_TIPC TIPC TIPC IP (addr_type, v1, v2, v3 [, scope]) :

  • addr_type TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, TIPC_ADDR_ID 1

  • scope TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, TIPC_NODE_SCOPE 1

  • addr_type TIPC_ADDR_NAME v1 v2 ID (the port identifier) v3 0

    addr_type TIPC_ADDR_NAMESEQ v1 v2 (lower port number) v3 (upper port number)

    addr_type TIPC_ADDR_ID v1 v2 v3 0

• AF_CAN (interface,) interface 'can0' ''

• (id, unit) PF_SYSTEM SYSPROTO_CONTROL IDIDID

  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

  : Linux 2.6.38

  3.6 .

• (AF_PACKET, AF_CAN)

For IPv4 addresses, two special forms are accepted instead of a host address: the empty string represents INADDR_ANY, 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.

IPv4/v6 host PythonDNS DNSIPv4/6 host

Python 3.3 OSError (Python 3.3 socket.error )

setblocking() settimeout()

18.1.2.

socket

18.1.2.1.

exception socket.error

OSError

3.3 : PEP 3151 OSError

exception socket.herror

OSError gethostbyname_ex() gethostbyaddr() POSIX C API h_errno (h_errno, string) h_errno string hstrerror() C h_errno

3.3 : OSError

exception socket.gaierror

OSError getaddrinfo() getnameinfo() (error, string) string C gai_strerror() error error EAI_*

3.3 : OSError

exception socket.timeout

OSError settimeout() ( setdefaulttimeout() ) "timed out"

3.3 : OSError

18.1.2.2.

AF_* SOCK_* AddressFamily SocketKind IntEnum collection

3.4 .

socket.AF_UNIX

socket.AF_INET

socket.AF_INET6

() socket() AF_UNIX AF_UNIX

socket.SOCK_STREAM

socket.SOCK_DGRAM

socket.SOCK_RAW

socket.SOCK_RDM

socket.SOCK_SEQPACKET

socket() 2 ( SOCK_STREAM SOCK_DGRAM )

socket.SOCK_CLOEXEC

socket.SOCK_NONBLOCK

2 flags ()

Secure File Descriptor Handling

: Linux 2.6.27

3.2 .

SO_*

socket.SOMAXCONN

MSG_*

SOL_*

SCM_*

IPPROTO_*

IPPORT_*

INADDR_*

IP_*

IPV6_*

EAI_*

AI_*

NI_*

TCP_*

UnixIP setsockopt() getsockopt() Unix

3.6 : SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION

3.6.5 : WindowsWindows TCP_FASTOPEN ``TCP_KEEPCNT``

socket.AF_CAN

socket.PF_CAN

SOL_CAN_*

CAN_*

Linux socket

: Linux 2.6.25

3.3 .

socket.CAN_BCM

CAN_BCM_*

CANCAN_BCM(BCM)Linuxsocket

: Linux 2.6.25

3.4 .

socket.CAN_RAW_FD_FRAMES

CAN_RAW CAN FD CAN CAN FD CAN CAN FD

Linux

: Linux 3.6

3.5 .

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_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

18.1.2.3.

18.1.2.3.1.

socket object

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

AF_INET () AF_INET6 AF_UNIX AF_CAN AF_RDS SOCK_STREAM () SOCK_DGRAM SOCK_RAW SOCK_ 0 AF_CAN CAN_RAW CAN_BCM fileno fileno socket.fromfd() socket.close()

3.3 : AF_CAN, AF_RDS

3.4 : CAN_BCM

3.4 :

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

socket() AF_UNIX AF_INET

3.2 : API

3.4 :

3.5 : Windows

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

address ((host, port) ) listen TCP socket.connect() host AF_INET AF_INET6 IPv4 IPv6

timeout timeout getdefaulttimeout()

source_address (host, port) 2 host port '' 0 OS

3.2 : source_address

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

( fileno() ) fd socket() (Unixinet)

3.4 :

socket.fromshare(data)

socket.share() data

: Windows.

3.3 .

socket.SocketType

type(socket(...))

18.1.2.3.2.

socket :

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

host / port 5 host IPv4/v6 None port 'http' None host port None C API NULL

family, type, proto 0 flags AI_* 1 AI_NUMERICHOST host

5 :

(family, type, proto, canonname, sockaddr)

family, type, proto socket() AI_CANONNAME flags canonname host canonical name canonname sockaddr family (AF_INET 2 (address, port) AF_INET6 4 (address, port, flow info, scope id)) socket.connect()

example.org 80 TCP ( IPv6 ):

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

3.2 :

socket.getfqdn([name])

name name gethostbyaddr() gethostname()

socket.gethostbyname(hostname)

'100.50.200.5' IPv4IPv4 gethostbyname() API gethostbyname_ex() gethostbyname() IPv6IPv4/ v6 getaddrinfo()

socket.gethostbyname_ex(hostname)

IPv4 (hostname, aliaslist, ipaddrlist) hostname ip_address aliaslist () ipaddrlist IPv4() gethostbyname_ex() IPv6IPv4/v6 getaddrinfo()

socket.gethostname()

Python

: gethostname() getfqdn()

socket.gethostbyaddr(ip_address)

(hostname, aliaslist, ipaddrlist) hostname ip_address aliaslist () ipaddrlist IPv4() getfqdn() gethostbyaddr() IPv4/IPv6

socket.getnameinfo(sockaddr, flags)

sockaddr (host, port) flags host port

socket.getprotobyname(protocolname)

('icmp' ) socket() "raw" (SOCK_RAW) 0

socket.getservbyname(servicename[, protocolname])

'tcp' 'udp'

socket.getservbyport(port[, protocolname])

'tcp' 'udp'

socket.ntohl(x)

324

socket.ntohs(x)

162

socket.htonl(x)

324

socket.htons(x)

162

socket.inet_aton(ip_string)

IPv4('123.45.67.89' )324C struct in_addr

inet_aton() 3 ; Unix inet(3)

IPv4 OSError C inet_aton()

inet_aton() IPv6IPv4/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() IPv6IPv4/v6 inet_ntop()

3.5 : bytes-like object

socket.inet_pton(address_family, ip_string)

IP inet_pton() struct in_addr (inet_aton() ) struct in6_addr

address_family AF_INET AF_INET6 ip_string IP OSError ip_string address_family inet_pton()

: Unix ()Windows

3.4 : Windows

socket.inet_ntop(address_family, packed_ip)

IP ( bytes-like ) '7.10.0.5' '5aef:2b::8' inet_ntop() (inet_ntoa() ) struct in_addr struct in6_addr

address_family AF_INET AF_INET6 packed_ip ValueError inet_ntop() OSError

: Unix ()Windows

3.4 : Windows

3.5 : bytes-like object

socket.CMSG_LEN(length)

length CMSG recvmsg() RFC 3542 CMSG_SPACE() length OverflowError

: Unix

3.3 .

socket.CMSG_SPACE(length)

length CMSG recvmsg() CMSG_SPACE() length OverflowError

: Unix

3.3 .

socket.getdefaulttimeout()

None socket None

socket.setdefaulttimeout(timeout)

(float ) socket None settimeout()

socket.sethostname(name)

name OSError

: Unix

3.3 .

socket.if_nameindex()

(index int, name string) OSError

: Unix

3.3 .

socket.if_nametoindex(if_name)

if_name OSError

: Unix

3.3 .

socket.if_indextoname(if_index)

if_index OSError

: Unix

3.3 .

18.1.3. socket

makefile() Unix

3.2 : context manager close()

socket.accept()

bindlisten (conn, address) conn address bind

3.4 :

3.5 : InterruptedError ( PEP 475 )

socket.bind(address)

address bindbind(address )

socket.close()

makefile()

close() with

3.6 : close() OSError

close() close() shutdown()

socket.connect(address)

address (address )

socket.timeout () InterruptedError

3.5 : InterruptedError  ( PEP 475 )

socket.connect_ex(address)

connect(address) C connect() ("host not found,") 0 errno

socket.detach()

3.2 .

socket.dup()

3.4 :

socket.fileno()

-1 select.select()

Windows (os.fdopen() ) Unix

socket.get_inheritable()

True False

3.4 .

socket.getpeername()

IPv4/v6 address ()

socket.getsockname()

IPv4/v6(address )

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

(Unix getsockopt(2) ) SO_* buflen buflen buflen struct

socket.gettimeout()

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 )

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.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

: Unix

3.3 .

3.5 : InterruptedError ( PEP 475 )

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

recvmsg() buffers (: bytearray ) (sysconf() SC_IOV_MAX) ancbufsize flags recvmsg()

4 (nbytes, ancdata, msg_flags, address) nbytes ancdatamsg_flagsaddress recvmsg()

:

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

: Unix

3.3 .

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

buffer (nbytes, address) nbytes address flags (:0) Unix recv(2) (address )

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

nbytes buffer nbytes (0) buffer flags (:0) Unix recv(2)

socket.send(bytes[, flags])

flags recv() HOWTO

3.5 : InterruptedError ( PEP 475 )

socket.sendall(bytes[, flags])

flags recv() send() bytes None

3.5 :

3.5 : InterruptedError ( PEP 475 )

socket.sendto(bytes, address)

socket.sendto(bytes, flags, address)

address flags recv() (address )

3.5 : InterruptedError ( PEP 475 )

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

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

: Unix

3.3 .

3.5 : InterruptedError ( PEP 475 )

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

sendmsg() AF_ALG AF_ALG IVAEAD

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

socket.settimeout(value)

value float None value timeout None

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

18.1.4.

1 setdefaulttimeout()

• select
• timeout

fileno()

18.1.4.1. connect

connect() settimeout() connect() create_connection() Python

18.1.4.2. accept

getdefaulttimeout() None accept() None

• accept()  
• accept()

18.1.5.

TCP/IP () socket() bind() listen() accept() ( accept() ) socket() connect() sendall() / recv() listen accept()

IPv4

# Echo server program
import socket

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

# Echo client program
import socket

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

IPv4 IPv6 IPv4/v6 listen IPv6 IPv6 IPv4

# Echo server program
import socket
import sys

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

# Echo client program
import socket
import sys

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

Windows raw socket :

import socket

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

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

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

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

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

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

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 Programmers Manual, Supplementary Documents 1 (PS1:7 PS1:8)Unix WindowsWinSock ( WinSock2) IPv6 API RFC 3493 "Basic Socket Interface Extensions for IPv6"