`socket` — 저수준 네트워킹 인터페이스

소스 코드: Lib/socket.py

이 모듈은 BSD socket 인터페이스에 접근할 수 있게 해 줘요. 모든 현대 Unix 시스템, Windows, MacOS, 그리고 아마 추가 플랫폼에서 사용할 수 있어요.

참고: 운영 체제의 socket API를 호출하기 때문에 일부 동작은 플랫폼에 따라 달라질 수 있어요.

가용성: WASI 아님. 이 모듈은 WebAssembly 플랫폼에서는 동작하지 않거나 사용할 수 없어요.

Python 인터페이스는 Unix 시스템 호출과 소켓용 라이브러리 인터페이스를 Python의 객체 지향 스타일로 직역한 것이에요. socket() 함수는 다양한 socket 시스템 호출을 구현한 메서드들을 가진 socket object 를 반환해요. 매개변수 형식은 C 인터페이스보다 조금 더 고수준이에요. Python 파일의 read()·write() 연산처럼, 수신 연산의 버퍼 할당은 자동이고 송신 연산의 버퍼 길이는 암묵적이에요.

참고:

모듈 socketserver: 네트워크 서버 작성이 쉬워지는 클래스들.

모듈 ssl: socket 객체를 위한 TLS/SSL 래퍼.

출처: Python 표준 라이브러리

본문

소켓 패밀리 (Socket families)

시스템과 빌드 옵션에 따라 이 모듈은 다양한 소켓 패밀리를 지원해요.

특정 socket 객체가 요구하는 주소 형식은 socket 객체를 만들 때 지정한 주소 패밀리에 따라 자동으로 선택돼요. 소켓 주소는 다음과 같이 표현돼요.

파일 시스템 노드에 바인딩된 AF_UNIX 소켓의 주소는 파일 시스템 인코딩과 'surrogateescape' 오류 핸들러를 사용하는 문자열로 표현돼요(PEP 383 참고). Linux의 추상 네임스페이스(abstract namespace)에 있는 주소는 맨 앞에 null 바이트가 있는 bytes-like 객체로 반환돼요. 이 네임스페이스의 소켓은 일반 파일 시스템 소켓과 통신할 수 있으므로, Linux에서 실행하도록 만든 프로그램은 두 종류의 주소를 모두 다뤄야 할 수 있어요. 인자로 전달할 때는 두 종류의 주소 모두 문자열 또는 bytes-like 객체를 쓸 수 있어요.
- 3.3 버전 변경: 이전에는 AF_UNIX 소켓 경로가 UTF-8 인코딩을 사용한다고 가정했어요.
- 3.5 버전 변경: 쓰기 가능한 bytes-like 객체가 이제 허용돼요.
AF_INET 주소 패밀리에는 (host, port) 쌍이 쓰여요. host 는 'daring.cwi.nl' 같은 인터넷 도메인 표기의 호스트 이름이거나 '100.50.200.5' 같은 IPv4 주소를 나타내는 문자열이고, port 는 정수예요.
IPv4 주소의 경우 호스트 주소 대신 두 가지 특수 형식이 허용돼요. '' 는 모든 인터페이스에 바인딩하는 데 쓰는 INADDR_ANY 를 나타내고, '<broadcast>' 문자열은 INADDR_BROADCAST 를 나타내요. 이 동작은 IPv6와 호환되지 않으므로, Python 프로그램에서 IPv6를 지원하려면 이것들을 피하는 게 좋아요.
AF_INET6 주소 패밀리에는 4-튜플 (host, port, flowinfo, scope_id) 가 쓰여요. flowinfo 와 scope_id 는 C의 struct sockaddr_in6 에 있는 sin6_flowinfo 와 sin6_scope_id 멤버를 나타내요. socket 모듈 메서드의 경우 하위 호환성을 위해 flowinfo 와 scope_id 는 생략할 수 있어요. 다만 scope_id 를 생략하면 스코프가 있는 IPv6 주소를 다룰 때 문제가 될 수 있어요.
- 3.7 버전 변경: 멀티캐스트 주소(scope_id 가 의미 있는)의 address 는 %scope_id(또는 zone id) 부분을 포함하지 않을 수 있어요. 이 정보는 불필요하며 안전하게 생략할 수 있어요(권장).
AF_NETLINK 소켓은 쌍 (pid, groups) 으로 표현돼요.
Linux 전용 TIPC 지원은 AF_TIPC 주소 패밀리로 사용할 수 있어요. TIPC는 클러스터형 컴퓨터 환경에서 쓰도록 설계된 개방형 비-IP 기반 네트워킹 프로토콜이에요. 주소는 튜플로 표현되고, 필드는 주소 유형에 따라 달라져요. 일반적인 튜플 형식은 (addr_type, v1, v2, v3 [, scope]) 이에요.
- addr_type 은 TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, TIPC_ADDR_ID 중 하나.
- scope 는 TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, TIPC_NODE_SCOPE 중 하나.
- addr_type 이 TIPC_ADDR_NAME 이면 v1 은 서버 유형, v2 는 포트 식별자, v3 는 0이어야 해요.
- addr_type 이 TIPC_ADDR_NAMESEQ 이면 v1 은 서버 유형, v2 는 하한 포트 번호, v3 는 상한 포트 번호.
- addr_type 이 TIPC_ADDR_ID 이면 v1 은 노드, v2 는 참조번호, v3 는 0으로 설정.
AF_CAN 주소 패밀리에는 튜플 (interface,) 이 쓰여요. interface 는 'can0' 같은 네트워크 인터페이스 이름을 나타내는 문자열이에요. 네트워크 인터페이스 이름 '' 을 사용하면 이 패밀리의 모든 네트워크 인터페이스에서 패킷을 받을 수 있어요.
CAN_ISOTP 프로토콜은 튜플 (interface, rx_addr, tx_addr) 이 필요해요. 여기서 추가 매개변수 둘 다 (표준 또는 확장) CAN 식별자를 나타내는 unsigned long 정수예요.
CAN_J1939 프로토콜은 튜플 (interface, name, pgn, addr) 이 필요해요. 추가 매개변수는 ECU 이름을 나타내는 64비트 부호 없는 정수, Parameter Group Number(PGN)를 나타내는 32비트 부호 없는 정수, 주소를 나타내는 8비트 정수예요.
PF_SYSTEM 패밀리의 SYSPROTO_CONTROL 프로토콜에는 문자열 또는 튜플 (id, unit) 이 쓰여요. 문자열은 동적으로 할당된 ID를 쓰는 커널 컨트롤의 이름이에요. 커널 컨트롤의 ID와 유닛 번호를 알거나 등록된 ID를 쓸 때는 튜플을 쓸 수 있어요.
- 3.3 버전에서 추가.
AF_BLUETOOTH 는 다음 프로토콜과 주소 형식을 지원해요.
- BTPROTO_L2CAP 은 튜플 (bdaddr, psm[, cid[, bdaddr_type]]) 을 받아요. bdaddr 은 Bluetooth 주소를 지정하는 문자열, psm 은 Protocol/Service Multiplexer를 지정하는 정수, cid 는 Channel Identifier를 지정하는 선택적 정수(주지 않으면 기본 0), bdaddr_type 은 주소 유형을 지정하는 선택적 정수로 BDADDR_BREDR(기본), BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM 중 하나.
  - 3.14 버전 변경: cid 와 bdaddr_type 필드가 추가됐어요.
- BTPROTO_RFCOMM 은 (bdaddr, channel) 을 받아요. bdaddr 는 문자열인 Bluetooth 주소, channel 은 정수예요.
- BTPROTO_HCI 는 OS에 따라 형식을 받아요.
  - Linux에서는 정수 device_id 또는 튜플 (device_id, [channel]) 을 받아요. device_id 는 Bluetooth 장치 번호, channel 은 HCI 채널을 지정하는 선택적 정수(기본 HCI_CHANNEL_RAW).
  - FreeBSD, NetBSD, DragonFly BSD에서는 문자열인 bdaddr 을 받아요.
  - 3.2 버전 변경: NetBSD와 DragonFlyBSD 지원이 추가됐어요. 3.13.3 버전 변경: FreeBSD 지원이 추가됐어요. 3.14 버전 변경: channel 필드가 추가됐고, 튜플에 담기지 않은 device_id 도 이제 허용돼요.
- BTPROTO_SCO 는 문자열 또는 bytes 객체인 bdaddr 을 받아요. (예: '12:23:34:45:56:67' 또는 b'12:23:34:45:56:67').
  - 3.14 버전 변경: FreeBSD 지원이 추가됐어요.
