blob: d4f1b65e46dcf12f0549b1f8325a11abbd5a1b01 [file] [log] [blame]
Fred Drakea6070f02000-08-16 14:14:32 +00001# Wrapper module for _socket, providing some additional facilities
2# implemented in Python.
3
4"""\
5This module provides socket operations and some related functions.
6On Unix, it supports IP (Internet Protocol) and Unix domain sockets.
Tim Peters495ad3c2001-01-15 01:36:40 +00007On other systems, it only supports IP. Functions specific for a
Martin v. Löwisaf484d52000-09-30 11:34:30 +00008socket are available as methods of the socket object.
Fred Drakea6070f02000-08-16 14:14:32 +00009
10Functions:
11
12socket() -- create a new socket object
Dave Cole331708b2004-08-09 04:51:41 +000013socketpair() -- create a pair of new socket objects [*]
Fred Drakea6070f02000-08-16 14:14:32 +000014fromfd() -- create a socket object from an open file descriptor [*]
Kristján Valur Jónsson10f383a2012-04-07 11:23:31 +000015fromshare() -- create a socket object from data received from socket.share() [*]
Fred Drakea6070f02000-08-16 14:14:32 +000016gethostname() -- return the current hostname
17gethostbyname() -- map a hostname to its IP number
18gethostbyaddr() -- map an IP number or hostname to DNS info
19getservbyname() -- map a service name and a protocol name to a port number
Mark Dickinson5c91bf32009-06-02 07:41:26 +000020getprotobyname() -- map a protocol name (e.g. 'tcp') to a number
Fred Drakea6070f02000-08-16 14:14:32 +000021ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order
22htons(), htonl() -- convert 16, 32 bit int from host to network byte order
23inet_aton() -- convert IP addr string (123.45.67.89) to 32-bit packed format
24inet_ntoa() -- convert 32-bit packed format IP to string (123.45.67.89)
Guido van Rossum9d0c8ce2002-07-18 17:08:35 +000025socket.getdefaulttimeout() -- get the default timeout value
26socket.setdefaulttimeout() -- set the default timeout value
Gregory P. Smithb4066372010-01-03 03:28:29 +000027create_connection() -- connects to an address, with an optional timeout and
28 optional source address.
Fred Drakea6070f02000-08-16 14:14:32 +000029
30 [*] not available on all platforms!
31
32Special objects:
33
34SocketType -- type object for socket objects
35error -- exception raised for I/O errors
Guido van Rossum47dfa4a2003-04-25 05:48:32 +000036has_ipv6 -- boolean value indicating if IPv6 is supported
Fred Drakea6070f02000-08-16 14:14:32 +000037
38Integer constants:
39
40AF_INET, AF_UNIX -- socket domains (first argument to socket() call)
41SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument)
42
43Many other constants may be defined; these may be used in calls to
44the setsockopt() and getsockopt() methods.
45"""
46
Tim Peters18e67782002-02-17 04:25:24 +000047import _socket
Fred Drakea6070f02000-08-16 14:14:32 +000048from _socket import *
Tim Peters18e67782002-02-17 04:25:24 +000049
Guido van Rossum7d0a8262007-05-21 23:13:11 +000050import os, sys, io
Fred Drakea6070f02000-08-16 14:14:32 +000051
Fred Drake70d566b2003-04-29 19:50:25 +000052try:
Gregory P. Smithaafdca82010-01-04 04:50:36 +000053 import errno
Fred Drake70d566b2003-04-29 19:50:25 +000054except ImportError:
Gregory P. Smithaafdca82010-01-04 04:50:36 +000055 errno = None
56EBADF = getattr(errno, 'EBADF', 9)
Antoine Pitrou98b46702010-09-18 22:59:00 +000057EAGAIN = getattr(errno, 'EAGAIN', 11)
58EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11)
Fred Drake70d566b2003-04-29 19:50:25 +000059
Benjamin Petersonef3e4c22009-04-11 19:48:14 +000060__all__ = ["getfqdn", "create_connection"]
Skip Montanaro0de65802001-02-15 22:15:14 +000061__all__.extend(os._get_exports_list(_socket))
Thomas Wouters47b49bf2007-08-30 22:15:33 +000062
63
64_realsocket = socket
Skip Montanaro0de65802001-02-15 22:15:14 +000065
Fred Drakea6070f02000-08-16 14:14:32 +000066# WSA error codes
67if sys.platform.lower().startswith("win"):
68 errorTab = {}
69 errorTab[10004] = "The operation was interrupted."
70 errorTab[10009] = "A bad file handle was passed."
71 errorTab[10013] = "Permission denied."
72 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT
73 errorTab[10022] = "An invalid operation was attempted."
74 errorTab[10035] = "The socket operation would block"
75 errorTab[10036] = "A blocking operation is already in progress."
76 errorTab[10048] = "The network address is in use."
77 errorTab[10054] = "The connection has been reset."
78 errorTab[10058] = "The network has been shut down."
79 errorTab[10060] = "The operation timed out."
80 errorTab[10061] = "Connection refused."
81 errorTab[10063] = "The name is too long."
82 errorTab[10064] = "The host is down."
83 errorTab[10065] = "The host is unreachable."
Skip Montanaro64de1a42001-03-18 19:53:21 +000084 __all__.append("errorTab")
Guido van Rossumde7cade2002-08-08 15:25:28 +000085
Fred Drakea6070f02000-08-16 14:14:32 +000086
Guido van Rossum7d0a8262007-05-21 23:13:11 +000087class socket(_socket.socket):
88
89 """A subclass of _socket.socket adding the makefile() method."""
90
Guido van Rossum86bc33c2007-11-14 22:32:02 +000091 __slots__ = ["__weakref__", "_io_refs", "_closed"]
Guido van Rossum7d0a8262007-05-21 23:13:11 +000092
Jeremy Hylton5accbdb2007-08-03 20:40:09 +000093 def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None):
Guido van Rossum39eb8fa2007-11-16 01:24:05 +000094 _socket.socket.__init__(self, family, type, proto, fileno)
Guido van Rossum86bc33c2007-11-14 22:32:02 +000095 self._io_refs = 0
96 self._closed = False
Jeremy Hylton5accbdb2007-08-03 20:40:09 +000097
Giampaolo Rodolàb383dbb2010-09-08 22:44:12 +000098 def __enter__(self):
99 return self
100
101 def __exit__(self, *args):
102 if not self._closed:
103 self.close()
104
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000105 def __repr__(self):
106 """Wrap __repr__() to reveal the real class name."""
107 s = _socket.socket.__repr__(self)
108 if s.startswith("<socket object"):
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000109 s = "<%s.%s%s%s" % (self.__class__.__module__,
110 self.__class__.__name__,
Antoine Pitroue033e062010-10-29 10:38:18 +0000111 getattr(self, '_closed', False) and " [closed] " or "",
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000112 s[7:])
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000113 return s
114
Antoine Pitrou6d58d642011-03-20 23:56:36 +0100115 def __getstate__(self):
116 raise TypeError("Cannot serialize socket object")
117
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000118 def dup(self):
119 """dup() -> socket object
120
121 Return a new socket object connected to the same system resource.
122 """
123 fd = dup(self.fileno())
124 sock = self.__class__(self.family, self.type, self.proto, fileno=fd)
125 sock.settimeout(self.gettimeout())
126 return sock
127
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000128 def accept(self):
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000129 """accept() -> (socket object, address info)
130
131 Wait for an incoming connection. Return a new socket
132 representing the connection, and the address of the client.
133 For IP sockets, the address info is a pair (hostaddr, port).
134 """
135 fd, addr = self._accept()
Antoine Pitrou600232b2011-01-05 21:03:42 +0000136 sock = socket(self.family, self.type, self.proto, fileno=fd)
137 # Issue #7995: if no default timeout is set and the listening
138 # socket had a (non-zero) timeout, force the new socket in blocking
139 # mode to override platform-specific socket flags inheritance.
140 if getdefaulttimeout() is None and self.gettimeout():
141 sock.setblocking(True)
142 return sock, addr
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000143
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000144 def makefile(self, mode="r", buffering=None, *,
Antoine Pitrou834bd812010-10-13 16:17:14 +0000145 encoding=None, errors=None, newline=None):
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000146 """makefile(...) -> an I/O stream connected to the socket
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000147
148 The arguments are as for io.open() after the filename,
149 except the only mode characters supported are 'r', 'w' and 'b'.
150 The semantics are similar too. (XXX refactor to share code?)
151 """
152 for c in mode:
153 if c not in {"r", "w", "b"}:
154 raise ValueError("invalid mode %r (only r, w, b allowed)")
155 writing = "w" in mode
156 reading = "r" in mode or not writing
157 assert reading or writing
158 binary = "b" in mode
159 rawmode = ""
160 if reading:
161 rawmode += "r"
162 if writing:
163 rawmode += "w"
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000164 raw = SocketIO(self, rawmode)
165 self._io_refs += 1
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000166 if buffering is None:
167 buffering = -1
168 if buffering < 0:
169 buffering = io.DEFAULT_BUFFER_SIZE
170 if buffering == 0:
171 if not binary:
172 raise ValueError("unbuffered streams must be binary")
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000173 return raw
174 if reading and writing:
175 buffer = io.BufferedRWPair(raw, raw, buffering)
176 elif reading:
177 buffer = io.BufferedReader(raw, buffering)
178 else:
179 assert writing
180 buffer = io.BufferedWriter(raw, buffering)
181 if binary:
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000182 return buffer
Antoine Pitrou834bd812010-10-13 16:17:14 +0000183 text = io.TextIOWrapper(buffer, encoding, errors, newline)
Guido van Rossum93adc5d2007-07-17 20:41:19 +0000184 text.mode = mode
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000185 return text
186
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000187 def _decref_socketios(self):
188 if self._io_refs > 0:
189 self._io_refs -= 1
190 if self._closed:
191 self.close()
192
Daniel Stutzbach19d6a4f2010-08-31 20:08:07 +0000193 def _real_close(self, _ss=_socket.socket):
Benjamin Peterson49203dc2010-08-31 20:10:55 +0000194 # This function should not reference any globals. See issue #808164.
Daniel Stutzbach19d6a4f2010-08-31 20:08:07 +0000195 _ss.close(self)
Bill Janssen54cc54c2007-12-14 22:08:56 +0000196
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000197 def close(self):
Benjamin Peterson49203dc2010-08-31 20:10:55 +0000198 # This function should not reference any globals. See issue #808164.
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000199 self._closed = True
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000200 if self._io_refs <= 0:
Bill Janssen54cc54c2007-12-14 22:08:56 +0000201 self._real_close()
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000202
Antoine Pitrou70deb3d2012-04-01 01:00:17 +0200203 def detach(self):
204 """detach() -> file descriptor
205
206 Close the socket object without closing the underlying file descriptor.
207 The object cannot be used after this call, but the file descriptor
208 can be reused for other purposes. The file descriptor is returned.
209 """
210 self._closed = True
211 return super().detach()
212
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000213def fromfd(fd, family, type, proto=0):
214 """ fromfd(fd, family, type[, proto]) -> socket object
215
216 Create a socket object from a duplicate of the given file
217 descriptor. The remaining arguments are the same as for socket().
218 """
219 nfd = dup(fd)
220 return socket(family, type, proto, nfd)
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000221
Kristján Valur Jónsson10f383a2012-04-07 11:23:31 +0000222if hasattr(_socket.socket, "share"):
223 def fromshare(info):
224 """ fromshare(info) -> socket object
225
226 Create a socket object from a the bytes object returned by
227 socket.share(pid).
228 """
229 return socket(0, 0, 0, info)
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000230
Antoine Pitrou9e0b8642010-09-14 18:00:02 +0000231if hasattr(_socket, "socketpair"):
232
233 def socketpair(family=None, type=SOCK_STREAM, proto=0):
234 """socketpair([family[, type[, proto]]]) -> (socket object, socket object)
235
236 Create a pair of socket objects from the sockets returned by the platform
237 socketpair() function.
238 The arguments are the same as for socket() except the default family is
239 AF_UNIX if defined on the platform; otherwise, the default is AF_INET.
240 """
241 if family is None:
242 try:
243 family = AF_UNIX
244 except NameError:
245 family = AF_INET
246 a, b = _socket.socketpair(family, type, proto)
247 a = socket(family, type, proto, a.detach())
248 b = socket(family, type, proto, b.detach())
249 return a, b
250
251
Antoine Pitrou98b46702010-09-18 22:59:00 +0000252_blocking_errnos = { EAGAIN, EWOULDBLOCK }
253
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000254class SocketIO(io.RawIOBase):
255
256 """Raw I/O implementation for stream sockets.
257
258 This class supports the makefile() method on sockets. It provides
259 the raw I/O interface on top of a socket object.
260 """
261
Antoine Pitrou872b79d2010-09-15 08:39:25 +0000262 # One might wonder why not let FileIO do the job instead. There are two
263 # main reasons why FileIO is not adapted:
264 # - it wouldn't work under Windows (where you can't used read() and
265 # write() on a socket handle)
266 # - it wouldn't work with socket timeouts (FileIO would ignore the
267 # timeout and consider the socket non-blocking)
268
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000269 # XXX More docs
270
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000271 def __init__(self, sock, mode):
Benjamin Peterson44309e62008-11-22 00:41:45 +0000272 if mode not in ("r", "w", "rw", "rb", "wb", "rwb"):
Guido van Rossum5abbf752007-08-27 17:39:33 +0000273 raise ValueError("invalid mode: %r" % mode)
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000274 io.RawIOBase.__init__(self)
275 self._sock = sock
Benjamin Peterson44309e62008-11-22 00:41:45 +0000276 if "b" not in mode:
277 mode += "b"
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000278 self._mode = mode
Guido van Rossum5abbf752007-08-27 17:39:33 +0000279 self._reading = "r" in mode
280 self._writing = "w" in mode
Antoine Pitrou68e5c042011-02-25 23:07:44 +0000281 self._timeout_occurred = False
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000282
283 def readinto(self, b):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000284 """Read up to len(b) bytes into the writable buffer *b* and return
285 the number of bytes read. If the socket is non-blocking and no bytes
286 are available, None is returned.
287
288 If *b* is non-empty, a 0 return value indicates that the connection
289 was shutdown at the other end.
290 """
Guido van Rossum5abbf752007-08-27 17:39:33 +0000291 self._checkClosed()
292 self._checkReadable()
Antoine Pitrou68e5c042011-02-25 23:07:44 +0000293 if self._timeout_occurred:
294 raise IOError("cannot read from timed out object")
Gregory P. Smithaafdca82010-01-04 04:50:36 +0000295 while True:
296 try:
297 return self._sock.recv_into(b)
Antoine Pitrou68e5c042011-02-25 23:07:44 +0000298 except timeout:
299 self._timeout_occurred = True
300 raise
Antoine Pitrou24d659d2011-10-23 23:49:42 +0200301 except InterruptedError:
302 continue
Gregory P. Smithaafdca82010-01-04 04:50:36 +0000303 except error as e:
Antoine Pitrou24d659d2011-10-23 23:49:42 +0200304 if e.args[0] in _blocking_errnos:
Antoine Pitrou98b46702010-09-18 22:59:00 +0000305 return None
Gregory P. Smithaafdca82010-01-04 04:50:36 +0000306 raise
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000307
308 def write(self, b):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000309 """Write the given bytes or bytearray object *b* to the socket
310 and return the number of bytes written. This can be less than
311 len(b) if not all data could be written. If the socket is
312 non-blocking and no bytes could be written None is returned.
313 """
Guido van Rossum5abbf752007-08-27 17:39:33 +0000314 self._checkClosed()
315 self._checkWritable()
Antoine Pitrou98b46702010-09-18 22:59:00 +0000316 try:
317 return self._sock.send(b)
318 except error as e:
319 # XXX what about EINTR?
320 if e.args[0] in _blocking_errnos:
321 return None
322 raise
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000323
324 def readable(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000325 """True if the SocketIO is open for reading.
326 """
Antoine Pitrou1e7ee9d2012-09-14 17:28:10 +0200327 if self.closed:
328 raise ValueError("I/O operation on closed socket.")
329 return self._reading
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000330
331 def writable(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000332 """True if the SocketIO is open for writing.
333 """
Antoine Pitrou1e7ee9d2012-09-14 17:28:10 +0200334 if self.closed:
335 raise ValueError("I/O operation on closed socket.")
336 return self._writing
337
338 def seekable(self):
339 """True if the SocketIO is open for seeking.
340 """
341 if self.closed:
342 raise ValueError("I/O operation on closed socket.")
343 return super().seekable()
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000344
345 def fileno(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000346 """Return the file descriptor of the underlying socket.
347 """
Gregory P. Smithde3369f2009-01-12 04:50:11 +0000348 self._checkClosed()
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000349 return self._sock.fileno()
350
Amaury Forgeot d'Arc9d24ff02008-11-20 23:15:52 +0000351 @property
352 def name(self):
Victor Stinnerc3a51ec2011-01-04 11:00:45 +0000353 if not self.closed:
354 return self.fileno()
355 else:
356 return -1
Amaury Forgeot d'Arc9d24ff02008-11-20 23:15:52 +0000357
358 @property
359 def mode(self):
360 return self._mode
361
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000362 def close(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000363 """Close the SocketIO object. This doesn't close the underlying
364 socket, except if all references to it have disappeared.
365 """
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000366 if self.closed:
367 return
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000368 io.RawIOBase.close(self)
Gregory P. Smithde3369f2009-01-12 04:50:11 +0000369 self._sock._decref_socketios()
370 self._sock = None
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000371
Fred Drakea6070f02000-08-16 14:14:32 +0000372
373def getfqdn(name=''):
374 """Get fully qualified domain name from name.
375
376 An empty argument is interpreted as meaning the local host.
377
378 First the hostname returned by gethostbyaddr() is checked, then
379 possibly existing aliases. In case no FQDN is available, hostname
Brett Cannon01668a12005-03-11 00:04:17 +0000380 from gethostname() is returned.
Fred Drakea6070f02000-08-16 14:14:32 +0000381 """
382 name = name.strip()
Peter Schneider-Kamp2d2785a2000-08-16 20:30:21 +0000383 if not name or name == '0.0.0.0':
Fred Drakea6070f02000-08-16 14:14:32 +0000384 name = gethostname()
385 try:
386 hostname, aliases, ipaddrs = gethostbyaddr(name)
387 except error:
388 pass
389 else:
390 aliases.insert(0, hostname)
391 for name in aliases:
392 if '.' in name:
393 break
394 else:
395 name = hostname
396 return name
397
398
Georg Brandlf78e02b2008-06-10 17:40:04 +0000399_GLOBAL_DEFAULT_TIMEOUT = object()
Guido van Rossumd8faa362007-04-27 19:54:29 +0000400
Gregory P. Smithb4066372010-01-03 03:28:29 +0000401def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT,
402 source_address=None):
Georg Brandlf78e02b2008-06-10 17:40:04 +0000403 """Connect to *address* and return the socket object.
404
405 Convenience function. Connect to *address* (a 2-tuple ``(host,
406 port)``) and return the socket object. Passing the optional
407 *timeout* parameter will set the timeout on the socket instance
408 before attempting to connect. If no *timeout* is supplied, the
409 global default timeout setting returned by :func:`getdefaulttimeout`
Gregory P. Smithb4066372010-01-03 03:28:29 +0000410 is used. If *source_address* is set it must be a tuple of (host, port)
411 for the socket to bind as a source address before making the connection.
412 An host of '' or port 0 tells the OS to use the default.
Guido van Rossumd8faa362007-04-27 19:54:29 +0000413 """
414
Guido van Rossumd8faa362007-04-27 19:54:29 +0000415 host, port = address
Antoine Pitrou4b92b5f2010-09-07 21:05:49 +0000416 err = None
Guido van Rossumd8faa362007-04-27 19:54:29 +0000417 for res in getaddrinfo(host, port, 0, SOCK_STREAM):
418 af, socktype, proto, canonname, sa = res
419 sock = None
420 try:
421 sock = socket(af, socktype, proto)
Georg Brandlf78e02b2008-06-10 17:40:04 +0000422 if timeout is not _GLOBAL_DEFAULT_TIMEOUT:
Guido van Rossumd8faa362007-04-27 19:54:29 +0000423 sock.settimeout(timeout)
Gregory P. Smithb4066372010-01-03 03:28:29 +0000424 if source_address:
425 sock.bind(source_address)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000426 sock.connect(sa)
427 return sock
428
Antoine Pitrou4b92b5f2010-09-07 21:05:49 +0000429 except error as _:
430 err = _
Guido van Rossumd8faa362007-04-27 19:54:29 +0000431 if sock is not None:
432 sock.close()
433
Antoine Pitrou4b92b5f2010-09-07 21:05:49 +0000434 if err is not None:
435 raise err
436 else:
437 raise error("getaddrinfo returns an empty list")