`socket` — Gränssnitt för nätverk på låg nivå¶

Källkod: Lib/socket.py

Denna modul ger tillgång till BSD socket-gränssnittet. Den är tillgänglig på alla moderna Unix-system, Windows, MacOS och förmodligen ytterligare plattformar.

Anteckning

Vissa beteenden kan vara plattformsberoende, eftersom anrop görs till operativsystemets socket-API:er.

Tillgänglighet: not WASI.

Den här modulen fungerar inte eller är inte tillgänglig på WebAssembly. Se WebAssembly-plattformar för mer information.

Python-gränssnittet är en enkel translitterering av Unix systemanrop och biblioteksgränssnitt för sockets till Pythons objektorienterade stil: funktionen socket() returnerar ett socket-objekt vars metoder implementerar de olika systemanropen för sockets. Parametertyperna är på en något högre nivå än i C-gränssnittet: precis som med read() och write() operationer på Python-filer är buffertallokeringen vid mottagning automatisk och buffertlängden är implicit vid sändning.

Se även

Modul socketserver: Klasser som förenklar skrivandet av nätverksservrar.
Modul ssl: En TLS/SSL-wrapper för socket-objekt.

Uttagsfamiljer¶

Beroende på system och byggalternativ stöds olika sockelfamiljer av denna modul.

Det adressformat som krävs av ett visst socket-objekt väljs automatiskt utifrån den adressfamilj som angavs när socket-objektet skapades. Socketadresser representeras på följande sätt:

Adressen till en AF_UNIX-socket som är bunden till en filsystemnod representeras som en sträng med hjälp av filsystemets kodning och felhanteraren 'surrogateescape' (se PEP 383). En adress i Linux abstrakta namnrymd returneras som ett bytesliknande objekt med en inledande nollbyte; notera att uttag i denna namnrymd kan kommunicera med vanliga filsystemuttag, så program som är avsedda att köras på Linux kan behöva hantera båda typerna av adresser. En sträng eller ett bytesliknande objekt kan användas för båda typerna av adresser när det skickas som ett argument.

Ändrad i version 3.3: Tidigare antogs AF_UNIX socket-sökvägar använda UTF-8-kodning.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

Ett par (host, port) används för adressfamiljen AF_INET, där host är en sträng som representerar antingen ett värdnamn i internetdomännotation som 'daring.cwi.nl' eller en IPv4-adress som '100.50.200.5', och port är ett heltal.
- För IPv4-adresser accepteras två specialformer i stället för en värdadress: '' representerar INADDR_ANY, som används för att binda till alla gränssnitt, och strängen '<broadcast>' representerar INADDR_BROADCAST. Detta beteende är inte kompatibelt med IPv6, därför bör du undvika dessa om du avser att stödja IPv6 med dina Python-program.
För adressfamiljen AF_INET6 används en fyrdubbling (host, port, flowinfo, scope_id), där flowinfo och scope_id representerar medlemmarna sin6_flowinfo och sin6_scope_id i struct sockaddr_in6 i C. För modulmetoderna socket kan flowinfo och scope_id utelämnas bara för bakåtkompatibilitet. Observera dock att utelämnande av scope_id kan orsaka problem vid manipulering av scoped IPv6-adresser.

Ändrad i version 3.7: För multicast-adresser (med scope_id meningsfullt) får address inte innehålla delen %scope_id (eller zone id). Denna information är överflödig och kan med fördel utelämnas (rekommenderas).
AF_NETLINK sockets representeras som par (pid, groups).
Stöd för TIPC endast för Linux finns tillgängligt med hjälp av adressfamiljen AF_TIPC. TIPC är ett öppet, icke-IP-baserat nätverksprotokoll som är utformat för användning i klustrade datormiljöer. Adresser representeras av en tupel och fälten beror på adresstypen. Den allmänna tupelformen är (addr_type, v1, v2, v3 [, scope]), där:
- addr_type är en av TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, eller TIPC_ADDR_ID.
- scope är en av TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, och TIPC_NODE_SCOPE.
- Om addr_type är TIPC_ADDR_NAME, så är v1 servertypen, v2 portidentifieraren och v3 bör vara 0.
  
  Om addr_type är TIPC_ADDR_NAMESEQ, så är v1 servertypen, v2 det lägre portnumret och v3 det övre portnumret.
  
  Om addr_type är TIPC_ADDR_ID, så är v1 noden, v2 referensen och v3 ska sättas till 0.
En tupel (interface, ) används för adressfamiljen AF_CAN, där interface är en sträng som representerar ett nätverksgränssnittsnamn som 'can0'. Nätverksgränssnittsnamnet '' kan användas för att ta emot paket från alla nätverksgränssnitt i denna familj.
- CAN_ISOTP-protokollet kräver en tupel (interface, rx_addr, tx_addr) där båda tilläggsparametrarna är osignerade långa heltal som representerar en CAN-identifierare (standard eller utökad).
- CAN_J1939-protokollet kräver en tupel (interface, name, pgn, addr) där ytterligare parametrar är ett 64-bitars osignerat heltal som representerar ECU-namnet, ett 32-bitars osignerat heltal som representerar parametergruppnumret (PGN) och ett 8-bitars heltal som representerar adressen.
En sträng eller en tupel (id, unit) används för protokollet SYSPROTO_CONTROL i familjen PF_SYSTEM. Strängen är namnet på en kärnkontroll som använder ett dynamiskt tilldelat ID. Tupeln kan användas om ID och enhetsnummer för kärnkontrollen är kända eller om ett registrerat ID används.

Tillagd i version 3.3.
AF_BLUETOOTH stöder följande protokoll och adressformat:
- BTPROTO_L2CAP accepterar en tupel (bdaddr, psm[, cid[, bdaddr_type]]) där:
  - bdaddr är en sträng som anger Bluetooth-adressen.
  - psm är ett heltal som anger Protocol/Service Multiplexer.
  - cid är ett valfritt heltal som anger kanalidentifieraren. Om den inte anges är standardvärdet noll.
  - bdaddr_type är ett valfritt heltal som anger adresstypen; en av BDADDR_BREDR (standard), BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM.
  Ändrad i version 3.14: Fälten cid och bdaddr_type tillagda.