AF_ALG 는 Linux 전용의 커널 암호화를 위한 소켓 기반 인터페이스예요. 알고리즘 소켓은 2~4개 요소의 튜플 (type, name [, feat [, mask]]) 로 구성돼요.
- type 은 aead, hash, skcipher, rng 같은 문자열 알고리즘 유형.
- name 은 sha256, hmac(sha256), cbc(aes), drbg_nopr_ctr_aes256 같은 문자열 알고리즘 이름과 연산 모드.
- feat 와 mask 는 부호 없는 32비트 정수.
- 가용성: Linux >= 2.6.38. 일부 알고리즘 유형은 더 최신 커널이 필요해요. 3.6 버전에서 추가.
AF_VSOCK 은 가상 머신과 그 호스트 간의 통신을 허용해요. 소켓은 (CID, port) 튜플로 표현되고, 컨텍스트 ID(CID)와 포트는 정수예요.
- 가용성: Linux >= 3.9. vsock(7) 참고. 3.7 버전에서 추가.
AF_PACKET 은 네트워크 장치에 직접 접근하는 저수준 인터페이스예요. 주소는 튜플 (ifname, proto[, pkttype[, hatype[, addr]]]) 로 표현돼요.
- ifname — 장치 이름을 지정하는 문자열.
- proto — 이더넷 프로토콜 번호. 모든 프로토콜을 캡처하려면 ETH_P_ALL, ETHERTYPE_* 상수 중 하나, 또는 다른 이더넷 프로토콜 번호.
- pkttype — 패킷 유형을 지정하는 선택적 정수: PACKET_HOST(기본, 로컬 호스트로 주소가 지정된 패킷), PACKET_BROADCAST(물리 계층 브로드캐스트 패킷), PACKET_MULTICAST(물리 계층 멀티캐스트 주소로 보낸 패킷), PACKET_OTHERHOST(promiscuous 모드 장치 드라이버가 잡은 다른 호스트로 가는 패킷), PACKET_OUTGOING(패킷 소켓으로 루프백된 로컬 호스트 발신 패킷).
- hatype — ARP 하드웨어 주소 유형을 지정하는 선택적 정수.
- addr — 하드웨어 물리 주소를 지정하는 선택적 bytes-like 객체. 해석은 장치에 따라 달라요.
- 가용성: Linux >= 2.2.
AF_QIPCRTR 은 Qualcomm 플랫폼의 코프로세서에서 실행되는 서비스와 통신하기 위한 Linux 전용 소켓 기반 인터페이스예요. 주소 패밀리는 (node, port) 튜플로 표현되고 node 와 port 는 음이 아닌 정수예요.
- 가용성: Linux >= 4.7. 3.8 버전에서 추가.
IPPROTO_UDPLITE 는 패킷의 어느 부분이 체크섬으로 덮이는지 지정할 수 있게 해 주는 UDP의 변형이에요. 변경할 수 있는 소켓 옵션 두 개를 추가해요. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) 는 발신 패킷 중 체크섬이 덮는 부분을 바꾸고, self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) 는 데이터를 너무 적게 덮는 패킷을 걸러내요. 두 경우 모두 length 는 range(8, 2**16, 8) 안에 있어야 해요.
- 이런 소켓은 IPv4에서는 socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE), IPv6에서는 socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) 로 만들어야 해요.
- 가용성: Linux >= 2.6.20, FreeBSD >= 10.1. 3.9 버전에서 추가.
AF_HYPERV 는 Hyper-V 호스트와 게스트와 통신하기 위한 Windows 전용 소켓 기반 인터페이스예요. 주소 패밀리는 (vm_id, service_id) 튜플로 표현되고 vm_id 와 service_id 는 UUID 문자열이에요.
- vm_id 는 가상 머신 식별자이거나, 대상이 특정 가상 머신이 아니면 알려진 VMID 값들의 집합이에요. socket 에 정의된 알려진 VMID 상수: HV_GUID_ZERO, HV_GUID_BROADCAST, HV_GUID_WILDCARD(자신에 바인딩하고 모든 파티션의 연결을 받는 데 사용), HV_GUID_CHILDREN(자신에 바인딩하고 자식 파티션의 연결을 받는 데 사용), HV_GUID_LOOPBACK(자신을 대상으로 쓰임), HV_GUID_PARENT(바인딩으로 쓰이면 부모 파티션의 연결을 받고, 주소 대상으로 쓰이면 부모 파티션에 연결).
- service_id 는 등록된 서비스의 서비스 식별자예요.
- 3.12 버전에서 추가.

IPv4/v6 소켓 주소의 host 부분에 호스트 이름을 쓰면 프로그램이 비결정적 동작을 보일 수 있어요. Python은 DNS 해석이 반환한 첫 번째 주소를 쓰기 때문이에요. 소켓 주소는 DNS 해석 결과와/또는 호스트 구성에 따라 실제 IPv4/v6 주소로 다르게 해석돼요. 결정적 동작을 원하면 host 부분에 숫자 주소를 사용하세요.

모든 오류는 예외를 발생시켜요. 잘못된 인자 유형과 메모리 부족 조건에 대한 일반적인 예외가 발생할 수 있어요. 소켓이나 주소 의미와 관련된 오류는 OSError 또는 그 서브클래스를 발생시켜요.

비블로킹 모드는 setblocking() 으로 지원돼요. 타임아웃에 기반한 일반화는 settimeout() 으로 지원돼요.

모듈 내용

socket 모듈은 다음 요소들을 내보내요.

예외 (Exceptions)

예외 socket.error

OSError 의 비권장(더 이상 쓰이지 않는) 별칭이에요.

3.3 버전 변경: PEP 3151 에 따라 이 클래스가 OSError 의 별칭이 됐어요.

예외 socket.herror

OSError 의 서브클래스로, 주소 관련 오류에 대해 발생해요. 즉 gethostbyname_ex() 와 gethostbyaddr() 를 포함해 POSIX C API에서 h_errno 를 사용하는 함수들에 대해 발생해요. 수반되는 값은 라이브러리 호출이 반환한 오류를 나타내는 쌍 (h_errno, string) 이에요. h_errno 는 숫자 값이고, string 은 hstrerror() C 함수가 반환한 것처럼 h_errno 의 설명을 나타내요.

3.3 버전 변경: 이 클래스가 OSError 의 서브클래스가 됐어요.

예외 socket.gaierror

OSError 의 서브클래스로, 주소 관련 오류에 대해 getaddrinfo() 와 getnameinfo() 가 발생시켜요. 수반되는 값은 라이브러리 호출이 반환한 오류를 나타내는 쌍 (error, string) 이에요. string 은 gai_strerror() C 함수가 반환한 것처럼 error 의 설명을 나타내요. 숫자 error 값은 이 모듈에 정의된 EAI_* 상수 중 하나와 일치해요.

3.3 버전 변경: 이 클래스가 OSError 의 서브클래스가 됐어요.

예외 socket.timeout

TimeoutError 의 비권장 별칭이에요.

OSError 의 서브클래스로, 이전에 settimeout()(또는 setdefaulttimeout() 을 통한 암묵적)을 호출해 타임아웃을 활성화한 소켓에서 타임아웃이 발생했을 때 발생해요. 수반되는 값은 현재 항상 "timed out"인 문자열이에요.

3.3 버전 변경: 이 클래스가 OSError 의 서브클래스가 됐어요.

3.10 버전 변경: 이 클래스가 TimeoutError 의 별칭이 됐어요.

상수 (Constants)

AF_* 및 SOCK_* 상수는 이제 AddressFamily 와 SocketKind IntEnum 컬렉션이에요.

3.4 버전에서 추가.

socket.AF_UNIX, socket.AF_INET, socket.AF_INET6

socket() 의 첫 번째 인자로 쓰이는 주소(및 프로토콜) 패밀리를 나타내요. AF_UNIX 상수가 정의돼 있지 않으면 그 프로토콜은 지원되지 않는 것이에요. 시스템에 따라 더 많은 상수가 사용 가능할 수 있어요.

socket.AF_UNSPEC

AF_UNSPEC 은 getaddrinfo() 가 사용할 수 있는 모든 주소 패밀리(IPv4, IPv6 또는 그 외)의 소켓 주소를 반환해야 함을 뜻해요.

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

socket() 의 두 번째 인자로 쓰이는 소켓 유형을 나타내요. 시스템에 따라 더 많은 상수가 사용 가능할 수 있어요.(일반적으로 유용한 것은 SOCK_STREAM 과 SOCK_DGRAM 뿐인 것 같아요.)

socket.SOCK_CLOEXEC, socket.SOCK_NONBLOCK

이 두 상수는 정의되어 있다면 소켓 유형과 결합해 플래그를 원자적으로 설정할 수 있게 해 줘요(경쟁 조건과 별도의 호출 필요성을 피함).

가용성: Linux >= 2.6.27. 3.2 버전에서 추가. 자세한 설명은 Secure File Descriptor Handling 참고.

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

이런 형태의 많은 상수들(소켓 및/또는 IP 프로토콜에 관한 Unix 문서에 설명됨)도 socket 모듈에 정의돼 있어요. 일반적으로 socket 객체의 setsockopt() 와 getsockopt() 메서드 인자에 쓰여요. 대부분의 경우 Unix 헤더 파일에 정의된 기호만 정의되고, 일부 기호에는 기본값이 제공돼요.

추가된 상수들에 대한 버전 변경 사항:

3.6: SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION 추가.
3.6.5: Windows에서 가능할 때 TCP_FASTOPEN, TCP_KEEPCNT 지원 추가.
3.7: TCP_NOTSENT_LOWAT 추가. Windows에서 가능할 때 TCP_KEEPIDLE, TCP_KEEPINTVL 지원 추가.
3.10: IP_RECVTOS 추가. TCP_KEEPALIVE 추가(MacOS에서는 Linux의 TCP_KEEPIDLE 과 같은 방식으로 사용).
3.11: TCP_CONNECTION_INFO 추가(MacOS에서는 Linux·BSD의 TCP_INFO 와 같은 방식으로 사용).
3.12: SO_RTABLE, SO_USER_COOKIE 추가(각각 OpenBSD, FreeBSD에서 Linux의 SO_MARK 와 같은 방식). Linux의 누락된 TCP 소켓 옵션(TCP_MD5SIG, TCP_THIN_LINEAR_TIMEOUTS, TCP_THIN_DUPACK, TCP_REPAIR, TCP_REPAIR_QUEUE, TCP_QUEUE_SEQ, TCP_REPAIR_OPTIONS, TCP_TIMESTAMP, TCP_CC_INFO, TCP_SAVE_SYN, TCP_SAVED_SYN, TCP_REPAIR_WINDOW, TCP_FASTOPEN_CONNECT, TCP_ULP, TCP_MD5SIG_EXT, TCP_FASTOPEN_KEY, TCP_FASTOPEN_NO_COOKIE, TCP_ZEROCOPY_RECEIVE, TCP_INQ, TCP_TX_DELAY) 추가. IP_PKTINFO, IP_UNBLOCK_SOURCE, IP_BLOCK_SOURCE, IP_ADD_SOURCE_MEMBERSHIP, IP_DROP_SOURCE_MEMBERSHIP 추가.
3.13: SO_BINDTOIFINDEX 추가(Linux에서 SO_BINDTODEVICE 와 같은 방식이지만 인터페이스 이름 대신 인덱스 사용).
3.14: Linux에 누락된 IP_FREEBIND, IP_RECVERR, IPV6_RECVERR, IP_RECVTTL, IP_RECVORIGDSTADDR 추가.
3.14: Windows에서 가능할 때 TCP_QUICKACK 지원 추가.

socket.AF_CAN, socket.PF_CAN, SOL_CAN_*, CAN_*

이런 형태의 많은 상수들(Linux 문서에 설명됨)도 socket 모듈에 정의돼 있어요.

가용성: Linux >= 2.6.25, NetBSD >= 8. 3.3 버전에서 추가.

3.11 버전 변경: NetBSD 지원이 추가됐어요. 3.14 버전 변경: Linux의 누락된 CAN_RAW_ERR_FILTER 복원.

socket.CAN_BCM, CAN_BCM_*

CAN 프로토콜 패밀리에서 CAN_BCM은 브로드캐스트 관리자(BCM) 프로토콜이에요. Linux 문서에 설명된 브로드캐스트 관리자 상수들도 socket 모듈에 정의돼 있어요.

가용성: Linux >= 2.6.25.

참고: CAN_BCM_CAN_FD_FRAME 플래그는 Linux >= 4.8에서만 사용할 수 있어요.

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_RAW_JOIN_FILTERS

적용된 CAN 필터를 결합해, 주어진 모든 CAN 필터와 일치하는 CAN 프레임만 사용자 공간으로 전달해요. (Linux 문서에 설명된 상수.)

가용성: Linux >= 4.1. 3.9 버전에서 추가.

socket.CAN_ISOTP

CAN 프로토콜 패밀리에서 CAN_ISOTP은 ISO-TP(ISO 15765-2) 프로토콜이에요. Linux 문서에 설명된 ISO-TP 상수들.

가용성: Linux >= 2.6.25. 3.7 버전에서 추가.

socket.CAN_J1939

CAN 프로토콜 패밀리에서 CAN_J1939은 SAE J1939 프로토콜이에요. Linux 문서에 설명된 J1939 상수들.

가용성: Linux >= 5.4. 3.9 버전에서 추가.

socket.AF_DIVERT, socket.PF_DIVERT

FreeBSD divert(4) 매뉴얼 페이지에 문서화된 이 두 상수도 socket 모듈에 정의돼 있어요.

가용성: FreeBSD >= 14.0. 3.12 버전에서 추가.

socket.AF_PACKET, socket.PF_PACKET, PACKET_*

이런 형태의 많은 상수들(Linux 문서에 설명됨)도 socket 모듈에 정의돼 있어요.

가용성: Linux >= 2.2.

socket.ETH_P_ALL

ETH_P_ALL 은 AF_PACKET 패밀리의 socket 생성자에서 proto 로 사용해 프로토콜과 무관하게 모든 패킷을 캡처할 수 있어요.

가용성: Linux. 3.12 버전에서 추가. 자세한 내용은 * packet(7) * manpage 참고.

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()용 상수들. socket 객체의 ioctl() 메서드 인자로 쓰여요.

3.6 버전 변경: SIO_LOOPBACK_FAST_PATH 가 추가됐어요.

TIPC_*

C socket API가 내보내는 것과 일치하는 TIPC 관련 상수들. 자세한 내용은 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*

Linux 호스트/게스트 통신용 상수들.

가용성: Linux >= 4.8. 3.7 버전에서 추가.

socket.AF_LINK

가용성: BSD, macOS. 3.4 버전에서 추가.

socket.has_ipv6

이 플랫폼에서 IPv6가 지원되는지 나타내는 boolean 값을 담은 상수예요.

socket.AF_BLUETOOTH, socket.BTPROTO_L2CAP, socket.BTPROTO_RFCOMM, socket.BTPROTO_HCI, socket.BTPROTO_SCO

Bluetooth 주소와 함께 쓰는 정수 상수들.

socket.BDADDR_ANY, socket.BDADDR_LOCAL

특별한 의미를 가진 Bluetooth 주소를 담은 문자열 상수들. 예를 들어 BTPROTO_RFCOMM 으로 바인딩 소켓을 지정할 때 BDADDR_ANY 를 사용해 임의의 주소를 나타낼 수 있어요.

socket.BDADDR_BREDR, socket.BDADDR_LE_PUBLIC, socket.BDADDR_LE_RANDOM

BTPROTO_L2CAP 소켓을 바인딩하거나 연결할 때 Bluetooth 주소 유형을 설명하는 상수들.

가용성: Linux, FreeBSD. 3.14 버전에서 추가.

socket.SOL_RFCOMM, socket.SOL_L2CAP, socket.SOL_HCI, socket.SOL_SCO, socket.SOL_BLUETOOTH

Bluetooth socket 객체의 setsockopt() 와 getsockopt() 메서드의 level 인자에 쓰여요.

SOL_BLUETOOTH 는 Linux에서만 사용할 수 있어요. 다른 상수들은 해당 프로토콜이 지원되면 사용할 수 있어요.

SO_L2CAP_*, socket.L2CAP_LM, L2CAP_LM_*, SO_RFCOMM_*, RFCOMM_LM_*, SO_SCO_*, SO_BTH_*, BT_*

Bluetooth socket 객체의 setsockopt() 와 getsockopt() 메서드의 옵션 이름과 값 인자에 쓰여요.

BT_* 와 L2CAP_LM 은 Linux에서만 사용할 수 있어요. SO_BTH_* 는 Windows에서만 사용할 수 있어요. 다른 상수들은 Linux와 다양한 BSD 플랫폼에서 사용할 수 있을 수 있어요.

3.14 버전에서 추가.

socket.HCI_FILTER, socket.HCI_TIME_STAMP, socket.HCI_DATA_DIR, socket.SO_HCI_EVT_FILTER, socket.SO_HCI_PKT_FILTER

BTPROTO_HCI 와 함께 쓰는 옵션 이름들. 옵션 값의 가용성과 형식은 플랫폼에 따라 달라요.

3.14 버전 변경: NetBSD와 DragonFly BSD에 SO_HCI_EVT_FILTER 와 SO_HCI_PKT_FILTER 가 추가됐고, FreeBSD·NetBSD·DragonFly BSD에 HCI_DATA_DIR 이 추가됐어요.

socket.HCI_DEV_NONE

단일 Bluetooth 어댑터에 특정되지 않는 HCI 소켓을 만드는 데 쓰는 device_id 값.

가용성: Linux. 3.14 버전에서 추가.

socket.HCI_CHANNEL_RAW, socket.HCI_CHANNEL_USER, socket.HCI_CHANNEL_MONITOR, socket.HCI_CHANNEL_CONTROL, socket.HCI_CHANNEL_LOGGING

BTPROTO_HCI 주소의 channel 필드에 대한 가능한 값들.

가용성: Linux. 3.14 버전에서 추가.

socket.AF_QIPCRTR

Qualcomm의 IPC 라우터 프로토콜 상수로, 원격 프로세서를 제공하는 서비스와 통신하는 데 사용돼요.

가용성: Linux >= 4.7.

socket.SCM_CREDS2, socket.LOCAL_CREDS, socket.LOCAL_CREDS_PERSISTENT

LOCAL_CREDS와 LOCAL_CREDS_PERSISTENT는 SOCK_DGRAM, SOCK_STREAM 소켓에서 사용할 수 있고, Linux/DragonFlyBSD의 SO_PASSCRED와 동등해요. LOCAL_CREDS는 첫 읽기에 자격 증명을 보내고, LOCAL_CREDS_PERSISTENT는 각 읽기마다 보내요. 후자의 메시지 유형에는 SCM_CREDS2를 사용해야 해요.

3.11 버전에서 추가. 가용성: FreeBSD.

socket.SO_INCOMING_CPU

CPU 지역성(locality)을 최적화하는 상수로, SO_REUSEPORT 와 함께 사용돼요.

3.11 버전에서 추가. 가용성: Linux >= 3.9.

socket.SO_REUSEPORT_LB

부하 분산이 있는 중복 주소·포트 바인딩을 활성화하는 상수.

3.14 버전에서 추가. 가용성: FreeBSD >= 12.0.

socket.AF_HYPERV, socket.HV_PROTOCOL_RAW, socket.HVSOCKET_CONNECT_TIMEOUT, socket.HVSOCKET_CONNECT_TIMEOUT_MAX, socket.HVSOCKET_CONNECTED_SUSPEND, socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU, socket.HV_GUID_ZERO, socket.HV_GUID_WILDCARD, socket.HV_GUID_BROADCAST, socket.HV_GUID_CHILDREN, socket.HV_GUID_LOOPBACK, socket.HV_GUID_PARENT

Windows Hyper-V 호스트/게스트 통신용 상수들.

가용성: Windows. 3.12 버전에서 추가.

socket.ETHERTYPE_ARP, socket.ETHERTYPE_IP, socket.ETHERTYPE_IPV6, socket.ETHERTYPE_VLAN

IEEE 802.3 프로토콜 번호 상수들.

가용성: Linux, FreeBSD, macOS. 3.12 버전에서 추가.

socket.SHUT_RD, socket.SHUT_WR, socket.SHUT_RDWR

socket 객체의 shutdown() 메서드가 사용하는 상수들.

가용성: WASI 아님.

함수 (Functions)

소켓 만들기

다음 함수들은 모두 socket object 를 만들어요.

socket 클래스 생성자는 새 소켓을 직접 만들어요. 매개변수와 전체 설명은 Socket Objects 참고.

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

주어진 주소 패밀리, 소켓 유형, 프로토콜 번호를 사용해 연결된 socket 객체 한 쌍을 만들어요. 주소 패밀리, 소켓 유형, 프로토콜 번호는 socket() 함수와 같아요. 기본 패밀리는 플랫폼에 AF_UNIX 가 정의돼 있으면 AF_UNIX 이고, 그렇지 않으면 AF_INET 이에요.

새로 만들어진 소켓은 non-inheritable(상속 불가)이에요.

3.2 버전 변경: 반환된 socket 객체는 이제 일부가 아닌 전체 socket API를 지원해요.

3.4 버전 변경: 반환된 소켓이 이제 non-inheritable이에요.

3.5 버전 변경: Windows 지원이 추가됐어요.

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

인터넷 address(2-튜플 (host, port))에서 수신 대기하는 TCP 서비스에 연결하고 socket 객체를 반환해요. socket.connect() 보다 고수준 함수예요. host 가 숫자가 아닌 호스트 이름이면 AF_INET 과 AF_INET6 모두에 대해 해석을 시도하고, 연결이 성공할 때까지 가능한 모든 주소를 차례로 연결하려 시도해요. 덕분에 IPv4와 IPv6 모두에 호환되는 클라이언트를 쉽게 작성할 수 있어요.

선택적 timeout 매개변수를 전달하면 연결을 시도하기 전에 소켓 인스턴스에 타임아웃을 설정해요. timeout 을 주지 않으면 getdefaulttimeout() 이 반환한 전역 기본 타임아웃 설정이 사용돼요.

source_address 가 주어지면 소켓이 연결 전에 소스 주소로 바인딩할 2-튜플 (host, port) 이어야 해요. host나 port가 각각 '' 나 0이면 OS 기본 동작이 사용돼요.

연결을 만들 수 없으면 예외가 발생해요. 기본적으로 목록의 마지막 주소에서 난 예외예요. all_errors 가 True 이면 모든 시도의 오류를 담은 ExceptionGroup 이에요.

3.2 버전 변경: source_address 추가.

3.11 버전 변경: all_errors 추가.

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

address(2-튜플 (host, port) )에 바인딩된 TCP 소켓을 만들고 socket 객체를 반환하는 편의 함수예요.

family 는 AF_INET 또는 AF_INET6 이어야 해요. backlog 는 socket.listen() 으로 전달되는 큐 크기예요. 지정하지 않으면 합리적인 기본값이 선택돼요. reuse_port 는 SO_REUSEPORT 소켓 옵션을 설정할지 여부를 나타내요.