- BTPROTO_RFCOMM accepterar (bdaddr, channel) där bdaddr är Bluetooth-adressen som en sträng och channel är ett heltal.
- BTPROTO_HCI accepterar ett format som beror på ditt operativsystem.
  - På Linux accepterar den ett heltal device_id eller en tupel (device_id, [channel]) där device_id anger numret på Bluetooth-enheten och channel är ett valfritt heltal som anger HCI-kanalen (HCI_CHANNEL_RAW` som standard).
  - På FreeBSD, NetBSD och DragonFly BSD accepterar den bdaddr där bdaddr är Bluetooth-adressen som en sträng.
  Ändrad i version 3.2: Stöd för NetBSD och DragonFlyBSD har lagts till.
  
  Ändrad i version 3.13.3: Stöd för FreeBSD har lagts till.
  
  Ändrad i version 3.14: Lagt till fältet channel. device_id som inte är packat i en tupel accepteras nu.
- BTPROTO_SCO accepterar bdaddr där bdaddr är Bluetooth-adressen som en sträng eller ett bytes-objekt. (t.ex. '12:23:34:45:56:67' eller b'12:23:34:45:56:67')
  
  Ändrad i version 3.14: Stöd för FreeBSD har lagts till.
AF_ALG är ett socketbaserat gränssnitt för kärnkryptografi som endast används i Linux. En algoritmsockel konfigureras med en tuple av två till fyra element (typ, namn [, feat [, mask]]), där:
- type är algoritmtypen som en sträng, t.ex. aead, hash, skcipher eller rng.
- name är algoritmens namn och driftläge som en sträng, t.ex. sha256, hmac(sha256), cbc(aes) eller drbg_nopr_ctr_aes256.
- feat och mask är osignerade 32-bitars heltal.
Tillgänglighet: Linux >= 2.6.38.

Vissa algoritmtyper kräver nyare kärnor.

Tillagd i version 3.6.
AF_VSOCK tillåter kommunikation mellan virtuella maskiner och deras värdar. Socklarna representeras som en (CID, port)-tupel där kontext-ID eller CID och port är heltal.

Tillgänglighet: Linux >= 3.9

Se vsock(7)

Tillagd i version 3.7.
AF_PACKET är ett lågnivågränssnitt direkt till nätverksenheter. Adresserna representeras av tupeln (ifname, proto[, pkttype[, hatype[, addr]]]) där:
- ifname - Sträng som anger enhetens namn.
- proto - Ethernetprotokollets nummer. Kan vara ETH_P_ALL för att fånga alla protokoll, en av ETHERTYPE_*-konstanterna eller något annat Ethernet-protokollnummer.
- pkttype - Valfritt heltal som anger pakettyp:
  - PACKET_HOST (standard) - Paketet adresseras till den lokala värden.
  - PACKET_BROADCAST - Broadcast-paket i det fysiska lagret.
  - PACKET_MULTICAST - Paket som skickas till en multicastadress i det fysiska lagret.
  - PACKET_OTHERHOST - Paket till en annan värd som har fångats upp av en enhetsdrivrutin i promiscuous-läge.
  - PACKET_OUTGOING - Paket från den lokala värden som loopas tillbaka till ett paketuttag.
- hatype - Valfritt heltal som anger typen av ARP-hårdvaruadress.
- addr - Valfritt bytesliknande objekt som anger den fysiska hårdvaruadressen, vars tolkning beror på enheten.
Tillgänglighet: Linux >= 2.2.
AF_QIPCRTR är ett socketbaserat gränssnitt för Linux för kommunikation med tjänster som körs på samprocessorer i Qualcomm-plattformar. Adressfamiljen representeras som en (nod, port)-tupel där nod och port är icke-negativa heltal.

Tillgänglighet: Linux >= 4.7.

Tillagd i version 3.8.
IPPROTO_UDPLITE är en variant av UDP som låter dig ange vilken del av ett paket som täcks av kontrollsumman. Den lägger till två socket-alternativ som du kan ändra. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) ändrar hur stor del av utgående paket som täcks av kontrollsumman och self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) filtrerar bort paket som täcker för lite av sina data. I båda fallen bör length ligga i range(8, 2**16, 8).

En sådan socket bör konstrueras med socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) för IPv4 eller socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) för IPv6.

Tillgänglighet: Linux >= 2.6.20, FreeBSD >= 10.1

Tillagd i version 3.9.
AF_HYPERV är ett socketbaserat gränssnitt för Windows för kommunikation med Hyper-V-värdar och -gäster. Adressfamiljen representeras som en (vm_id, service_id)-tupel där vm_id och service_id är UUID-strängar.

vm_id är den virtuella maskinens identifierare eller en uppsättning kända VMID-värden om målet inte är en specifik virtuell maskin. Kända VMID-konstanter som definieras på socket är:
- HV_GUID_ZERO
- HV_GUID_BROADCAST
- HV_GUID_WILDCARD - Används för att binda på sig själv och acceptera anslutningar från alla partitioner.
- HV_GUID_CHILDREN - Används för att binda på sig själv och acceptera anslutning från underordnade partitioner.
- HV_GUID_LOOPBACK - Används som mål för sig själv.
- HV_GUID_PARENT - När den används som bindning accepteras anslutning från den överordnade partitionen. När den används som adressmål kommer den att ansluta till den överordnade partitionen.
service_id är tjänsteidentifieraren för den registrerade tjänsten.

Tillagd i version 3.12.

Om du använder ett värdnamn i host-delen av IPv4/v6-socketadressen kan programmet uppvisa ett icke-bestämbart beteende, eftersom Python använder den första adressen som returneras från DNS-upplösningen. Socketadressen kommer att lösas upp på olika sätt till en faktisk IPv4/v6-adress, beroende på resultaten från DNS-upplösningen och/eller värdkonfigurationen. För deterministiskt beteende använd en numerisk adress i host-delen.

Alla fel ger upphov till undantag. De normala undantagen för ogiltiga argumenttyper och när minnet är slut kan användas. Fel relaterade till socket- eller adresssemantik ger upphov till OSError eller en av dess underklasser.

Icke-blockerande läge stöds genom setblocking(). En generalisering av detta baserat på timeouts stöds genom settimeout().

Modulens innehåll¶

Modulen socket exporterar följande element.

Undantag¶

exception socket.error¶: Ett föråldrat alias för OSError.

Ändrad i version 3.3: Efter PEP 3151 gjordes denna klass till ett alias för OSError.

exception socket.herror¶: Detta undantag är en underklass till OSError och uppstår vid adressrelaterade fel, dvs. för funktioner som använder h_errno i POSIX C API, inklusive gethostbyname_ex() och gethostbyaddr(). Det medföljande värdet är ett par (h_errno, string) som representerar ett fel som returneras av ett biblioteksanrop. h_errno är ett numeriskt värde, medan sträng representerar beskrivningen av h_errno, som returneras av C-funktionen hstrerror().

Ändrad i version 3.3: Denna klass gjordes till en underklass av OSError.

exception socket.gaierror¶: Detta undantag, som är en underklass till OSError, uppstår vid adressrelaterade fel som orsakas av getaddrinfo() och getnameinfo(). Det medföljande värdet är ett par (error, string) som representerar ett fel som returneras av ett biblioteksanrop. string representerar beskrivningen av error, som returneras av C-funktionen gai_strerror(). Det numeriska error-värdet kommer att matcha en av EAI_*-konstanterna som definieras i den här modulen.

Ändrad i version 3.3: Denna klass gjordes till en underklass av OSError.

exception socket.timeout¶

Ett föråldrat alias för TimeoutError.

Detta undantag är en underklass till OSError och uppstår när en timeout inträffar på ett uttag som har timeouts aktiverade via ett tidigare anrop till settimeout() (eller implicit via setdefaulttimeout()). Det medföljande värdet är en sträng vars värde för närvarande alltid är ”timed out”.

Ändrad i version 3.3: Denna klass gjordes till en underklass av OSError.

Ändrad i version 3.10: Denna klass gjordes till ett alias för TimeoutError.

Konstanter¶

Konstanterna AF_* och SOCK_* är nu AddressFamily och SocketKind IntEnum samlingar.

Tillagd i version 3.4.

socket.AF_UNIX¶
socket.AF_INET¶
socket.AF_INET6¶: Dessa konstanter representerar de adress- (och protokoll-) familjer som används för det första argumentet till socket(). Om konstanten AF_UNIX inte är definierad stöds inte det här protokollet. Fler konstanter kan vara tillgängliga beroende på systemet.

socket.AF_UNSPEC¶: AF_UNSPEC betyder att getaddrinfo() ska returnera socketadresser för alla adressfamiljer (antingen IPv4, IPv6 eller någon annan) som kan användas.

socket.SOCK_STREAM¶
socket.SOCK_DGRAM¶
socket.SOCK_RAW¶
socket.SOCK_RDM¶
socket.SOCK_SEQPACKET¶: Dessa konstanter representerar de socket-typer som används för det andra argumentet till socket(). Fler konstanter kan vara tillgängliga beroende på systemet. (Endast SOCK_STREAM och SOCK_DGRAM verkar vara allmänt användbara)

socket.SOCK_CLOEXEC¶
socket.SOCK_NONBLOCK¶: Dessa två konstanter, om de definieras, kan kombineras med socket-typerna och gör att du kan ställa in vissa flaggor atomiskt (och därmed undvika eventuella tävlingsförhållanden och behovet av separata anrop).

Se även

Säker hantering av File Descriptor för en mer ingående förklaring.

Tillgänglighet: Linux >= 2.6.27.

Tillagd i version 3.2.

SO_*
socket.SOMAXCONN¶
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*: Många konstanter av dessa former, som finns dokumenterade i Unix-dokumentationen om sockets och/eller IP-protokollet, är också definierade i socket-modulen. De används i allmänhet som argument till metoderna setsockopt() och getsockopt() för socket-objekt. I de flesta fall definieras endast de symboler som finns definierade i Unix header-filer; för några få symboler anges standardvärden.

Ändrad i version 3.6: SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION lades till.

Ändrad i version 3.6.5: Lagt till stöd för TCP_FASTOPEN, TCP_KEEPCNT på Windows-plattformar när det finns tillgängligt.

Ändrad i version 3.7: TCP_NOTSENT_LOWAT lades till.

Lagt till stöd för TCP_KEEPIDLE, TCP_KEEPINTVL på Windows-plattformar när det finns tillgängligt.

Ändrad i version 3.10: IP_RECVTOS lades till. TCP_KEEPALIVE lades till. På MacOS kan denna konstant användas på samma sätt som TCP_KEEPIDLE används på Linux.

Ändrad i version 3.11: Lagt till TCP_CONNECTION_INFO. På MacOS kan denna konstant användas på samma sätt som TCP_INFO används på Linux och BSD.

Ändrad i version 3.12: Lagt till SO_RTABLE och SO_USER_COOKIE. På OpenBSD respektive FreeBSD kan dessa konstanter användas på samma sätt som SO_MARK används på Linux. Har även lagt till saknade TCP-socketalternativ från Linux: 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. Lagt till IP_PKTINFO, IP_UNBLOCK_SOURCE, IP_BLOCK_SOURCE, IP_ADD_SOURCE_MEMBERSHIP, IP_DROP_SOURCE_MEMBERSHIP.

Ändrad i version 3.13: Lagt till SO_BINDTOIFINDEX. På Linux kan denna konstant användas på samma sätt som SO_BINDTODEVICE, men med indexet för ett nätverksgränssnitt i stället för dess namn.

Ändrad i version 3.14: Lagt till saknade IP_FREEBIND, IP_RECVERR, IPV6_RECVERR, IP_RECVTTL och IP_RECVORIGDSTADDR på Linux.

Ändrad i version 3.14: Lagt till stöd för TCP_QUICKACK på Windows-plattformar när det finns tillgängligt.

socket.AF_CAN¶
socket.PF_CAN¶
SOL_CAN_*
CAN_*: Många konstanter av dessa former, som finns dokumenterade i Linux-dokumentationen, definieras också i socket-modulen.

Tillgänglighet: Linux >= 2.6.25, NetBSD >= 8.

Tillagd i version 3.3.

Ändrad i version 3.11: Stöd för NetBSD har lagts till.

Ändrad i version 3.14: Återställde saknade CAN_RAW_ERR_FILTER på Linux.

socket.CAN_BCM¶
CAN_BCM_*: CAN_BCM, i CAN-protokollfamiljen, är broadcast manager (BCM)-protokollet. Broadcast Manager-konstanter, som finns dokumenterade i Linux-dokumentationen, definieras också i socket-modulen.

Tillgänglighet: Linux >= 2.6.25.

Anteckning

Flaggan CAN_BCM_CAN_FD_FRAME är endast tillgänglig på Linux >= 4.8.

Tillagd i version 3.4.

socket.CAN_RAW_FD_FRAMES¶

Aktiverar stöd för CAN FD i ett CAN_RAW-uttag. Detta är avaktiverat som standard. Detta gör att din applikation kan skicka både CAN- och CAN FD-ramar, men du måste acceptera både CAN- och CAN FD-ramar när du läser från sockeln.

Denna konstant finns dokumenterad i Linux-dokumentationen.

Tillgänglighet: Linux >= 3.6.

Tillagd i version 3.5.

socket.CAN_RAW_JOIN_FILTERS¶

Sammanfogar de tillämpade CAN-filtren så att endast CAN-ramar som matchar alla givna CAN-filter skickas till användarutrymmet.

Denna konstant finns dokumenterad i Linux-dokumentationen.

Tillgänglighet: Linux >= 4.1.

Tillagd i version 3.9.

socket.CAN_ISOTP¶: CAN_ISOTP, i CAN-protokollfamiljen, är ISO-TP-protokollet (ISO 15765-2). ISO-TP-konstanter, dokumenterade i Linux-dokumentationen.

Tillgänglighet: Linux >= 2.6.25.

Tillagd i version 3.7.

socket.CAN_J1939¶: CAN_J1939, i CAN-protokollfamiljen, är SAE J1939-protokollet. J1939-konstanter, dokumenterade i Linux-dokumentationen.

Tillgänglighet: Linux >= 5.4.

Tillagd i version 3.9.

socket.AF_DIVERT¶
socket.PF_DIVERT¶: Dessa två konstanter, som finns dokumenterade i FreeBSD divert(4)-manualsidan, definieras också i socket-modulen.

Tillgänglighet: FreeBSD >= 14.0.

Tillagd i version 3.12.

socket.AF_PACKET¶
socket.PF_PACKET¶
PACKET_*: Många konstanter av dessa former, som finns dokumenterade i Linux-dokumentationen, definieras också i socket-modulen.

Tillgänglighet: Linux >= 2.2.

socket.ETH_P_ALL¶

ETH_P_ALL kan användas i socket-konstruktören som proto för AF_PACKET-familjen för att fånga alla paket, oavsett protokoll.

För mer information, se packet(7) manpage.

Tillgänglighet: Linux.

Tillagd i version 3.12.

socket.AF_RDS¶
socket.PF_RDS¶
socket.SOL_RDS¶
RDS_*: Många konstanter av dessa former, som finns dokumenterade i Linux-dokumentationen, definieras också i socket-modulen.

Tillgänglighet: Linux >= 2.6.30.

Tillagd i version 3.3.

socket.SIO_RCVALL¶
socket.SIO_KEEPALIVE_VALS¶
socket.SIO_LOOPBACK_FAST_PATH¶
RCVALL_*: Konstanter för Windows WSAIoctl(). Konstanterna används som argument till ioctl()-metoden för socket-objekt.

Ändrad i version 3.6: SIO_LOOPBACK_FAST_PATH lades till.

TIPC_*: TIPC-relaterade konstanter, som matchar de som exporteras av C socket API. Se TIPC-dokumentationen för mer information.

socket.AF_ALG¶
socket.SOL_ALG¶
ALG_*: Konstanter för Linux Kernel-kryptografi.

Tillgänglighet: Linux >= 2.6.38.

Tillagd i version 3.6.

socket.AF_VSOCK¶
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID¶
VMADDR*
SO_VM*: Konstanter för Linux host/guest-kommunikation.

Tillgänglighet: Linux >= 4.8.

Tillagd i version 3.7.

socket.AF_LINK¶: Tillgänglighet: BSD, macOS.

Tillagd i version 3.4.

socket.has_ipv6¶: Denna konstant innehåller ett booleskt värde som anger om IPv6 stöds på denna plattform.

socket.AF_BLUETOOTH¶
socket.BTPROTO_L2CAP¶
socket.BTPROTO_RFCOMM¶
socket.BTPROTO_HCI¶
socket.BTPROTO_SCO¶: Heltalskonstanter för användning med Bluetooth-adresser.

socket.BDADDR_ANY¶
socket.BDADDR_LOCAL¶: Dessa är strängkonstanter som innehåller Bluetooth-adresser med speciella betydelser. Till exempel kan BDADDR_ANY användas för att ange vilken adress som helst när du anger bindningsuttaget med BTPROTO_RFCOMM.

socket.BDADDR_BREDR¶
socket.BDADDR_LE_PUBLIC¶
socket.BDADDR_LE_RANDOM¶: Dessa konstanter beskriver Bluetooth-adresstypen när du binder eller ansluter ett BTPROTO_L2CAP-uttag.

Tillgänglighet: Linux, FreeBSD

Tillagd i version 3.14.

socket.SOL_RFCOMM¶

socket.SOL_L2CAP¶

socket.SOL_HCI¶

socket.SOL_SCO¶

socket.SOL_BLUETOOTH¶

Används i level-argumentet till metoderna setsockopt() och getsockopt() för Bluetooth-socketobjekt.

SOL_BLUETOOTH är endast tillgängligt på Linux. Andra konstanter är tillgängliga om det finns stöd för motsvarande protokoll.

SO_L2CAP_*

socket.L2CAP_LM¶

L2CAP_LM_*

SO_RFCOMM_*

RFCOMM_LM_*

SO_SCO_*

SO_BTH_*

BT_*

Används som argument för alternativnamn och värde i metoderna setsockopt() och getsockopt() för Bluetooth-socketobjekt.

BT_* och L2CAP_LM är endast tillgängliga på Linux. SO_BTH_* är endast tillgängliga på Windows. Andra konstanter kan finnas tillgängliga på Linux och olika BSD-plattformar.

Tillagd i version 3.14.

socket.HCI_FILTER¶
socket.HCI_TIME_STAMP¶
socket.HCI_DATA_DIR¶
socket.SO_HCI_EVT_FILTER¶
socket.SO_HCI_PKT_FILTER¶: Alternativnamn för användning med BTPROTO_HCI. Tillgänglighet och format för alternativvärdena beror på plattform.

Ändrad i version 3.14: Lagt till SO_HCI_EVT_FILTER och SO_HCI_PKT_FILTER på NetBSD och DragonFly BSD. Lagt till HCI_DATA_DIR på FreeBSD, NetBSD och DragonFly BSD.

socket.HCI_DEV_NONE¶: Värdet device_id som används för att skapa ett HCI-uttag som inte är specifikt för en enda Bluetooth-adapter.

Tillgänglighet: Linux

Tillagd i version 3.14.

socket.HCI_CHANNEL_RAW¶
socket.HCI_CHANNEL_USER¶
socket.HCI_CHANNEL_MONITOR¶
socket.HCI_CHANNEL_CONTROL¶
socket.HCI_CHANNEL_LOGGING¶: Möjliga värden för fältet channel i adressen BTPROTO_HCI.

Tillgänglighet: Linux

Tillagd i version 3.14.

socket.AF_QIPCRTR¶: Konstant för Qualcomms IPC-routerprotokoll, som används för att kommunicera med fjärrprocessorer som tillhandahåller tjänster.

Tillgänglighet: Linux >= 4.7.

socket.SCM_CREDS2¶
socket.LOCAL_CREDS¶
socket.LOCAL_CREDS_PERSISTENT¶: LOCAL_CREDS och LOCAL_CREDS_PERSISTENT kan användas med SOCK_DGRAM, SOCK_STREAM uttag, motsvarande Linux/DragonFlyBSD SO_PASSCRED, medan LOCAL_CREDS skickar inloggningsuppgifterna vid första läsningen, LOCAL_CREDS_PERSISTENT skickar för varje läsning, SCM_CREDS2 måste då användas för den senare för meddelandetypen.

Tillagd i version 3.11.

Tillgänglighet: FreeBSD.

socket.SO_INCOMING_CPU¶: Konstant för att optimera CPU-lokalisering, ska användas tillsammans med SO_REUSEPORT.

Tillagd i version 3.11.

Tillgänglighet: Linux >= 3.9

socket.SO_REUSEPORT_LB¶: Konstant för att aktivera duplicerade adress- och portbindningar med lastbalansering.

Tillagd i version 3.14.

Tillgänglighet: 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¶: Konstanter för Windows Hyper-V-sockets för värd/gäst-kommunikation.

Tillgänglighet: Windows.

Tillagd i version 3.12.

socket.ETHERTYPE_ARP¶
socket.ETHERTYPE_IP¶
socket.ETHERTYPE_IPV6¶
socket.ETHERTYPE_VLAN¶: IEEE 802.3 protokollnummer. konstanter.

Tillgänglighet: Linux, FreeBSD, macOS.

Tillagd i version 3.12.

socket.SHUT_RD¶
socket.SHUT_WR¶
socket.SHUT_RDWR¶: Dessa konstanter används av shutdown()-metoden för socket-objekt.

Tillgänglighet: not WASI.

Funktioner¶

Skapa uttag¶

Följande funktioner skapar alla socket-objekt.

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

Skapa en ny socket med hjälp av den angivna adressfamiljen, socket-typen och protokollnumret. Adressfamiljen bör vara AF_INET (standard), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET eller AF_RDS. Socket-typen bör vara SOCK_STREAM (standard), SOCK_DGRAM, SOCK_RAW eller kanske någon av de andra SOCK_-konstanterna. Protokollnumret är vanligtvis noll och kan utelämnas eller i det fall adressfamiljen är AF_CAN bör protokollet vara ett av CAN_RAW, CAN_BCM, CAN_ISOTP eller CAN_J1939.

Om fileno anges, hämtas värdena för family, type och proto automatiskt från den angivna filbeskrivaren. Automatisk detektering kan åsidosättas genom att anropa funktionen med uttryckliga family-, type- eller proto-argument. Detta påverkar endast hur Python representerar t.ex. returvärdet av socket.getpeername() men inte den faktiska OS-resursen. Till skillnad från socket.fromfd() kommer fileno att returnera samma socket och inte en dubblett. Detta kan hjälpa till att stänga ett fristående uttag med hjälp av socket.close().

Det nyskapade uttaget är non-inherititable.

Utlöser en auditing event socket.__new__ med argumenten self, family, type, protocol.

Ändrad i version 3.3: Familjen AF_CAN lades till. Familjen AF_RDS lades till.

Ändrad i version 3.4: Protokollet CAN_BCM har lagts till.

Ändrad i version 3.4: Den returnerade sockeln är nu inte ärftlig.

Ändrad i version 3.7: Protokollet CAN_ISOTP har lagts till.

Ändrad i version 3.7: När bitflaggorna SOCK_NONBLOCK eller SOCK_CLOEXEC tillämpas på type rensas de och socket.type kommer inte att återspegla dem. De skickas fortfarande till det underliggande systemets socket()-anrop. Därför är

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

kommer fortfarande att skapa ett icke-blockerande uttag på operativsystem som stöder SOCK_NONBLOCK, men sock.type kommer att sättas till socket.SOCK_STREAM.

Ändrad i version 3.9: Protokollet CAN_J1939 har lagts till.

Ändrad i version 3.10: Protokollet IPPROTO_MPTCP har lagts till.

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

Bygger ett par anslutna socket-objekt med hjälp av den angivna adressfamiljen, socket-typen och protokollnumret. Adressfamilj, sockeltyp och protokollnummer är som för funktionen socket() ovan. Standardfamiljen är AF_UNIX om den definieras på plattformen; annars är standard AF_INET.

De nyskapade uttagen är icke-ärftliga.

Ändrad i version 3.2: De returnerade socket-objekten stöder nu hela socket-API:et, snarare än en delmängd.

Ändrad i version 3.4: De återlämnade uttagen är nu icke-ärftliga.

Ändrad i version 3.5: Stöd för Windows har lagts till.

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

Anslut till en TCP-tjänst som lyssnar på internetadressen address (en 2-tupel (host, port)) och returnera socket-objektet. Detta är en funktion på högre nivå än socket.connect(): om host är ett icke-numeriskt värdnamn kommer den att försöka lösa det för både AF_INET och AF_INET6, och sedan försöka ansluta till alla möjliga adresser i tur och ordning tills en anslutning lyckas. Detta gör det enkelt att skriva klienter som är kompatibla med både IPv4 och IPv6.

Om den valfria parametern timeout anges kommer timeouten att ställas in på socket-instansen innan anslutningsförsök görs. Om ingen timeout anges används den globala standardinställningen för timeout som returneras av getdefaulttimeout().

Om source_address anges måste det vara en 2-tupel (host, port) som sockeln ska binda till som sin källadress innan den ansluter. Om host eller port är ’’ respektive 0 kommer OS standardbeteende att användas.

Om det inte går att skapa en anslutning uppstår ett undantag. Som standard är det undantaget från den sista adressen i listan. Om all_errors är True, är det en ExceptionGroup som innehåller felen i alla försök.

Ändrad i version 3.2: source_address har lagts till.

Ändrad i version 3.11: all_errors har lagts till.

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

Bekvämlighetsfunktion som skapar ett TCP-socket bundet till adress (en 2-tupel (host, port)) och returnerar socket-objektet.

family bör vara antingen AF_INET eller AF_INET6. backlog är den köstorlek som skickas till socket.listen(); om inget anges väljs ett rimligt standardvärde. reuse_port avgör om socket-alternativet SO_REUSEPORT ska ställas in.

Om dualstack_ipv6 är true, family är AF_INET6 och plattformen stöder det kommer uttaget att kunna acceptera både IPv4- och IPv6-anslutningar, annars kommer det att ge upphov till ValueError. De flesta POSIX-plattformar och Windows ska ha stöd för denna funktionalitet. När den här funktionen är aktiverad kommer den adress som returneras av socket.getpeername() när en IPv4-anslutning sker att vara en IPv6-adress som representeras av en IPv4-mappad IPv6-adress. Om dualstack_ipv6 är false kommer denna funktionalitet att uttryckligen inaktiveras på plattformar som aktiverar den som standard (t.ex. Linux). Denna parameter kan användas tillsammans med 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)

Anteckning

På POSIX-plattformar är socket-alternativet SO_REUSEADDR inställt för att omedelbart återanvända tidigare sockets som var bundna till samma adress och förblev i TIME_WAIT-tillstånd.

Tillagd i version 3.8.

socket.has_dualstack_ipv6()¶: Returnerar True om plattformen stöder skapandet av ett TCP-uttag som kan hantera både IPv4- och IPv6-anslutningar.

Tillagd i version 3.8.

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

Duplicera filbeskrivaren fd (ett heltal som returneras av ett filobjekts fileno()-metod) och bygg ett socket-objekt från resultatet. Adressfamilj, socket-typ och protokollnummer är samma som för funktionen socket() ovan. Filens deskriptor bör referera till en socket, men detta kontrolleras inte — efterföljande operationer på objektet kan misslyckas om filens deskriptor är ogiltig. Denna funktion behövs sällan, men kan användas för att hämta eller ställa in socket-alternativ på en socket som skickas till ett program som standardinmatning eller -utmatning (t.ex. en server som startas av Unix inet daemon). Sockeln antas vara i blockeringsläge.

Det nyskapade uttaget är non-inherititable.

Ändrad i version 3.4: Den returnerade sockeln är nu inte ärftlig.

socket.fromshare(data)¶: Instansiera ett uttag från data som erhållits från metoden socket.share(). Uttaget antas vara i blockeringsläge.

Tillgänglighet: Windows.

Tillagd i version 3.3.

socket.SocketType¶: Detta är ett Python-typobjekt som representerar objekttypen socket. Det är samma sak som type(socket(...)).

Övriga funktioner¶

Modulen socket erbjuder också olika nätverksrelaterade tjänster:

socket.close(fd)¶: Stäng en filbeskrivare för en socket. Detta är som os.close(), men för sockets. På vissa plattformar (mest märkbart Windows) fungerar inte os.close() för socket-filbeskrivare.

Tillagd i version 3.7.

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

Denna funktion omsluter C-funktionen getaddrinfo i det underliggande systemet.

Översätter host/port-argumentet till en sekvens av 5-tuples som innehåller alla nödvändiga argument för att skapa en socket som är ansluten till den tjänsten. host är ett domännamn, en strängrepresentation av en IPv4/v6-adress eller None. port är ett strängnamn för en tjänst, t.ex. 'http', ett numeriskt portnummer eller None. Genom att ange None som värde för host och port kan du ange NULL till det underliggande C API:et.

Argumenten family, type och proto kan anges som tillval för att ge alternativ och begränsa listan med adresser som returneras. Använd deras standardvärden (AF_UNSPEC, 0 respektive 0) för att inte begränsa resultaten. Se anmärkningen nedan för mer information.

Argumentet flags kan vara en eller flera av AI_*-konstanterna och påverkar hur resultaten beräknas och returneras. Exempelvis kommer AI_NUMERICHOST att inaktivera domännamnsupplösning och ge upphov till ett fel om host är ett domännamn.

Funktionen returnerar en lista med 5-tuples med följande struktur:

(family, type, proto, canonname, sockaddr)

I dessa tupler är family, type, proto alla heltal och är avsedda att skickas till funktionen socket(). canonname kommer att vara en sträng som representerar det kanoniska namnet på host om AI_CANONNAME är en del av flags-argumentet; annars kommer canonname att vara tomt. sockaddr är en tupel som beskriver en socketadress, vars format beror på den returnerade familjen (en (adress, port) 2-tupel för AF_INET, en (adress, port, flowinfo, scope_id) 4-tupel för AF_INET6), och är avsedd att skickas till metoden socket.connect().

Anteckning

Om du tänker använda resultaten från getaddrinfo() för att skapa ett uttag (i stället för att t.ex. hämta canonname) bör du överväga att begränsa resultaten efter typ (t.ex. SOCK_STREAM eller SOCK_DGRAM) och/eller proto (t.ex. IPPROTO_TCP eller IPPROTO_UDP) som ditt program kan hantera.

Beteendet med standardvärden för family, type, proto och flags är systemspecifikt.

Många system (t.ex. de flesta Linux-konfigurationer) returnerar en sorterad lista över alla matchande adresser. Dessa adresser bör i allmänhet provas i tur och ordning tills en anslutning lyckas (eventuellt parallellt, t.ex. med hjälp av en Happy Eyeballs-algoritm). I dessa fall kan en begränsning av typ och/eller proto bidra till att eliminera misslyckade eller oanvändbara anslutningsförsök.

Vissa system returnerar dock bara en enda adress. (Detta har t.ex. rapporterats för Solaris- och AIX-konfigurationer.) På dessa system kan man genom att begränsa type och/eller proto säkerställa att adressen är användbar.

Utlöser en auditing event socket.getaddrinfo med argumenten host, port, family, type, protocol.

Följande exempel hämtar adressinformation för en hypotetisk TCP-anslutning till example.org på port 80 (resultaten kan skilja sig åt i ditt system om IPv6 inte är aktiverat):

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

Ändrad i version 3.2: parametrar kan nu skickas med hjälp av nyckelordsargument.

Ändrad i version 3.7: för IPv6 multicast-adresser kommer strängen som representerar en adress inte att innehålla delen %scope_id.

socket.getfqdn([name])¶: Returnerar ett fullständigt kvalificerat domännamn för namn. Om name utelämnas eller är tomt tolkas det som den lokala värden. För att hitta det fullständigt kvalificerade namnet kontrolleras det värdnamn som returneras av gethostbyaddr(), följt av alias för värden, om sådana finns. Det första namnet som innehåller en punkt väljs. Om inget fullständigt kvalificerat domännamn finns tillgängligt och name angavs returneras det oförändrat. Om name var tomt eller lika med '0.0.0.0' returneras värdnamnet från gethostname().

socket.gethostbyname(hostname)¶

Översätter ett värdnamn till IPv4-adressformat. IPv4-adressen returneras som en sträng, t.ex. '100.50.200.5'. Om värdnamnet i sig är en IPv4-adress returneras den oförändrad. Se gethostbyname_ex() för ett mer komplett gränssnitt. gethostbyname() stöder inte IPv6-namnupplösning, och getaddrinfo() bör användas istället för IPv4/v6 dual stack-stöd.

Utlöser en auditing event socket.gethostbyname med argumentet hostname.

Tillgänglighet: not WASI.

socket.gethostbyname_ex(hostname)¶

Översätter ett värdnamn till IPv4-adressformat, utökat gränssnitt. Returnerar en 3-tupel (hostname, aliaslist, ipaddrlist) där hostname är värdens primära värdnamn, aliaslist är en (eventuellt tom) lista med alternativa värdnamn för samma adress och ipaddrlist är en lista med IPv4-adresser för samma gränssnitt på samma värd (ofta men inte alltid en enda adress). gethostbyname_ex() har inte stöd för IPv6-namnupplösning och getaddrinfo() bör användas istället för IPv4/v6 dual stack-stöd.

Utlöser en auditing event socket.gethostbyname med argumentet hostname.

Tillgänglighet: not WASI.

socket.gethostname()¶

Returnerar en sträng som innehåller värdnamnet på den maskin där Python-tolken körs för närvarande.

Utlöser en auditing event socket.gethostname utan argument.

Observera: gethostname() returnerar inte alltid det fullständigt kvalificerade domännamnet; använd getfqdn() för det.

Tillgänglighet: not WASI.

socket.gethostbyaddr(ip_address)¶

Returnerar en 3-tupel (hostname, aliaslist, ipaddrlist) där hostname är det primära värdnamnet som svarar på den angivna ip_address, aliaslist är en (eventuellt tom) lista över alternativa värdnamn för samma adress och ipaddrlist är en lista över IPv4/v6-adresser för samma gränssnitt på samma värd (innehåller troligen bara en enda adress). För att hitta det fullständigt kvalificerade domännamnet, använd funktionen getfqdn(). gethostbyaddr() stöder både IPv4 och IPv6.

Utlöser en auditing event socket.gethostbyaddr med argumentet ip_address.

Tillgänglighet: not WASI.

socket.getnameinfo(sockaddr, flags)¶

Översätter en socketadress sockaddr till en 2-tupel (host, port). Beroende på inställningarna i flags kan resultatet innehålla ett fullständigt kvalificerat domännamn eller en numerisk adressrepresentation i host. På samma sätt kan port innehålla en sträng med ett portnamn eller ett numeriskt portnummer.

För IPv6-adresser läggs %scope_id till värddelen om sockaddr innehåller meningsfulla scope_id. Vanligtvis händer detta för multicast-adresser.

För mer information om flags kan du läsa getnameinfo(3).

Utlöser en auditing event socket.getnameinfo med argumentet sockaddr.

Tillgänglighet: not WASI.

socket.getprotobyname(protocolname)¶: Översätt ett internetprotokollnamn (t.ex. 'icmp') till en konstant som kan användas som det (valfria) tredje argumentet till funktionen socket(). Detta behövs vanligtvis bara för socklar som öppnas i ”raw”-läge (SOCK_RAW); för de normala socketlägena väljs rätt protokoll automatiskt om protokollet utelämnas eller är noll.

Tillgänglighet: not WASI.

socket.getservbyname(servicename[, protocolname])¶

Översätter ett namn på en internettjänst och ett protokollnamn till ett portnummer för den tjänsten. Det valfria protokollnamnet, om det anges, bör vara 'tcp' eller 'udp', annars kommer alla protokoll att matcha.

Utlöser en auditing event socket.getservbyname med argumenten servicename, protocolname.

Tillgänglighet: not WASI.

socket.getservbyport(port[, protocolname])¶

Översätter ett internetportnummer och ett protokollnamn till ett servicenamn för den tjänsten. Det valfria protokollnamnet, om det anges, bör vara 'tcp' eller 'udp', annars kommer alla protokoll att matcha.

Utlöser en auditing event socket.getservbyport med argumenten port, protocolname.

Tillgänglighet: not WASI.

socket.ntohl(x)¶: Konverterar 32-bitars positiva heltal från nätverkets till värddatorns byteordning. På maskiner där värdbyteordningen är densamma som nätverksbyteordningen är detta ett no-op; annars utförs en swapoperation på 4 byte.

socket.ntohs(x)¶: Konvertera 16-bitars positiva heltal från nätverkets byteordning till värddatorns byteordning. På maskiner där värdbyteordningen är densamma som nätverksbyteordningen är detta ett no-op; annars utförs en 2 byte swap-operation.

Ändrad i version 3.10: Utlöser OverflowError om x inte ryms i ett 16-bitars osignerat heltal.

socket.htonl(x)¶: Konverterar 32-bitars positiva heltal från värd- till nätverksbyteordning. På maskiner där värdbyteordningen är densamma som nätverksbyteordningen är detta en no-op; annars utförs en swapoperation på 4 byte.

socket.htons(x)¶: Konverterar 16-bitars positiva heltal från värd- till nätverksbyteordning. På maskiner där värdbyteordningen är densamma som nätverksbyteordningen är detta en no-op; annars utförs en 2 byte swap-operation.

Ändrad i version 3.10: Utlöser OverflowError om x inte ryms i ett 16-bitars osignerat heltal.

socket.inet_aton(ip_string)¶

Konverterar en IPv4-adress från strängformat med prickade kvadrater (t.ex. ’123.45.67.89’) till 32-bitars packat binärt format, som ett bytesobjekt med fyra tecken i längd. Detta är användbart när du pratar med ett program som använder standard C-biblioteket och behöver objekt av typen in_addr, vilket är C-typen för det 32-bitars packade binära format som denna funktion returnerar.

inet_aton() accepterar även strängar med mindre än tre punkter; se Unix manualsida inet(3) för detaljer.

Om IPv4-adresssträngen som skickas till denna funktion är ogiltig, kommer OSError att uppstå. Observera att exakt vad som är giltigt beror på den underliggande C-implementeringen av inet_aton().

inet_aton() har inte stöd för IPv6 och inet_pton() bör användas istället för stöd för IPv4/v6 dual stack.

socket.inet_ntoa(packed_ip)¶

Konverterar en 32-bitars packad IPv4-adress (ett fyra byte långt bytes-like object) till dess standardrepresentation i form av en sträng med prickade kvadrater (t.ex. ’123.45.67.89’). Detta är användbart när du pratar med ett program som använder standard C-biblioteket och behöver objekt av typen in_addr, vilket är C-typen för 32-bitars packade binära data som den här funktionen tar som argument.

Om byte-sekvensen som skickas till den här funktionen inte är exakt 4 byte lång, kommer OSError att visas. inet_ntoa() stöder inte IPv6, och inet_ntop() bör användas istället för IPv4/v6 dual stack-stöd.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

socket.inet_pton(address_family, ip_string)¶

Konvertera en IP-adress från dess familjespecifika strängformat till ett packat, binärt format. inet_pton() är användbart när ett bibliotek eller nätverksprotokoll kräver ett objekt av typen in_addr (liknande inet_aton()) eller in6_addr.

Värden som stöds för address_family är för närvarande AF_INET och AF_INET6. Om IP-adresssträngen ip_string är ogiltig kommer OSError att visas. Observera att exakt vad som är giltigt beror på både värdet på address_family och den underliggande implementationen av inet_pton().

Tillgänglighet: Unix, Windows.

Ändrad i version 3.4: Windows-stöd har lagts till

socket.inet_ntop(address_family, packed_ip)¶

Konverterar en packad IP-adress (ett bytesliknande objekt med ett visst antal byte) till dess standardiserade, familjespecifika strängrepresentation (t.ex. '7.10.0.5' eller '5aef:2b::8'). inet_ntop() är användbart när ett bibliotek eller nätverksprotokoll returnerar ett objekt av typen in_addr (liknande inet_ntoa()) eller in6_addr.

Värden som stöds för address_family är för närvarande AF_INET och AF_INET6. Om bytesobjektet packed_ip inte har rätt längd för den angivna adressfamiljen, kommer ValueError att uppstå. OSError uppstår för fel från anropet till inet_ntop().

Tillgänglighet: Unix, Windows.

Ändrad i version 3.4: Windows-stöd har lagts till

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

socket.CMSG_LEN(length)¶: Returnerar den totala längden, utan efterföljande utfyllnad, av ett tilläggsdataobjekt med tillhörande data av den angivna längden. Detta värde kan ofta användas som buffertstorlek för recvmsg() för att ta emot ett enda objekt med tillhörande data, men RFC 3542 kräver att portabla applikationer använder CMSG_SPACE() och därmed inkluderar utrymme för utfyllnad, även när objektet kommer att vara det sista i bufferten. Utlöser OverflowError om length ligger utanför det tillåtna värdeintervallet.

Tillgänglighet: Unix, not WASI.

De flesta Unix-plattformar.

Tillagd i version 3.3.

socket.CMSG_SPACE(length)¶

Returnerar den buffertstorlek som behövs för att recvmsg() ska kunna ta emot ett tilläggsdataobjekt med tillhörande data av den angivna längden, tillsammans med eventuell efterföljande utfyllnad. Det buffertutrymme som behövs för att ta emot flera objekt är summan av CMSG_SPACE()-värdena för deras associerade datalängder. Utlöser OverflowError om length ligger utanför det tillåtna värdeintervallet.

Observera att vissa system kan stödja tilläggsdata utan att tillhandahålla denna funktion. Observera också att en inställning av buffertstorleken med hjälp av resultaten från denna funktion kanske inte exakt begränsar den mängd tilläggsdata som kan tas emot, eftersom ytterligare data kan rymmas i utfyllnadsområdet.

Tillgänglighet: Unix, not WASI.

de flesta Unix-plattformar.

Tillagd i version 3.3.

socket.getdefaulttimeout()¶: Returnerar standardtimeout i sekunder (float) för nya socket-objekt. Ett värde på None anger att nya socket-objekt inte har någon timeout. När socket-modulen importeras första gången är standardvärdet None.

socket.setdefaulttimeout(timeout)¶: Ställ in standardtimeout i sekunder (float) för nya socket-objekt. När socket-modulen importeras första gången är standardvärdet None. Se settimeout() för möjliga värden och deras respektive betydelser.

socket.sethostname(name)¶

Ställ in maskinens värdnamn till namn. Detta kommer att ge upphov till ett OSError om du inte har tillräckliga rättigheter.

Utlöser en auditing event socket.sethostname med argumentet name.

Tillgänglighet: Unix, not Android.

Tillagd i version 3.3.

socket.if_nameindex()¶

Returnerar en lista med information om nätverksgränssnitt (index int, namnsträng). OSError om systemanropet misslyckas.

Tillgänglighet: Unix, Windows, not WASI.

Tillagd i version 3.3.

Ändrad i version 3.8: Stöd för Windows har lagts till.

Anteckning

I Windows har nätverksgränssnitten olika namn i olika sammanhang (alla namn är exempel):

UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}
name: ethernet_32770
friendly name: vEthernet (nat)
description: Hyper-V Virtual Ethernet Adapter

Denna funktion returnerar namn av den andra formen från listan, ethernet_32770 i detta exempel.

socket.if_nametoindex(if_name)¶: Returnerar ett indexnummer för ett nätverksgränssnitt som motsvarar ett gränssnittsnamn. OSError om det inte finns något gränssnitt med det angivna namnet.

Tillgänglighet: Unix, Windows, not WASI.

Tillagd i version 3.3.

Ändrad i version 3.8: Stöd för Windows har lagts till.

Se även

”Interface name” är ett namn som dokumenterats i if_nameindex().

socket.if_indextoname(if_index)¶: Returnerar ett nätverksgränssnittsnamn som motsvarar ett gränssnittsindexnummer. OSError om det inte finns något gränssnitt med angivet index.

Tillgänglighet: Unix, Windows, not WASI.

Tillagd i version 3.3.

Ändrad i version 3.8: Stöd för Windows har lagts till.

Se även

”Interface name” är ett namn som dokumenterats i if_nameindex().

socket.send_fds(sock, buffers, fds[, flags[, address]])¶: Skicka listan med filbeskrivare fds över ett AF_UNIX-socket sock. Parametern fds är en sekvens av filbeskrivare. Se sendmsg() för dokumentation av dessa parametrar.

Tillgänglighet: Unix, not WASI.

Unix-plattformar som stöder sendmsg() och SCM_RIGHTS mekanism.

Tillagd i version 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])¶: Tar emot upp till maxfds filbeskrivare från en AF_UNIX socket sock. Returnerar (msg, list(fds), flags, addr). Se recvmsg() för dokumentation av dessa parametrar.

Tillgänglighet: Unix, not WASI.

Unix-plattformar som stöder recvmsg() och SCM_RIGHTS mekanism.

Tillagd i version 3.9.

Anteckning

Eventuella avkortade heltal i slutet av listan över filbeskrivare.

Socket-objekt¶

Socket-objekt har följande metoder. Med undantag för makefile() motsvarar dessa Unix systemanrop som är tillämpliga på sockets.

Ändrad i version 3.2: Stöd för protokollet context manager har lagts till. Att avsluta kontexthanteraren är likvärdigt med att anropa close().

socket.accept()¶

Acceptera en anslutning. Sockeln måste vara bunden till en adress och lyssna efter anslutningar. Returvärdet är ett par (conn, address) där conn är ett nytt socketobjekt som kan användas för att skicka och ta emot data på anslutningen, och address är adressen som är bunden till sockeln i andra änden av anslutningen.

Det nyskapade uttaget är non-inherititable.

Ändrad i version 3.4: Uttaget är nu icke-ärftligt.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

socket.bind(address)¶

Binda uttaget till adress. Uttaget får inte redan vara bundet. (Formatet på adress beror på adressfamiljen — se ovan)

Utlöser en auditing event socket.bind med argumenten self, address.

Tillgänglighet: not WASI.

socket.close()¶

Markera uttaget som stängt. Den underliggande systemresursen (t.ex. en filbeskrivare) stängs också när alla filobjekt från makefile() stängs. När det händer kommer alla framtida operationer på socket-objektet att misslyckas. Fjärränden kommer inte att ta emot några fler data (efter att köade data har spolats).

Socklar stängs automatiskt när de samlas in, men det rekommenderas att close() dem explicit, eller att använda ett with-slutord runt dem.

Ändrad i version 3.6: OSError tas nu upp om ett fel uppstår när det underliggande close()-anropet görs.

Anteckning

close() frigör den resurs som är kopplad till en anslutning men stänger inte nödvändigtvis anslutningen omedelbart. Om du vill stänga anslutningen i rätt tid, anropa shutdown() före close().

socket.connect(address)¶

Anslut till en fjärransluten socket på adress. (Formatet på adress beror på adressfamiljen — se ovan)

Om anslutningen avbryts av en signal väntar metoden tills anslutningen är klar, eller ger upphov till ett TimeoutError vid timeout, om signalhanteraren inte ger upphov till ett undantag och uttaget är blockerande eller har en timeout. För icke-blockerande uttag ger metoden upphov till ett InterruptedError-undantag om anslutningen avbryts av en signal (eller det undantag som signalhanteraren ger upphov till).

Utlöser en auditing event socket.connect med argumenten self, address.

Ändrad i version 3.5: Metoden väntar nu tills anslutningen är klar istället för att skapa ett InterruptedError-undantag om anslutningen avbryts av en signal, signalhanteraren inte skapar ett undantag och uttaget blockeras eller har en timeout (se PEP 475 för motivering).

Tillgänglighet: not WASI.

socket.connect_ex(address)¶

Som connect(address), men returnerar en felindikator istället för att skapa ett undantag för fel som returneras av anropet connect() på C-nivå (andra problem, t.ex. ”host not found”, kan fortfarande skapa undantag). Felindikatorn är 0 om operationen lyckades, annars värdet på variabeln errno. Detta är användbart för att stödja t.ex. asynkrona anslutningar.

Utlöser en auditing event socket.connect med argumenten self, address.

Tillgänglighet: not WASI.

socket.detach()¶: Sätter socket-objektet i stängt tillstånd utan att faktiskt stänga den underliggande filbeskrivaren. Fildeskriptorn returneras och kan återanvändas för andra ändamål.

Tillagd i version 3.2.

socket.dup()¶

Duplicera uttaget.

Det nyskapade uttaget är non-inherititable.

Ändrad i version 3.4: Uttaget är nu icke-ärftligt.

Tillgänglighet: not WASI.

socket.fileno()¶

Returnerar socketens filbeskrivare (ett litet heltal), eller -1 om den misslyckas. Detta är användbart med select.select().

Under Windows kan det lilla heltal som returneras av denna metod inte användas där en filbeskrivare kan användas (t.ex. os.fdopen()). Unix har inte denna begränsning.

socket.get_inheritable()¶: Hämta inheritable flag för socketens filbeskrivare eller socketens handtag: True om sockeln kan ärvas i underordnade processer, False om den inte kan det.

Tillagd i version 3.4.

socket.getpeername()¶: Returnerar den fjärradress som uttaget är anslutet till. Detta är till exempel användbart för att ta reda på portnumret för en fjärransluten IPv4/v6-socket. (Formatet på den adress som returneras beror på adressfamiljen — se ovan) På vissa system stöds inte denna funktion.

socket.getsockname()¶: Returnerar socketens egen adress. Detta är till exempel användbart för att ta reda på portnumret för ett IPv4/v6-uttag. (Formatet på den adress som returneras beror på adressfamiljen — se ovan)

socket.getsockopt(level, optname[, buflen])¶: Returnerar värdet för det angivna socket-alternativet (se Unix man-sida getsockopt(2)). De symboliska konstanter som behövs (SO_* etc.) definieras i den här modulen. Om buflen saknas antas ett heltalsalternativ och dess heltalsvärde returneras av funktionen. Om buflen finns anger den den maximala längden på den buffert som används för att ta emot alternativet, och denna buffert returneras som ett bytesobjekt. Det är upp till den som anropar att avkoda innehållet i bufferten (se den valfria inbyggda modulen struct för ett sätt att avkoda C-strukturer som kodats som bytesträngar).

Tillgänglighet: not WASI.

socket.getblocking()¶

Returnerar True om uttaget är i blockeringsläge, False om det är i icke-blockeringsläge.

Detta är likvärdigt med att kontrollera socket.gettimeout() != 0.

Tillagd i version 3.7.

socket.gettimeout()¶: Returnerar timeout i sekunder (float) associerad med socket-operationer, eller None om ingen timeout är inställd. Detta återspeglar det senaste anropet till setblocking() eller settimeout().

socket.ioctl(control, option)¶

Metoden ioctl() är ett begränsat gränssnitt till systemgränssnittet WSAIoctl. Mer information finns i Win32-dokumentationen.

På andra plattformar kan de generiska funktionerna fcntl.fcntl() och fcntl.ioctl() användas; de accepterar ett socket-objekt som sitt första argument.

För närvarande stöds endast följande kontrollkoder: SIO_RCVALL, SIO_KEEPALIVE_VALS och SIO_LOOPBACK_FAST_PATH.

Tillgänglighet: Windows

Ändrad i version 3.6: SIO_LOOPBACK_FAST_PATH lades till.

socket.listen([backlog])¶: Gör det möjligt för en server att acceptera anslutningar. Om backlog anges måste det vara minst 0 (om det är lägre sätts det till 0); det anger antalet oaccepterade anslutningar som systemet tillåter innan nya anslutningar nekas. Om det inte specificeras väljs ett rimligt standardvärde.

Tillgänglighet: not WASI.

Ändrad i version 3.5: Parametern backlog är nu valfri.

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

Returnerar ett filobjekt associerat med uttaget. Den exakta typen som returneras beror på de argument som ges till makefile(). Dessa argument tolkas på samma sätt som av den inbyggda funktionen open(), förutom att de enda mode-värden som stöds är 'r' (standard), 'w', 'b' eller en kombination av dessa.

Sockeln måste vara i blockeringsläge; den kan ha en timeout, men filobjektets interna buffert kan hamna i ett inkonsekvent tillstånd om en timeout inträffar.

Om du stänger filobjektet som returneras av makefile() stängs inte den ursprungliga sockeln om inte alla andra filobjekt har stängts och socket.close() har anropats på socketobjektet.

Anteckning

I Windows kan det filliknande objekt som skapas av makefile() inte användas där ett filobjekt med en filbeskrivare förväntas, t.ex. strömargumenten i subprocess.Popen().

socket.recv(bufsize[, flags])¶: Ta emot data från uttaget. Returvärdet är ett bytes-objekt som representerar den mottagna datan. Den maximala mängden data som kan tas emot på en gång anges av bufsize. Ett returnerat tomt bytes-objekt indikerar att klienten har kopplat från. Se Unix-manualsidan recv(2) för betydelsen av det valfria argumentet flags; det är noll som standard.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

socket.recvfrom(bufsize[, flags])¶: Tar emot data från uttaget. Returvärdet är ett par (bytes, address) där bytes är ett bytesobjekt som representerar de mottagna data och address är adressen till det uttag som skickar data. Se Unix-manualsidan recv(2) för betydelsen av det valfria argumentet flags; det är noll som standard. (Formatet på address beror på adressfamiljen — se ovan)

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

Ändrad i version 3.7: För IPv6-adresser för multicast innehåller den första posten i address inte längre delen %scope_id. För att få en fullständig IPv6-adress, använd getnameinfo().

socket.recvmsg(bufsize[, ancbufsize[, flags]])¶

Tar emot normal data (upp till bufsize bytes) och tilläggsdata från sockeln. Argumentet ancbufsize anger storleken i byte på den interna buffert som används för att ta emot tilläggsdata; standardvärdet är 0, vilket innebär att inga tilläggsdata tas emot. Lämpliga buffertstorlekar för tilläggsdata kan beräknas med hjälp av CMSG_SPACE() eller CMSG_LEN(), och objekt som inte ryms i bufferten kan avkortas eller kasseras. Argumentet flags är 0 som standard och har samma betydelse som för recv().

Returvärdet är en 4-tupel: (data, ancdata, msg_flags, address). Objektet data är ett bytes-objekt som innehåller de icke-ancillära data som mottagits. Objektet ancdata är en lista med noll eller flera tupler (cmsg_level, cmsg_type, cmsg_data) som representerar de mottagna tilläggsdata (kontrollmeddelanden): cmsg_level och cmsg_type är heltal som anger protokollnivån respektive den protokollspecifika typen, och cmsg_data är ett bytes-objekt som innehåller tillhörande data. Objektet msg_flags är det bitvisa ELLER av olika flaggor som anger villkor för det mottagna meddelandet; se systemdokumentationen för mer information. Om det mottagande uttaget inte är anslutet är address adressen till det sändande uttaget, om sådan finns; annars är dess värde ospecificerat.

På vissa system kan sendmsg() och recvmsg() användas för att skicka filbeskrivare mellan processer över en AF_UNIX-socket. När denna funktion används (den är ofta begränsad till SOCK_STREAM-socklar), kommer recvmsg() att returnera, i sina tilläggsdata, objekt av formen (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds), där fds är ett bytes-objekt som representerar de nya filbeskrivarna som en binär array av den ursprungliga C-typen int. Om recvmsg() ger upphov till ett undantag efter att systemanropet har returnerats, kommer det först att försöka stänga alla filbeskrivare som har tagits emot via denna mekanism.

Vissa system anger inte den avkortade längden på tilläggsdata som bara delvis har tagits emot. Om ett objekt verkar sträcka sig längre än slutet av bufferten, kommer recvmsg() att utfärda en RuntimeWarning, och kommer att returnera den del av det som finns i bufferten förutsatt att det inte har avkortats före början av dess tillhörande data.

På system som stöder SCM_RIGHTS-mekanismen tar följande funktion emot upp till maxfds filbeskrivare och returnerar meddelandedata och en lista som innehåller beskrivarna (samtidigt som oväntade förhållanden ignoreras, t.ex. att orelaterade kontrollmeddelanden tas emot). Se även 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)

Tillgänglighet: Unix.

De flesta Unix-plattformar.

Tillagd i version 3.3.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

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

Tar emot normala data och tilläggsdata från sockeln och beter sig som recvmsg() skulle göra, men sprider ut de data som inte tillhörancillary i en serie buffertar istället för att returnera ett nytt bytes-objekt. Argumentet buffers måste vara en iterabel av objekt som exporterar skrivbara buffertar (t.ex. bytearray-objekt); dessa kommer att fyllas med successiva bitar av de icke-ancillära data tills allt har skrivits eller det inte finns några fler buffertar. Operativsystemet kan sätta en gräns (sysconf() värde SC_IOV_MAX) på antalet buffertar som kan användas. Argumenten ancbufsize och flags har samma betydelse som för recvmsg().

Returvärdet är en 4-tupel: (nbytes, ancdata, msg_flags, address), där nbytes är det totala antalet byte av icke-ancillär data som skrivs in i buffertarna, och ancdata, msg_flags och address är desamma som för recvmsg().

Exempel:

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

Tillgänglighet: Unix.

De flesta Unix-plattformar.

Tillagd i version 3.3.

socket.recvfrom_into(buffer[, nbytes[, flags]])¶: Tar emot data från sockeln och skriver in dem i buffer istället för att skapa en ny bytestring. Returvärdet är ett par (nbytes, address) där nbytes är antalet mottagna byte och address är adressen till den socket som skickar data. Se Unix-manualsidan recv(2) för betydelsen av det valfria argumentet flags; det är noll som standard. (Formatet på address beror på adressfamiljen — se ovan)

socket.recv_into(buffer[, nbytes[, flags]])¶: Tar emot upp till nbytes byte från sockeln och lagrar data i en buffert i stället för att skapa en ny bytestring. Om nbytes inte anges (eller 0), tas upp till den storlek som finns tillgänglig i den angivna bufferten. Returnerar antalet mottagna byte. Se Unix-manualsidan recv(2) för betydelsen av det valfria argumentet flags; det är noll som standard.

socket.send(bytes[, flags])¶: Skicka data till uttaget. Uttaget måste vara anslutet till ett fjärruttag. Det valfria argumentet flags har samma betydelse som för recv() ovan. Returnerar antalet bytes som skickats. Applikationer är ansvariga för att kontrollera att alla data har skickats; om endast en del av data har skickats måste applikationen försöka leverera resterande data. För ytterligare information om detta ämne, se HOWTO för programmering av socket.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

socket.sendall(bytes[, flags])¶: Skicka data till uttaget. Uttaget måste vara anslutet till ett fjärruttag. Det valfria argumentet flags har samma betydelse som för recv() ovan. Till skillnad från send() fortsätter den här metoden att skicka data från bytes tills antingen all data har skickats eller ett fel inträffar. None returneras vid framgång. Vid fel uppstår ett undantag och det finns inget sätt att avgöra hur mycket data, om någon, som skickades framgångsrikt.

Ändrad i version 3.5: Socket timeout återställs inte längre varje gång data har skickats framgångsrikt. Socket timeout är nu den maximala totala tiden det tar att skicka all data.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

socket.sendto(bytes, address)¶

socket.sendto(bytes, flags, address)

Skicka data till uttaget. Sockeln ska inte vara ansluten till en fjärrsocket, eftersom destinationssockeln anges av address. Det valfria argumentet flags har samma betydelse som för recv() ovan. Returnerar antalet bytes som skickats. (Formatet på address beror på adressfamiljen — se ovan)

Utlöser en auditing event socket.sendto med argumenten self, address.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

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

Skicka normala data och tilläggsdata till sockeln genom att samla in icke-anknutna data från en serie buffertar och sammanfoga dem till ett enda meddelande. Argumentet buffers anger de icke-anknutna data som en iterabel av bytesliknande objekt (t.ex. bytes-objekt); operativsystemet kan sätta en gräns (sysconf()-värdet SC_IOV_MAX) för antalet buffertar som kan användas. Argumentet ancdata anger tilläggsdata (kontrollmeddelanden) som en iterabel med noll eller flera tupler (cmsg_level, cmsg_type, cmsg_data), där cmsg_level och cmsg_type är heltal som anger protokollnivån respektive den protokollspecifika typen, och cmsg_data är ett bytesliknande objekt som innehåller tillhörande data. Observera att vissa system (i synnerhet system utan CMSG_SPACE()) kan stödja sändning av endast ett kontrollmeddelande per anrop. Argumentet flags är 0 som standard och har samma betydelse som för send(). Om address anges och inte None, anges en destinationsadress för meddelandet. Returvärdet är antalet bytes av icke-ancillär data som skickats.

Följande funktion skickar listan över filbeskrivare fds över en AF_UNIX-socket, på system som stöder SCM_RIGHTS-mekanismen. Se även recvmsg().

import socket, array

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

Tillgänglighet: Unix, not WASI.

De flesta Unix-plattformar.

Utlöser en auditing event socket.sendmsg med argumenten self, address.

Tillagd i version 3.3.

Ändrad i version 3.5: Om systemanropet avbryts och signalhanteraren inte ger upphov till ett undantag, försöker metoden nu göra om systemanropet istället för att ge upphov till ett InterruptedError-undantag (se PEP 475 för förklaringen).

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])¶: Specialiserad version av sendmsg() för AF_ALG socket. Ställ in läge, IV, AEAD-associerad datalängd och flaggor för AF_ALG-uttag.

Tillgänglighet: Linux >= 2.6.38.

Tillagd i version 3.6.

socket.sendfile(file, offset=0, count=None)¶: Skicka en fil tills EOF nås med hjälp av högpresterande os.sendfile och returnera det totala antalet bytes som skickades. file måste vara ett vanligt filobjekt som öppnas i binärt läge. Om os.sendfile inte är tillgänglig (t.ex. Windows) eller om fil inte är en vanlig fil används istället send(). offset anger varifrån filen ska börja läsas. Om det anges är count det totala antalet byte som ska överföras i stället för att skicka filen tills EOF nås. Filens position uppdateras vid retur eller också vid fel, i vilket fall file.tell() kan användas för att räkna ut antalet bytes som skickades. Uttaget måste vara av typen SOCK_STREAM. Icke-blockerande socklar stöds inte.

Tillagd i version 3.5.

socket.set_inheritable(inheritable)¶: Ställ in ärvbarhetsflaggan för socketens filbeskrivare eller socketens handtag.

Tillagd i version 3.4.

socket.setblocking(flag)¶

Ställ in blockerande eller icke-blockerande läge för uttaget: om flag är false ställs uttaget in på icke-blockerande, annars på blockerande läge.

Denna metod är en kortform för vissa settimeout()-anrop:

sock.setblocking(True) är likvärdigt med sock.settimeout(None)
sock.setblocking(False) är likvärdigt med sock.settimeout(0.0)

Ändrad i version 3.7: Metoden tillämpar inte längre SOCK_NONBLOCK-flaggan på socket.type.

socket.settimeout(value)¶

Ställer in en timeout för blockering av socket-operationer. Argumentet value kan vara ett icke-negativt flyttal som uttrycker sekunder, eller None. Om ett värde som inte är noll anges kommer efterföljande socket-operationer att ge upphov till ett timeout-undantag om timeout-perioden value har löpt ut innan operationen har slutförts. Om noll anges sätts uttaget i icke-blockerande läge. Om None anges sätts uttaget i blockeringsläge.

För mer information, se notes on socket timeouts.

Ändrad i version 3.7: Metoden växlar inte längre SOCK_NONBLOCK-flaggan på socket.type.

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

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

socket.setsockopt(level, optname, None, optlen: int): Ställ in värdet för det angivna socket-alternativet (se Unix-manualsidan setsockopt(2)). De symboliska konstanter som behövs definieras i den här modulen (SO_* etc. <socket-unix-constants>). Värdet kan vara ett heltal, None eller ett bytesliknande objekt som representerar en buffert. I det senare fallet är det upp till den som anropar att se till att bytestringen innehåller rätt bitar (se den valfria inbyggda modulen struct för ett sätt att koda C-strukturer som bytestringar). När value är satt till None krävs argumentet optlen. Det är likvärdigt med att anropa C-funktionen setsockopt() med optval=NULL och optlen=optlen.

Ändrad i version 3.5: Skrivbar bytesliknande objekt är nu accepterad.

Ändrad i version 3.6: setsockopt(level, optname, None, optlen: int) formuläret har lagts till.

Tillgänglighet: not WASI.

socket.shutdown(how)¶: Stänger av en eller båda halvorna av anslutningen. Om how är SHUT_RD, tillåts inte ytterligare mottagningar. Om how är SHUT_WR, är ytterligare sändningar inte tillåtna. Om how är SHUT_RDWR, är ytterligare sändningar och mottagningar inte tillåtna.

Tillgänglighet: not WASI.

socket.share(process_id)¶: Duplicera ett uttag och förbered det för delning med en målprocess. Målprocessen måste förses med process_id. Det resulterande bytesobjektet kan sedan skickas till målprocessen med hjälp av någon form av interprocesskommunikation och sockeln kan återskapas där med fromshare(). När den här metoden har anropats är det säkert att stänga sockeln eftersom operativsystemet redan har duplicerat den för målprocessen.

Tillgänglighet: Windows.

Tillagd i version 3.3.

Observera att det inte finns några metoder read() eller write(); använd istället recv() och send() utan flags-argument.

Socket-objekt har också dessa (skrivskyddade) attribut som motsvarar de värden som ges till socket-konstruktören.

socket.family¶: Socket-familjen.

socket.type¶: Typ av socket.

socket.proto¶: Socketprotokollet.

Anmärkningar om timeout för socket¶

Ett socket-objekt kan vara i ett av tre lägen: blockerande, icke-blockerande eller timeout. Sockets skapas som standard alltid i blockeringsläge, men detta kan ändras genom att anropa setdefaulttimeout().

I blockeringsläge blockeras operationer tills de är slutförda eller tills systemet returnerar ett fel (t.ex. att anslutningen har tidsavgränsats).
I non-blocking mode misslyckas operationer (med ett fel som tyvärr är systemberoende) om de inte kan slutföras omedelbart: funktioner från modulen select kan användas för att veta när och om en socket är tillgänglig för läsning eller skrivning.
I timeout-läge misslyckas operationer om de inte kan slutföras inom den timeout som anges för uttaget (de ger upphov till ett timeout-undantag) eller om systemet returnerar ett fel.

Anteckning

På operativsystemsnivå är sockets i timeout-läge internt inställda på icke-blockerande läge. Dessutom delas blockerings- och timeout-lägena mellan filbeskrivare och socket-objekt som refererar till samma nätverksändpunkt. Denna implementationsdetalj kan få synliga konsekvenser om du t.ex. bestämmer dig för att använda fileno() för ett uttag.

Timeout och metoden ”Connect¶

Operationen connect() är också föremål för timeout-inställningen, och i allmänhet rekommenderas att anropa settimeout() innan anrop av connect() eller skicka en timeout-parameter till create_connection(). Systemets nätverksstack kan dock också returnera ett eget timeout-fel för anslutningen oavsett Python-socketens timeout-inställning.

Tidsgränser och `accept`-metoden¶

Om getdefaulttimeout() inte är None, ärver de uttag som returneras av metoden accept() denna timeout. Annars beror beteendet på inställningarna för det lyssnande uttaget:

om det lyssnande uttaget är i blockeringsläge eller i timeout-läge, är uttaget som returneras av accept() i blockeringsläge;
om det lyssnande uttaget är i icke-blockerande läge, om det uttag som returneras av accept() är i blockerande eller icke-blockerande läge är beroende av operativsystemet. Om du vill säkerställa ett plattformsoberoende beteende rekommenderas att du manuellt åsidosätter den här inställningen.

Exempel¶

Här följer fyra minimala exempel på program som använder TCP/IP-protokollet: en server som ekar alla data som den får tillbaka (och som bara betjänar en klient) och en klient som använder det. Observera att en server måste utföra sekvensen socket(), bind(), listen(), accept() (eventuellt upprepa accept() för att betjäna mer än en klient), medan en klient bara behöver sekvensen socket(), connect(). Observera också att servern inte gör sendall()/recv() på den socket den lyssnar på utan på den nya socket som returneras av accept().

De två första exemplen stöder endast 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))

De två följande exemplen är identiska med de två föregående, men stöder både IPv4 och IPv6. Serversidan lyssnar på den första tillgängliga adressfamiljen (den borde lyssna på båda i stället). På de flesta IPv6-klara system kommer IPv6 att ha företräde och servern kanske inte accepterar IPv4-trafik. Klientsidan försöker ansluta till alla de adresser som returneras som ett resultat av namnupplösningen och skickar trafik till den första som ansluts framgångsrikt:

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

Nästa exempel visar hur man skriver en mycket enkel nätverkssniffer med raw sockets i Windows. Exemplet kräver administratörsbehörighet för att ändra gränssnittet:

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)

I nästa exempel visas hur du använder socket-gränssnittet för att kommunicera med ett CAN-nätverk med hjälp av raw socket-protokollet. Om du istället vill använda CAN med broadcast manager-protokollet öppnar du en socket med:

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

När du har bundit (CAN_RAW) eller anslutit (CAN_BCM) sockeln kan du använda operationerna socket.send() och socket.recv() (och deras motsvarigheter) på socketobjektet som vanligt.

Detta sista exempel kan kräva särskilda privilegier:

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

Om du kör ett exempel flera gånger med för kort fördröjning mellan körningarna kan det leda till följande fel:

OSError: [Errno 98] Adressen är redan i bruk

Detta beror på att den tidigare exekveringen har lämnat uttaget i ett TIME_WAIT-tillstånd och inte kan återanvändas omedelbart.

Det finns en socket flagga att ställa in, för att förhindra detta, 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))

flaggan SO_REUSEADDR talar om för kärnan att återanvända en lokal socket i TIME_WAIT-tillstånd, utan att vänta på att dess naturliga timeout ska löpa ut.

Se även

För en introduktion till socketprogrammering (i C), se följande artiklar:

En inledande handledning i 4.3BSD Interprocess Communication, av Stuart Sechrest
An Advanced 4.3BSD Interprocess Communication Tutorial, av Samuel J. Leffler et al,

både i UNIX Programmer’s Manual, Supplementary Documents 1 (avsnitt PS1:7 och PS1:8). Det plattformsspecifika referensmaterialet för de olika socket-relaterade systemanropen är också en värdefull källa till information om detaljerna i socket-semantik. För Unix hänvisas till manualsidorna; för Windows hänvisas till WinSock (eller Winsock 2) specifikationen. För IPv6-klara API:er kan läsare vilja hänvisa till RFC 3493 med titeln Basic Socket Interface Extensions for IPv6.

`socket` — Gränssnitt för nätverk på låg nivå¶

Uttagsfamiljer¶

Modulens innehåll¶

Undantag¶

Konstanter¶

Funktioner¶

Skapa uttag¶

Övriga funktioner¶

Socket-objekt¶

Anmärkningar om timeout för socket¶

Timeout och metoden ”Connect¶

Tidsgränser och `accept`-metoden¶

Exempel¶

Innehåll

Föregående ämne

Nästa ämne

Denna sidan

socket — Gränssnitt för nätverk på låg nivå¶

Uttagsfamiljer¶

Modulens innehåll¶

Undantag¶

Konstanter¶

Funktioner¶

Skapa uttag¶

Övriga funktioner¶

Socket-objekt¶

Anmärkningar om timeout för socket¶

Timeout och metoden ”Connect¶

Tidsgränser och accept-metoden¶

Exempel¶

`socket` — Gränssnitt för nätverk på låg nivå¶

Tidsgränser och `accept`-metoden¶