dualstack_ipv6 가 true이고 family 가 AF_INET6 이며 플랫폼이 지원하면 소켓이 IPv4와 IPv6 연결을 모두 받아들일 수 있어요. 그렇지 않으면 ValueError 를 발생시켜요. 대부분의 POSIX 플랫폼과 Windows가 이 기능을 지원할 거예요. 이 기능이 활성화되면 IPv4 연결이 발생할 때 socket.getpeername() 이 반환하는 주소는 IPv4-mapped IPv6 주소로 표현된 IPv6 주소가 돼요. dualstack_ipv6 가 false이면 기본으로 활성화하는 플랫폼(예: Linux)에서 이 기능을 명시적으로 비활성화해요. 이 매개변수는 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)

참고: POSIX 플랫폼에서는 같은 address 에 바인딩됐다가 TIME_WAIT 상태에 남아 있던 이전 소켓을 즉시 재사용하기 위해 SO_REUSEADDR 소켓 옵션이 설정돼요.

3.8 버전에서 추가.

socket.has_dualstack_ipv6()

플랫폼이 IPv4와 IPv6 연결을 모두 처리할 수 있는 TCP 소켓 생성을 지원하면 True 를 반환해요.

3.8 버전에서 추가.

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

파일 디스크립터 fd(파일 객체의 fileno() 메서드가 반환한 정수)를 중복(duplicate)해서 그 결과로 socket 객체를 만들어요. 주소 패밀리, 소켓 유형, 프로토콜 번호는 socket() 함수와 같아요. 파일 디스크립터는 소켓을 가리켜야 하지만, 이것은 검사되지 않아요. 파일 디스크립터가 유효하지 않으면 객체에 대한 이후 연산이 실패할 수 있어요. 이 함수는 거의 필요하지 않지만, 프로그램에 표준 입력이나 출력으로 전달된 소켓(예: Unix inet 데몬이 시작한 서버)의 소켓 옵션을 얻거나 설정하는 데 쓸 수 있어요. 소켓은 블로킹 모드에 있다고 가정돼요.

새로 만들어진 소켓은 non-inheritable이에요.

3.4 버전 변경: 반환된 소켓이 이제 non-inheritable이에요.

socket.fromshare(*data*)

socket.share() 메서드에서 얻은 데이터로 소켓을 인스턴스화해요. 소켓은 블로킹 모드에 있다고 가정돼요.

가용성: Windows. 3.3 버전에서 추가.

기타 함수

socket 모듈은 다양한 네트워크 관련 서비스도 제공해요.

socket.close(*fd*)

소켓 파일 디스크립터를 닫아요. os.close() 와 비슷하지만 소켓용이에요. 일부 플랫폼(특히 Windows)에서는 os.close() 가 소켓 파일 디스크립터에서 동작하지 않아요.

3.7 버전에서 추가.

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

이 함수는 기반 시스템의 C 함수 getaddrinfo 를 감싸요.

host/port 인자를, 그 서비스에 연결하는 소켓을 만들기 위한 모든 필요한 인자를 담은 5-튜플들의 시퀀스로 변환해요. host 는 도메인 이름, IPv4/v6 주소의 문자열 표현 또는 None 이에요. port 는 'http' 같은 문자열 서비스 이름, 숫자 포트 번호 또는 None 이에요. host 와 port 의 값으로 None 을 전달하면 기반 C API에 NULL 을 전달할 수 있어요.

family, type, proto 인자는 옵션을 제공하고 반환되는 주소 목록을 제한하기 위해 선택적으로 지정할 수 있어요. 결과를 제한하지 않으려면 기본값(AF_UNSPEC, 0, 0)을 전달하세요. 자세한 내용은 아래 참고를 보세요.

flags 인자는 AI_* 상수 중 하나 또는 여러 개일 수 있고, 결과가 어떻게 계산되고 반환되는지에 영향을 줘요. 예를 들어 AI_NUMERICHOST 는 도메인 이름 해석을 비활성화하고, host 가 도메인 이름이면 오류를 발생시켜요.

이 함수는 다음 구조의 5-튜플 목록을 반환해요.

(family, type, proto, canonname, sockaddr)

이 튜플들에서 family, type, proto 는 모두 정수이고 socket() 함수에 전달하라는 뜻이에요. canonname 은 AI_CANONNAME 이 flags 인자의 일부이면 host 의 정식 이름을 나타내는 문자열이고, 그렇지 않으면 canonname 은 비어 있어요. sockaddr 은 소켓 주소를 설명하는 튜플이고, 그 형식은 반환된 family 에 따라 달라지며(AF_INET 은 (address, port) 2-튜플, AF_INET6 은 (address, port, flowinfo, scope_id) 4-튜플), socket.connect() 메서드에 전달하라는 뜻이에요.

참고: 소켓을 만들기 위해 getaddrinfo() 의 결과를 쓰려고 한다면(예를 들어 canonname 을 가져오는 대신), 애플리케이션이 처리할 수 있는 type(예: SOCK_STREAM 또는 SOCK_DGRAM) 및/또는 proto(예: IPPROTO_TCP 또는 IPPROTO_UDP)로 결과를 제한하는 것을 고려하세요.

family, type, proto, flags 의 기본값에서의 동작은 시스템마다 달라요.

많은 시스템(예: 대부분의 Linux 구성)은 모든 일치 주소의 정렬된 목록을 반환해요. 이 주소들은 일반적으로 연결이 성공할 때까지 순서대로 시도돼야 해요(병렬로 시도할 수도 있음, 예: Happy Eyeballs 알고리즘 사용). 이런 경우 type 및/또는 proto 를 제한하면 실패하거나 쓸 수 없는 연결 시도를 없애는 데 도움이 돼요.

그러나 일부 시스템은 단일 주소만 반환해요(예: Solaris와 AIX 구성에서 보고됨). 이런 시스템에서 type 및/또는 proto 를 제한하면 그 주소가 사용 가능함을 보장하는 데 도움이 돼요.

인자 host, port, family, type, protocol과 함께 감사 이벤트 socket.getaddrinfo 를 발생시켜요.

다음 예제는 포트 80에서 example.org 로의 가상 TCP 연결에 대한 주소 정보를 가져와요(IPv6가 활성화되지 않았다면 시스템에 따라 결과가 다를 수 있어요).

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

3.2 버전 변경: 이제 매개변수를 키워드 인자로 전달할 수 있어요.

3.7 버전 변경: IPv6 멀티캐스트 주소의 경우 주소를 나타내는 문자열이 %scope_id 부분을 포함하지 않아요.

socket.getfqdn([*name*])

name 에 대한 정규화된 도메인 이름(FQDN)을 반환해요. name 을 생략하거나 비어 있으면 로컬 호스트로 해석돼요. 정규화된 이름을 찾기 위해 gethostbyaddr() 가 반환한 호스트 이름이 확인되고, 가능하면 호스트의 별칭들이 이어져 확인돼요. 마침표를 포함하는 첫 번째 이름이 선택돼요. 정규화된 도메인 이름이 없고 name 이 제공됐다면 그대로 반환돼요. name 이 비어 있거나 '0.0.0.0' 과 같으면 gethostname() 의 호스트 이름이 반환돼요.

socket.gethostbyname(*hostname*)

호스트 이름을 IPv4 주소 형식으로 변환해요. IPv4 주소는 '100.50.200.5' 같은 문자열로 반환돼요. 호스트 이름이 그 자체로 IPv4 주소이면 변경 없이 반환돼요. 더 완전한 인터페이스는 gethostbyname_ex() 를 참고하세요. gethostbyname() 은 IPv6 이름 해석을 지원하지 않으므로, IPv4/v6 듀얼 스택 지원에는 getaddrinfo() 를 대신 사용해야 해요.

인자 hostname 과 함께 감사 이벤트 socket.gethostbyname 을 발생시켜요.

가용성: WASI 아님.

socket.gethostbyname_ex(*hostname*)

호스트 이름을 IPv4 주소 형식으로 변환하는 확장 인터페이스예요. 3-튜플 (hostname, aliaslist, ipaddrlist) 을 반환해요. hostname 은 호스트의 기본 호스트 이름, aliaslist 는 같은 주소에 대한 (비어 있을 수 있는) 대체 호스트 이름 목록, ipaddrlist 는 같은 호스트의 같은 인터페이스에 대한 IPv4 주소 목록(흔히 그러나 항상은 아닌 단일 주소)이에요. gethostbyname_ex() 는 IPv6 이름 해석을 지원하지 않으므로, IPv4/v6 듀얼 스택 지원에는 getaddrinfo() 를 대신 사용해야 해요.

인자 hostname 과 함께 감사 이벤트 socket.gethostbyname 을 발생시켜요.

가용성: WASI 아님.

socket.gethostname()

Python 인터프리터가 현재 실행 중인 머신의 호스트 이름을 담은 문자열을 반환해요.

인자 없이 감사 이벤트 socket.gethostname 을 발생시켜요.

참고: gethostname() 은 항상 정규화된 도메인 이름을 반환하지는 않아요. 그 용도에는 getfqdn() 을 사용하세요.

가용성: WASI 아님.

socket.gethostbyaddr(*ip_address*)

3-튜플 (hostname, aliaslist, ipaddrlist) 을 반환해요. hostname 은 주어진 ip_address 에 응답하는 기본 호스트 이름, aliaslist 는 같은 주소에 대한 (비어 있을 수 있는) 대체 호스트 이름 목록, ipaddrlist 는 같은 호스트의 같은 인터페이스에 대한 IPv4/v6 주소 목록(대부분 단일 주소만 포함)이에요. 정규화된 도메인 이름을 찾으려면 getfqdn() 함수를 사용하세요. gethostbyaddr() 는 IPv4와 IPv6를 모두 지원해요.

인자 ip_address 와 함께 감사 이벤트 socket.gethostbyaddr 을 발생시켜요.

가용성: WASI 아님.

socket.getnameinfo(*sockaddr*, *flags*)

소켓 주소 sockaddr 을 2-튜플 (host, port) 로 변환해요. flags 설정에 따라 결과의 host 에 정규화된 도메인 이름 또는 숫자 주소 표현이 포함될 수 있어요. 마찬가지로 port 는 문자열 포트 이름 또는 숫자 포트 번호를 포함할 수 있어요.

IPv6 주소의 경우, sockaddr 가 의미 있는 scope_id 를 포함하면 %scope_id 가 host 부분에 추가돼요. 보통 멀티캐스트 주소에서 이런 일이 일어나요.

flags 에 대한 자세한 내용은 * getnameinfo(3) * 을 참고할 수 있어요.

인자 sockaddr 와 함께 감사 이벤트 socket.getnameinfo 를 발생시켜요.

가용성: WASI 아님.

socket.getprotobyname(*protocolname*)

인터넷 프로토콜 이름(예: 'icmp')을 socket() 함수의 (선택적) 세 번째 인자로 전달하기에 적합한 상수로 변환해요. 보통 "raw" 모드(SOCK_RAW)로 연 소켓에서만 필요한데, 일반 소켓 모드에서는 프로토콜을 생략하거나 0으로 하면 올바른 프로토콜이 자동으로 선택돼요.

가용성: WASI 아님.

socket.getservbyname(*servicename*[, *protocolname*])

인터넷 서비스 이름과 프로토콜 이름을 그 서비스의 포트 번호로 변환해요. 선택적 프로토콜 이름이 주어지면 'tcp' 또는 'udp' 여야 하고, 그렇지 않으면 모든 프로토콜이 일치해요.

인자 servicename, protocolname과 함께 감사 이벤트 socket.getservbyname 을 발생시켜요.

가용성: WASI 아님.

socket.getservbyport(*port*[, *protocolname*])

인터넷 포트 번호와 프로토콜 이름을 그 서비스의 서비스 이름으로 변환해요. 선택적 프로토콜 이름이 주어지면 'tcp' 또는 'udp' 여야 하고, 그렇지 않으면 모든 프로토콜이 일치해요.

인자 port, protocolname과 함께 감사 이벤트 socket.getservbyport 를 발생시켜요.

가용성: WASI 아님.

socket.ntohl(*x*)

32비트 양의 정수를 네트워크 바이트 순서에서 호스트 바이트 순서로 변환해요. 호스트 바이트 순서가 네트워크 바이트 순서와 같은 머신에서는 아무것도 하지 않아요(no-op). 그 외에는 4바이트 스왑 연산을 수행해요.

socket.ntohs(*x*)

16비트 양의 정수를 네트워크 바이트 순서에서 호스트 바이트 순서로 변환해요. 호스트 바이트 순서가 네트워크 바이트 순서와 같은 머신에서는 no-op이에요. 그 외에는 2바이트 스왑 연산을 수행해요.

3.10 버전 변경: x 가 16비트 부호 없는 정수에 맞지 않으면 OverflowError 를 발생시켜요.

socket.htonl(*x*)

32비트 양의 정수를 호스트 바이트 순서에서 네트워크 바이트 순서로 변환해요. 호스트 바이트 순서가 네트워크 바이트 순서와 같은 머신에서는 no-op이에요. 그 외에는 4바이트 스왑 연산을 수행해요.

socket.htons(*x*)

16비트 양의 정수를 호스트 바이트 순서에서 네트워크 바이트 순서로 변환해요. 호스트 바이트 순서가 네트워크 바이트 순서와 같은 머신에서는 no-op이에요. 그 외에는 2바이트 스왑 연산을 수행해요.

3.10 버전 변경: x 가 16비트 부호 없는 정수에 맞지 않으면 OverflowError 를 발생시켜요.

socket.inet_aton(*ip_string*)

IPv4 주소를 점분리(dotted-quad) 문자열 형식(예: '123.45.67.89')에서 4문자 길이의 bytes 객체인 32비트 패킹 이진 형식으로 변환해요. 표준 C 라이브러리를 쓰면서 이 함수가 반환하는 32비트 패킹 이진의 C 유형인 in_addr 형식의 객체가 필요한 프로그램과 대화할 때 유용해요.

inet_aton() 은 점이 3개 미만인 문자열도 받아들여요. 자세한 내용은 Unix 매뉴얼 페이지 * inet(3) * 참고.

이 함수에 전달된 IPv4 주소 문자열이 유효하지 않으면 OSError 가 발생해요. 정확히 무엇이 유효한지는 기반 C 구현인 inet_aton() 에 따라 달라진다는 점에 유의하세요.

inet_aton() 은 IPv6를 지원하지 않으므로, IPv4/v6 듀얼 스택 지원에는 inet_pton() 을 대신 사용해야 해요.

socket.inet_ntoa(*packed_ip*)

32비트 패킹 IPv4 주소(4바이트 길이의 bytes-like 객체)를 표준 점분리 문자열 표현(예: '123.45.67.89')으로 변환해요. 표준 C 라이브러리를 쓰면서 이 함수가 인자로 받는 32비트 패킹 이진 데이터의 C 유형인 in_addr 형식의 객체가 필요한 프로그램과 대화할 때 유용해요.

이 함수에 전달된 바이트 시퀀스가 정확히 4바이트가 아니면 OSError 가 발생해요. inet_ntoa() 는 IPv6를 지원하지 않으므로, IPv4/v6 듀얼 스택 지원에는 inet_ntop() 을 대신 사용해야 해요.

3.5 버전 변경: 쓰기 가능한 bytes-like 객체가 이제 허용돼요.

socket.inet_pton(*address_family*, *ip_string*)

IP 주소를 패밀리별 문자열 형식에서 패킹된 이진 형식으로 변환해요. inet_pton() 은 라이브러리나 네트워크 프로토콜이 in_addr(inet_aton() 과 유사) 또는 in6_addr 형식의 객체를 요구할 때 유용해요.

현재 address_family 에 대해 지원되는 값은 AF_INET 과 AF_INET6 이에요. IP 주소 문자열 ip_string 이 유효하지 않으면 OSError 가 발생해요. 정확히 무엇이 유효한지는 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() 은 라이브러리나 네트워크 프로토콜이 in_addr(inet_ntoa() 와 유사) 또는 in6_addr 형식의 객체를 반환할 때 유용해요.

현재 address_family 에 대해 지원되는 값은 AF_INET 과 AF_INET6 이에요. bytes 객체 packed_ip 가 지정된 주소 패밀리에 맞는 길이가 아니면 ValueError 가 발생해요. inet_ntop() 호출 오류에 대해서는 OSError 가 발생해요.

가용성: Unix, Windows.

3.4 버전 변경: Windows 지원 추가.

3.5 버전 변경: 쓰기 가능한 bytes-like 객체가 이제 허용돼요.

socket.CMSG_LEN(*length*)

주어진 length 의 관련 데이터를 가진 보조 데이터(ancillary data) 항목의 총 길이(끝의 패딩 제외)를 반환해요. 이 값은 recvmsg() 가 단일 보조 데이터 항목을 받기 위한 버퍼 크기로 자주 쓰일 수 있지만, RFC 3542 는 항목이 버퍼의 마지막에 있더라도 이식 가능한 애플리케이션이 CMSG_SPACE() 를 사용해 패딩 공간을 포함하도록 요구해요. length 가 허용 범위 밖이면 OverflowError 를 발생시켜요.

가용성: Unix, WASI 아님. 대부분의 Unix 플랫폼.

3.3 버전에서 추가.

socket.CMSG_SPACE(*length*)

recvmsg() 가 주어진 length 의 관련 데이터를 가진 보조 데이터 항목을 (끝의 패딩을 포함해) 받는 데 필요한 버퍼 크기를 반환해요. 여러 항목을 받는 데 필요한 버퍼 공간은 관련 데이터 길이의 CMSG_SPACE() 값들의 합이에요. length 가 허용 범위 밖이면 OverflowError 를 발생시켜요.

일부 시스템은 이 함수를 제공하지 않고 보조 데이터를 지원할 수 있다는 점에 유의하세요. 또한 이 함수의 결과로 버퍼 크기를 지정해도 받을 수 있는 보조 데이터 양을 정확히 제한하지 못할 수 있는데, 추가 데이터가 패딩 영역에 들어갈 수 있기 때문이에요.

가용성: Unix, WASI 아님. 대부분의 Unix 플랫폼.

3.3 버전에서 추가.

socket.getdefaulttimeout()

새 socket 객체에 대한 기본 타임아웃을 초(부동소수점) 단위로 반환해요. None 값은 새 socket 객체에 타임아웃이 없음을 나타내요. socket 모듈이 처음 임포트될 때 기본값은 None 이에요.

socket.setdefaulttimeout(*timeout*)

새 socket 객체에 대한 기본 타임아웃을 초(부동소수점) 단위로 설정해요. socket 모듈이 처음 임포트될 때 기본값은 None 이에요. 가능한 값과 각각의 의미는 settimeout() 참고.

socket.sethostname(*name*)

머신의 호스트 이름을 name 으로 설정해요. 충분한 권한이 없으면 OSError 가 발생해요.

인자 name 과 함께 감사 이벤트 socket.sethostname 을 발생시켜요.

가용성: Unix, Android 아님.

3.3 버전에서 추가.

socket.if_nameindex()

네트워크 인터페이스 정보(인덱스 int, 이름 string) 튜플의 목록을 반환해요. 시스템 호출이 실패하면 OSError.

가용성: Unix, Windows, WASI 아님.

3.3 버전에서 추가.

3.8 버전 변경: Windows 지원이 추가됐어요.

참고: Windows에서 네트워크 인터페이스는 상황에 따라 다른 이름을 가져요(모든 이름은 예시).

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

name: ethernet_32770

friendly name: vEthernet (nat)

description: Hyper-V Virtual Ethernet Adapter

이 함수는 목록에서 두 번째 형식의 이름(이 예시에서는 ethernet_32770)을 반환해요.

socket.if_nametoindex(*if_name*)

인터페이스 이름에 해당하는 네트워크 인터페이스 인덱스 번호를 반환해요. 주어진 이름의 인터페이스가 없으면 OSError.

가용성: Unix, Windows, WASI 아님.

3.3 버전에서 추가.

3.8 버전 변경: Windows 지원이 추가됐어요.

참고: "인터페이스 이름"은 if_nameindex() 에 문서화된 이름이에요.

socket.if_indextoname(*if_index*)

인터페이스 인덱스 번호에 해당하는 네트워크 인터페이스 이름을 반환해요. 주어진 인덱스의 인터페이스가 없으면 OSError.

가용성: Unix, Windows, WASI 아님.

3.3 버전에서 추가.

3.8 버전 변경: Windows 지원이 추가됐어요.

참고: "인터페이스 이름"은 if_nameindex() 에 문서화된 이름이에요.

socket.send_fds(*sock*, *buffers*, *fds*[, *flags*[, *address*]])

AF_UNIX 소켓 sock 을 통해 파일 디스크립터 목록 fds 를 보내요. fds 매개변수는 파일 디스크립터들의 시퀀스예요. 이 매개변수들의 문서는 sendmsg() 를 참고하세요.

가용성: Unix, WASI 아님. sendmsg() 와 SCM_RIGHTS 메커니즘을 지원하는 Unix 플랫폼.

3.9 버전에서 추가.

socket.recv_fds(*sock*, *bufsize*, *maxfds*[, *flags*])

AF_UNIX 소켓 sock 에서 최대 maxfds 개의 파일 디스크립터를 받아요. (msg, list(fds), flags, addr) 을 반환해요. 이 매개변수들의 문서는 recvmsg() 를 참고하세요.

가용성: Unix, WASI 아님. recvmsg() 와 SCM_RIGHTS 메커니즘을 지원하는 Unix 플랫폼.

3.9 버전에서 추가.

참고: 파일 디스크립터 목록 끝의 잘린 정수는 무시돼요.

Socket Objects

클래스 socket.socket(*family=AF_INET*, *type=SOCK_STREAM*, *proto=0*, *fileno=None*)

주어진 주소 패밀리, 소켓 유형, 프로토콜 번호로 새 소켓을 만들어요. 주소 패밀리는 AF_INET(기본), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET 또는 AF_RDS 여야 해요. 소켓 유형은 SOCK_STREAM(기본), SOCK_DGRAM, SOCK_RAW 또는 다른 SOCK_ 상수 중 하나여야 해요. 프로토콜 번호는 보통 0이고 생략할 수 있으며, 주소 패밀리가 AF_CAN 인 경우 프로토콜은 CAN_RAW, CAN_BCM, CAN_ISOTP 또는 CAN_J1939 중 하나여야 해요.

fileno 가 지정되면 family, type, proto 값은 지정된 파일 디스크립터에서 자동 감지돼요. 자동 감지는 명시적 family, type, proto 인자로 호출해 무시할 수 있어요. 이것은 Python이 예를 들어 socket.getpeername() 의 반환 값을 어떻게 표현하는지에만 영향을 주고, 실제 OS 리소스에는 영향을 주지 않아요. socket.fromfd() 와 달리 fileno 는 중복본이 아닌 같은 소켓을 반환해요. 이것은 socket.close() 로 분리된 소켓을 닫는 데 도움이 될 수 있어요.

새로 만들어진 소켓은 non-inheritable이에요.

인자 self, family, type, protocol과 함께 감사 이벤트 socket.__new__ 를 발생시켜요.

3.3 버전 변경: AF_CAN 패밀리와 AF_RDS 패밀리가 추가됐어요.

3.4 버전 변경: CAN_BCM 프로토콜이 추가됐고, 반환된 소켓이 non-inheritable이 됐어요.

3.7 버전 변경: CAN_ISOTP 프로토콜이 추가됐어요. SOCK_NONBLOCK 이나 SOCK_CLOEXEC 비트 플래그가 type 에 적용되면 지워지고 socket.type 에 반영되지 않아요. 여전히 기반 시스템 socket() 호출에는 전달돼요. 따라서:
sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)
는 SOCK_NONBLOCK 을 지원하는 OS에서 여전히 non-blocking 소켓을 만들지만, sock.type 은 socket.SOCK_STREAM 으로 설정돼요.

3.9 버전 변경: CAN_J1939 프로토콜이 추가됐어요.

3.10 버전 변경: IPPROTO_MPTCP 프로토콜이 추가됐어요.

Socket 객체는 다음 메서드들을 가져요. makefile() 을 제외하면 소켓에 적용되는 Unix 시스템 호출에 대응해요.

3.2 버전 변경: 컨텍스트 관리자 프로토콜 지원이 추가됐어요. 컨텍스트 관리자를 나가는 것은 close() 를 호출하는 것과 동등해요.

accept()

연결을 받아들여요. 소켓은 주소에 바인딩돼 있고 연결을 수신 대기 중이어야 해요. 반환 값은 쌍 (conn, address) 이에요. conn 은 연결에서 데이터를 주고받는 데 사용할 수 있는 새로운 socket 객체이고, address 는 연결의 다른 쪽 끝에서 소켓에 바인딩된 주소예요.

새로 만들어진 소켓은 non-inheritable이에요.

3.4 버전 변경: 소켓이 이제 non-inheritable이에요.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, 이 메서드는 InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

bind(*address*)

소켓을 address 에 바인딩해요. 소켓은 아직 바인딩되지 않아야 해요. address 의 형식은 주소 패밀리에 따라 달라요(Socket families 참고).

인자 self, address와 함께 감사 이벤트 socket.bind 를 발생시켜요.

가용성: WASI 아님.

close()

소켓을 닫힌 것으로 표시해요. makefile() 의 모든 파일 객체가 닫힐 때 기반 시스템 리소스(예: 파일 디스크립터)도 닫혀요. 그렇게 되면 소켓 객체에 대한 모든 이후 연산은 실패해요. 원격 끝은 (큐에 있는 데이터가 flush된 후) 더 이상 데이터를 받지 않아요.

소켓은 가비지 컬렉션될 때 자동으로 닫히지만, 명시적으로 close() 하거나 with 문으로 감싸는 것을 권장해요.

3.6 버전 변경: 기반 close() 호출 시 오류가 발생하면 이제 OSError 가 발생해요.

참고: close() 는 연결과 관련된 리소스를 해제하지만 반드시 즉시 연결을 닫는 것은 아니에요. 제때 연결을 닫으려면 close() 전에 shutdown() 을 호출하세요.

connect(*address*)

address 의 원격 소켓에 연결해요. address 의 형식은 주소 패밀리에 따라 달라요(Socket families 참고).

연결이 신호로 중단되면, 신호 핸들러가 예외를 발생시키지 않고 소켓이 블로킹이거나 타임아웃이 있으면, 이 메서드는 연결이 완료될 때까지 기다리거나 타임아웃 시 TimeoutError 를 발생시켜요. non-blocking 소켓의 경우, 연결이 신호로 중단되면(또는 신호 핸들러가 발생시킨 예외) 이 메서드는 InterruptedError 예외를 발생시켜요.

인자 self, address와 함께 감사 이벤트 socket.connect 를 발생시켜요.

3.5 버전 변경: 연결이 신호로 중단되고, 신호 핸들러가 예외를 발생시키지 않으며, 소켓이 블로킹이거나 타임아웃이 있으면, InterruptedError 예외를 발생시키는 대신 이제 연결이 완료될 때까지 기다려요(근거: PEP 475).

가용성: WASI 아님.

connect_ex(*address*)

connect(address) 와 같지만, C 수준 connect() 호출이 반환한 오류에 대해 예외를 발생시키는 대신 오류 표시기를 반환해요(다른 문제, 예: "host not found"는 여전히 예외를 발생시킬 수 있음). 연산이 성공하면 오류 표시기는 0 이고, 그렇지 않으면 errno 변수의 값이에요. 예를 들어 비동기 연결을 지원하는 데 유용해요.

인자 self, address와 함께 감사 이벤트 socket.connect 를 발생시켜요.

가용성: WASI 아님.

detach()

기반 파일 디스크립터를 실제로 닫지 않고 socket 객체를 닫힌 상태로 만들어요. 파일 디스크립터가 반환되고 다른 용도로 재사용할 수 있어요.

3.2 버전에서 추가.

dup()

소켓을 중복해요.

새로 만들어진 소켓은 non-inheritable이에요.

3.4 버전 변경: 소켓이 이제 non-inheritable이에요.

가용성: WASI 아님.

fileno()

소켓의 파일 디스크립터(작은 정수)를 반환하거나, 실패 시 -1을 반환해요. select.select() 와 함께 유용해요.

Windows에서 이 메서드가 반환한 작은 정수는 파일 디스크립터를 쓸 수 있는 곳(예: os.fdopen())에서는 쓸 수 없어요. Unix에는 이 제한이 없어요.

get_inheritable()

소켓의 파일 디스크립터 또는 소켓 핸들의 상속 가능 플래그를 가져와요. 자식 프로세스에서 소켓을 상속할 수 있으면 True, 없으면 False.

3.4 버전에서 추가.

getpeername()

소켓이 연결된 원격 주소를 반환해요. 예를 들어 원격 IPv4/v6 소켓의 포트 번호를 찾는 데 유용해요. 반환되는 주소의 형식은 주소 패밀리에 따라 달라요(Socket families 참고). 일부 시스템에서는 이 함수가 지원되지 않아요.

getsockname()

소켓 자신의 주소를 반환해요. 예를 들어 IPv4/v6 소켓의 포트 번호를 찾는 데 유용해요. 반환되는 주소의 형식은 주소 패밀리에 따라 달라요(Socket families 참고).

getsockopt(*level*, *optname*[, *buflen*])

주어진 소켓 옵션의 값을 반환해요(Unix 매뉴얼 페이지 * getsockopt(2) * 참고). 필요한 기호 상수(SO_* 등)는 이 모듈에 정의돼 있어요. buflen 이 없으면 정수 옵션으로 가정하고 함수가 그 정수 값을 반환해요. buflen 이 있으면 옵션을 받는 데 쓰는 버퍼의 최대 길이를 지정하고, 이 버퍼가 bytes 객체로 반환돼요. 버퍼 내용을 해독하는 것은 호출자의 몫이에요(바이트 문자열로 인코딩된 C 구조를 해독하는 방법은 선택적 내장 모듈 struct 참고).

가용성: WASI 아님.

getblocking()

소켓이 블로킹 모드이면 True, non-blocking이면 False 를 반환해요.

이것은 socket.gettimeout() != 0 을 확인하는 것과 동등해요.

3.7 버전에서 추가.

gettimeout()

소켓 연산과 관련된 타임아웃을 초(부동소수점) 단위로 반환하거나, 타임아웃이 설정돼 있지 않으면 None 을 반환해요. setblocking() 또는 settimeout() 에 대한 마지막 호출을 반영해요.

ioctl(*control*, *option*)

ioctl() 메서드는 WSAIoctl 시스템 인터페이스에 대한 제한적 인터페이스예요. 자세한 내용은 Win32 문서를 참고하세요.

다른 플랫폼에서는 일반적인 fcntl.fcntl() 과 fcntl.ioctl() 함수를 사용할 수 있어요. 이 함수들은 첫 번째 인자로 socket 객체를 받아요.

현재 지원되는 제어 코드는 SIO_RCVALL, SIO_KEEPALIVE_VALS, SIO_LOOPBACK_FAST_PATH 뿐이에요.

가용성: Windows.

3.6 버전 변경: SIO_LOOPBACK_FAST_PATH 가 추가됐어요.

listen([*backlog*])

서버가 연결을 받아들이도록 활성화해요. backlog 가 지정되면 최소 0이어야 해요(더 낮으면 0으로 설정됨). 그것은 시스템이 새 연결을 거부하기 전에 허용할 받아들여지지 않은 연결의 수를 지정해요. 지정하지 않으면 합리적인 기본값이 선택돼요.

가용성: WASI 아님.

3.5 버전 변경: backlog 매개변수가 이제 선택적이에요.

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

소켓과 연결된 file object 를 반환해요. 정확한 반환 형식은 makefile() 에 주어진 인자에 따라 달라요. 이 인자들은 내장 open() 함수와 같은 방식으로 해석되지만, 지원되는 mode 값은 'r'(기본), 'w', 'b' 또는 그 조합뿐이에요.

소켓은 블로킹 모드여야 해요. 타임아웃이 있을 수 있지만, 타임아웃이 발생하면 file object의 내부 버퍼가 일관되지 않은 상태가 될 수 있어요.

makefile() 이 반환한 file object를 닫아도 원래 소켓은 닫히지 않아요. 다른 모든 file object가 닫히고 socket 객체에 socket.close() 가 호출된 경우에만 닫혀요.

참고: Windows에서 makefile() 이 만든 file-like 객체는 파일 디스크립터가 있는 file object가 기대되는 곳(예: subprocess.Popen() 의 스트림 인자)에서는 쓸 수 없어요.

recv(*bufsize*[, *flags*])

소켓에서 데이터를 받아요. 반환 값은 받은 데이터를 나타내는 bytes 객체예요. 한 번에 받을 최대 데이터 양은 bufsize 가 지정해요. 비어 있는 bytes 객체를 반환하면 클라이언트가 연결을 끊었음을 나타내요. 선택적 인자 flags 의 의미는 Unix 매뉴얼 페이지 * recv(2) * 참고. 기본값은 0이에요.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

recvfrom(*bufsize*[, *flags*])

소켓에서 데이터를 받아요. 반환 값은 쌍 (bytes, address) 이에요. bytes 는 받은 데이터를 나타내는 bytes 객체, address 는 데이터를 보낸 소켓의 주소예요. 선택적 인자 flags 의 의미는 Unix 매뉴얼 페이지 * recv(2) * 참고. 기본값은 0이에요. address 의 형식은 주소 패밀리에 따라 달라요(Socket families 참고).

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

3.7 버전 변경: 멀티캐스트 IPv6 주소의 경우, address 의 첫 항목이 더 이상 %scope_id 부분을 포함하지 않아요. 전체 IPv6 주소를 얻으려면 getnameinfo() 를 사용하세요.

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

소켓에서 일반 데이터(최대 bufsize 바이트)와 보조 데이터를 받아요. ancbufsize 인자는 보조 데이터를 받는 데 쓰는 내부 버퍼의 크기를 바이트 단위로 설정해요. 기본값은 0으로, 보조 데이터를 받지 않음을 의미해요. 보조 데이터에 적합한 버퍼 크기는 CMSG_SPACE() 또는 CMSG_LEN() 으로 계산할 수 있고, 버퍼에 맞지 않는 항목은 잘리거나 버려질 수 있어요. flags 인자는 기본값 0이고 recv() 와 같은 의미를 가져요.

반환 값은 4-튜플 (data, ancdata, msg_flags, address) 이에요. data 항목은 받은 비-보조 데이터를 담은 bytes 객체예요. ancdata 항목은 받은 보조 데이터(제어 메시지)를 나타내는 0개 이상의 튜플 (cmsg_level, cmsg_type, cmsg_data) 의 목록이에요. cmsg_level 과 cmsg_type 은 각각 프로토콜 레벨과 프로토콜별 유형을 지정하는 정수고, cmsg_data 는 관련 데이터를 담은 bytes 객체예요. msg_flags 항목은 받은 메시지의 조건을 나타내는 다양한 플래그의 비트 OR이에요. 자세한 내용은 시스템 문서를 참고하세요. 수신 소켓이 연결되지 않았다면 address 는 사용 가능할 때 보내는 소켓의 주소이고, 그렇지 않으면 값은 지정되지 않아요.

일부 시스템에서 sendmsg() 와 recvmsg() 는 AF_UNIX 소켓을 통해 프로세스 간에 파일 디스크립터를 전달하는 데 쓸 수 있어요. 이 기능(종종 SOCK_STREAM 소켓으로 제한됨)을 사용할 때 recvmsg() 는 보조 데이터에서 (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds) 형태의 항목을 반환하는데, fds 는 네이티브 C int 형식의 이진 배열로 새 파일 디스크립터를 나타내는 bytes 객체예요. 시스템 호출이 반환된 후 recvmsg() 가 예외를 발생시키면, 먼저 이 메커니즘을 통해 받은 모든 파일 디스크립터를 닫으려고 시도해요.

일부 시스템은 부분적으로만 받은 보조 데이터 항목의 잘린 길이를 나타내지 않아요. 항목이 버퍼 끝 너머로 이어지는 것처럼 보이면 recvmsg() 는 RuntimeWarning 을 발생시키고, 관련 데이터 시작 전에 잘리지 않았다면 버퍼 안에 있는 부분을 반환해요.

SCM_RIGHTS 메커니즘을 지원하는 시스템에서 다음 함수는 최대 maxfds 개의 파일 디스크립터를 받아 메시지 데이터와 디스크립터를 담은 목록을 반환해요(관련 없는 제어 메시지 수신 같은 예상치 못한 조건은 무시). sendmsg() 도 참고하세요.

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # 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)

가용성: Unix. 대부분의 Unix 플랫폼.

3.3 버전에서 추가.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

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

소켓에서 일반 데이터와 보조 데이터를 받아요. recvmsg() 처럼 동작하지만, 비-보조 데이터를 새 bytes 객체로 반환하는 대신 일련의 버퍼에 흩어 써요. buffers 인자는 쓰기 가능한 버퍼를 내보내는 객체들(예: bytearray 객체)의 이터러블이어야 해요. 이것들은 모든 비-보조 데이터가 기록되거나 버퍼가 더 없을 때까지 연속 청크로 채워져요. 운영 체제가 사용할 수 있는 버퍼 수에 제한(sysconf() 값 SC_IOV_MAX)을 설정할 수 있어요. ancbufsize 와 flags 인자는 recvmsg() 와 같은 의미를 가져요.

반환 값은 4-튜플 (nbytes, ancdata, msg_flags, address) 이에요. nbytes 는 버퍼에 기록된 비-보조 데이터의 총 바이트 수이고, ancdata, msg_flags, address 는 recvmsg() 와 같아요.

예:

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

가용성: Unix. 대부분의 Unix 플랫폼.

3.3 버전에서 추가.

recvfrom_into(*buffer*[, *nbytes*[, *flags*]])

소켓에서 데이터를 받아 새 바이트 문자열을 만드는 대신 buffer 에 써요. 반환 값은 쌍 (nbytes, address) 이에요. nbytes 는 받은 바이트 수, address 는 데이터를 보낸 소켓의 주소예요. 선택적 인자 flags 의 의미는 Unix 매뉴얼 페이지 * recv(2) * 참고. 기본값은 0이에요. address 의 형식은 주소 패밀리에 따라 달라요(Socket families 참고).

recv_into(*buffer*[, *nbytes*[, *flags*]])

소켓에서 최대 nbytes 바이트를 받아 새 바이트 문자열을 만드는 대신 버퍼에 저장해요. nbytes 를 지정하지 않으면(또는 0이면) 주어진 버퍼에서 사용 가능한 크기까지 받아요. 받은 바이트 수를 반환해요. 선택적 인자 flags 의 의미는 Unix 매뉴얼 페이지 * recv(2) * 참고. 기본값은 0이에요.

send(*bytes*[, *flags*])

소켓에 데이터를 보내요. 소켓은 원격 소켓에 연결돼 있어야 해요. 선택적 flags 인자는 recv() 와 같은 의미를 가져요. 보낸 바이트 수를 반환해요. 애플리케이션은 모든 데이터가 보내졌는지 확인해야 해요. 일부만 전송됐다면 애플리케이션은 나머지 데이터를 전달하려고 시도해야 해요. 이 주제에 대한 자세한 정보는 Socket Programming HOWTO를 참고하세요.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

sendall(*bytes*[, *flags*])

소켓에 데이터를 보내요. 소켓은 원격 소켓에 연결돼 있어야 해요. 선택적 flags 인자는 recv() 와 같은 의미를 가져요. send() 와 달리 이 메서드는 모든 데이터가 보내지거나 오류가 발생할 때까지 bytes 의 데이터를 계속 보내요. 성공하면 None 을 반환해요. 오류가 있으면 예외가 발생하고, 얼마나 많은 데이터가 성공적으로 보내졌는지(보냈다면) 알아낼 방법이 없어요.

3.5 버전 변경: 데이터가 성공적으로 보내질 때마다 소켓 타임아웃이 더 이상 리셋되지 않아요. 소켓 타임아웃은 이제 모든 데이터를 보내는 최대 총 시간이에요.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

sendto(*bytes*, *address*)

sendto(*bytes*, *flags*, *address*)

소켓에 데이터를 보내요. 목적지 소켓이 address 로 지정되므로 소켓은 원격 소켓에 연결돼 있지 않아야 해요. 선택적 flags 인자는 recv() 와 같은 의미를 가져요. 보낸 바이트 수를 반환해요. address 의 형식은 주소 패밀리에 따라 달라요(Socket families 참고).

인자 self, address와 함께 감사 이벤트 socket.sendto 를 발생시켜요.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

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

소켓에 일반 및 보조 데이터를 보내요. 비-보조 데이터를 일련의 버퍼에서 모아 단일 메시지로 연결해요. buffers 인자는 bytes-like 객체(예: bytes 객체)의 이터러블로 비-보조 데이터를 지정해요. 운영 체제가 사용할 수 있는 버퍼 수에 제한(sysconf() 값 SC_IOV_MAX)을 설정할 수 있어요. ancdata 인자는 0개 이상의 튜플 (cmsg_level, cmsg_type, cmsg_data) 의 이터러블로 보조 데이터(제어 메시지)를 지정해요. cmsg_level 과 cmsg_type 은 각각 프로토콜 레벨과 프로토콜별 유형을 지정하는 정수고, cmsg_data 는 관련 데이터를 담은 bytes-like 객체예요. 일부 시스템(특히 CMSG_SPACE() 가 없는 시스템)은 호출당 제어 메시지를 하나만 보내는 것을 지원할 수 있다는 점에 유의하세요. flags 인자는 기본값 0이고 send() 와 같은 의미를 가져요. address 가 주어지고 None 이 아니면 메시지의 목적지 주소를 설정해요. 반환 값은 보낸 비-보조 데이터의 바이트 수예요.

다음 함수는 SCM_RIGHTS 메커니즘을 지원하는 시스템에서 AF_UNIX 소켓을 통해 파일 디스크립터 목록 fds 를 보내요. recvmsg() 도 참고하세요.

import socket, array

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

가용성: Unix, WASI 아님. 대부분의 Unix 플랫폼.

인자 self, address와 함께 감사 이벤트 socket.sendmsg 를 발생시켜요.

3.3 버전에서 추가.

3.5 버전 변경: 시스템 호출이 중단되고 신호 핸들러가 예외를 발생시키지 않으면, InterruptedError 예외를 발생시키는 대신 이제 시스템 호출을 재시도해요(근거: PEP 475).

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

AF_ALG 소켓을 위한 sendmsg() 의 특수 버전이에요. AF_ALG 소켓의 모드, IV, AEAD 관련 데이터 길이와 플래그를 설정해요.

가용성: Linux >= 2.6.38.

3.6 버전에서 추가.

sendfile(*file*, *offset=0*, *count=None*)

고성능 os.sendfile 을 사용해 EOF에 도달할 때까지 파일을 보내고 보낸 총 바이트 수를 반환해요. file 은 이진 모드로 열린 일반 파일 객체여야 해요. os.sendfile 을 사용할 수 없거나(예: Windows) file 이 일반 파일이 아니면 send() 가 대신 사용돼요. offset 은 파일 읽기를 시작할 위치를 알려줘요. count 가 지정되면 EOF까지 보내는 대신 전송할 총 바이트 수예요. 파일 위치는 반환 시 갱신되고, 오류가 있어도 갱신돼요. 그 경우 file.tell() 로 보낸 바이트 수를 알아낼 수 있어요. 소켓은 SOCK_STREAM 유형이어야 해요. Non-blocking 소켓은 지원되지 않아요.

3.5 버전에서 추가.

set_inheritable(*inheritable*)

소켓의 파일 디스크립터 또는 소켓 핸들의 상속 가능 플래그를 설정해요.

3.4 버전에서 추가.

setblocking(*flag*)

소켓의 블로킹 또는 non-blocking 모드를 설정해요. flag 가 false이면 소켓은 non-blocking으로, 그렇지 않으면 블로킹 모드로 설정돼요.

이 메서드는 특정 settimeout() 호출의 축약형이에요.

sock.setblocking(True) 는 sock.settimeout(None) 과 동등.
sock.setblocking(False) 는 sock.settimeout(0.0) 과 동등.

3.7 버전 변경: 이 메서드는 더 이상 socket.type 에 SOCK_NONBLOCK 플래그를 적용하지 않아요.

settimeout(*value*)

블로킹 소켓 연산에 타임아웃을 설정해요. value 인자는 초를 나타내는 음이 아닌 실수 또는 None 일 수 있어요. 0이 아닌 값이 주어지면, 이후 소켓 연산은 타임아웃 기간 value 가 연산 완료 전에 경과하면 timeout 예외를 발생시켜요. 0이 주어지면 소켓은 non-blocking 모드가 돼요. None 이 주어지면 소켓은 블로킹 모드가 돼요.

자세한 내용은 소켓 타임아웃에 대한 참고 사항을 참고하세요.

3.7 버전 변경: 이 메서드는 더 이상 socket.type 에서 SOCK_NONBLOCK 플래그를 토글하지 않아요.

setsockopt(*level*, *optname*, *value: int | Buffer*)

setsockopt(*level*, *optname*, *None*, *optlen: int*)

주어진 소켓 옵션의 값을 설정해요(Unix 매뉴얼 페이지 * setsockopt(2) * 참고). 필요한 기호 상수는 이 모듈에 정의돼 있어요(SO_* 등). 값은 정수, None, 또는 버퍼를 나타내는 bytes-like 객체일 수 있어요. 후자의 경우 바이트 문자열에 적절한 비트가 들어 있는지 확인하는 것은 호출자의 몫이에요(바이트 문자열로 C 구조를 인코딩하는 방법은 선택적 내장 모듈 struct 참고). value 가 None 으로 설정되면 optlen 인자가 필요해요. C 함수 setsockopt() 를 optval=NULL, optlen=optlen 으로 호출하는 것과 동등해요.

3.5 버전 변경: 쓰기 가능한 bytes-like 객체가 이제 허용돼요.

3.6 버전 변경: setsockopt(level, optname, None, optlen: int) 형식이 추가됐어요.

가용성: WASI 아님.

shutdown(*how*)

연결의 절반 또는 양쪽 모두를 종료해요. how 가 SHUT_RD 이면 이후의 수신이 허용되지 않아요. how 가 SHUT_WR 이면 이후의 송신이 허용되지 않아요. how 가 SHUT_RDWR 이면 이후의 송수신이 모두 허용되지 않아요.

가용성: WASI 아님.

share(*process_id*)

소켓을 중복하고 대상 프로세스와 공유할 준비를 해요. 대상 프로세스를 process_id 로 제공해야 해요. 결과 bytes 객체는 어떤 형태의 프로세스 간 통신을 사용해 대상 프로세스에 전달할 수 있고, 소켓은 fromshare() 를 사용해 그곳에서 다시 만들 수 있어요. 이 메서드가 호출된 후에는 소켓을 닫아도 안전한데, 운영 체제가 이미 대상 프로세스를 위해 소켓을 중복했기 때문이에요.

가용성: Windows.

3.3 버전에서 추가.

read() 나 write() 메서드는 없다는 점에 유의하세요. 대신 flags 인자 없는 recv() 와 send() 를 사용하세요.

Socket 객체는 socket 생성자에 주어진 값들에 대응하는 이 (읽기 전용) 속성들도 가져요.

family

소켓 패밀리.

type

소켓 유형.

proto

소켓 프로토콜.

클래스 socket.SocketType

socket 유형의 기본 클래스로, _socket 에서 다시 내보내진 것이에요. isinstance(socket(...), SocketType) 같은 인스턴스 검사는 true지만, SocketType 는 socket 그 자체인 type(socket(...)) 과 같지 않아요.

소켓 타임아웃에 대한 참고

socket 객체는 세 가지 모드 중 하나일 수 있어요: 블로킹, non-blocking, 타임아웃. 소켓은 기본적으로 항상 블로킹 모드로 만들어지지만, setdefaulttimeout() 을 호출해 바꿀 수 있어요.

블로킹 모드에서는 연산이 완료되거나 시스템이 오류(연결 타임아웃 같은)를 반환할 때까지 블로킹해요.
non-blocking 모드에서는 연산이 즉시 완료될 수 없으면 실패해요(불행히도 시스템에 따라 다른 오류). select 모듈의 함수를 사용해 소켓이 읽기나 쓰기에 사용 가능한 시기와 여부를 알 수 있어요.
타임아웃 모드에서는 연산이 소켓에 지정된 타임아웃 안에 완료될 수 없으면 실패해요(timeout 예외를 발생)하거나 시스템이 오류를 반환하면 실패해요.

참고: 운영 체제 수준에서 타임아웃 모드의 소켓은 내부적으로 non-blocking 모드로 설정돼요. 또한 블로킹과 타임아웃 모드는 같은 네트워크 엔드포인트를 가리키는 파일 디스크립터와 socket 객체 사이에서 공유돼요. 이 구현 세부사항은 예를 들어 소켓의 fileno() 를 사용하기로 결정했다면 눈에 보이는 결과를 가질 수 있어요.

타임아웃과 `connect` 메서드

connect() 연산도 타임아웃 설정의 적용을 받아요. 일반적으로 connect() 를 호출하기 전에 settimeout() 을 호출하거나 create_connection() 에 타임아웃 매개변수를 전달하는 것을 권장해요. 다만 시스템 네트워크 스택도 Python 소켓 타임아웃 설정과 무관하게 자체적인 연결 타임아웃 오류를 반환할 수 있어요.

타임아웃과 `accept` 메서드

getdefaulttimeout() 이 None 이 아니면 accept() 메서드가 반환한 소켓은 그 타임아웃을 상속해요. 그렇지 않으면 동작은 수신 대기 소켓의 설정에 따라 달라져요.

수신 대기 소켓이 블로킹 모드 또는 타임아웃 모드이면, accept() 가 반환한 소켓은 블로킹 모드예요.
수신 대기 소켓이 non-blocking 모드이면, accept() 가 반환한 소켓이 블로킹인지 non-blocking인지는 운영 체제에 따라 달라요. 플랫폼 간 동작을 보장하려면 이 설정을 수동으로 재정의하는 것을 권장해요.

예제

TCP/IP 프로토콜을 사용하는 네 개의 최소 예제 프로그램이 있어요. 받은 모든 데이터를 다시 에코하는 서버(클라이언트 하나만 서비스)와 그것을 사용하는 클라이언트예요. 서버는 socket(), bind(), listen(), accept() 순서를 수행해야 하고(둘 이상의 클라이언트를 서비스하려면 accept() 를 반복할 수 있음), 클라이언트는 socket(), connect() 순서만 필요하다는 점에 유의하세요. 또한 서버는 수신 대기 중인 소켓에서 sendall()/recv() 를 하는 것이 아니라 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를 모두 지원해요. 서버 쪽은 사용 가능한 첫 번째 주소 패밀리를 수신 대기해요(둘 다 수신 대기해야 함). 대부분의 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 소켓으로 아주 간단한 네트워크 스니퍼를 작성하는 방법을 보여줘요. 이 예제는 인터페이스를 수정하려면 관리자 권한이 필요해요.

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 packets
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

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

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

다음 예제는 raw 소켓 프로토콜을 사용해 CAN 네트워크와 통신하기 위해 소켓 인터페이스를 사용하는 방법을 보여줘요. 대신 브로드캐스트 관리자 프로토콜로 CAN을 사용하려면 다음과 같이 소켓을 여세요.

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

소켓을 바인딩(CAN_RAW)하거나 연결(CAN_BCM)한 후에는 평소처럼 socket 객체에서 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)을 소개하는 내용은 다음 논문 참고.

Stuart Sechrest의 An Introductory 4.3BSD Interprocess Communication Tutorial

Samuel J. Leffler 등의 An Advanced 4.3BSD Interprocess Communication Tutorial

둘 다 UNIX Programmer's Manual, Supplementary Documents 1(섹션 PS1:7과 PS1:8)에 있어요. 다양한 소켓 관련 시스템 호출에 대한 플랫폼별 참조 자료도 소켓 의미론의 세부사항에 대한 귀중한 정보를 제공해요. Unix는 매뉴얼 페이지, Windows는 WinSock(또는 Winsock 2) 명세 참고. IPv6 준비 API에 대해서는 RFC 3493 "Basic Socket Interface Extensions for IPv6"를 참고할 수 있어요.

더 알아보기

socketserver — 네트워크 서버 작성을 단순화하는 클래스들.
ssl — socket 객체를 위한 TLS/SSL 래퍼.
select, selectors — 여러 소켓을 동시에 감시하는 I/O 멀티플렉싱.

`socket` — 저수준 네트워킹 인터페이스