blob: b2954b5a877660671e41a87f9d783894ef377f93 [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 [*]
15gethostname() -- return the current hostname
16gethostbyname() -- map a hostname to its IP number
17gethostbyaddr() -- map an IP number or hostname to DNS info
18getservbyname() -- map a service name and a protocol name to a port number
Mark Dickinson5c91bf32009-06-02 07:41:26 +000019getprotobyname() -- map a protocol name (e.g. 'tcp') to a number
Fred Drakea6070f02000-08-16 14:14:32 +000020ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order
21htons(), htonl() -- convert 16, 32 bit int from host to network byte order
22inet_aton() -- convert IP addr string (123.45.67.89) to 32-bit packed format
23inet_ntoa() -- convert 32-bit packed format IP to string (123.45.67.89)
Guido van Rossum9d0c8ce2002-07-18 17:08:35 +000024socket.getdefaulttimeout() -- get the default timeout value
25socket.setdefaulttimeout() -- set the default timeout value
Gregory P. Smithb4066372010-01-03 03:28:29 +000026create_connection() -- connects to an address, with an optional timeout and
27 optional source address.
Fred Drakea6070f02000-08-16 14:14:32 +000028
29 [*] not available on all platforms!
30
31Special objects:
32
33SocketType -- type object for socket objects
34error -- exception raised for I/O errors
Guido van Rossum47dfa4a2003-04-25 05:48:32 +000035has_ipv6 -- boolean value indicating if IPv6 is supported
Fred Drakea6070f02000-08-16 14:14:32 +000036
37Integer constants:
38
39AF_INET, AF_UNIX -- socket domains (first argument to socket() call)
40SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument)
41
42Many other constants may be defined; these may be used in calls to
43the setsockopt() and getsockopt() methods.
44"""
45
Tim Peters18e67782002-02-17 04:25:24 +000046import _socket
Fred Drakea6070f02000-08-16 14:14:32 +000047from _socket import *
Tim Peters18e67782002-02-17 04:25:24 +000048
Guido van Rossum7d0a8262007-05-21 23:13:11 +000049import os, sys, io
Fred Drakea6070f02000-08-16 14:14:32 +000050
Fred Drake70d566b2003-04-29 19:50:25 +000051try:
Gregory P. Smithaafdca82010-01-04 04:50:36 +000052 import errno
Fred Drake70d566b2003-04-29 19:50:25 +000053except ImportError:
Gregory P. Smithaafdca82010-01-04 04:50:36 +000054 errno = None
55EBADF = getattr(errno, 'EBADF', 9)
Antoine Pitrou98b46702010-09-18 22:59:00 +000056EAGAIN = getattr(errno, 'EAGAIN', 11)
57EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11)
Fred Drake70d566b2003-04-29 19:50:25 +000058
Benjamin Petersonef3e4c22009-04-11 19:48:14 +000059__all__ = ["getfqdn", "create_connection"]
Skip Montanaro0de65802001-02-15 22:15:14 +000060__all__.extend(os._get_exports_list(_socket))
Thomas Wouters47b49bf2007-08-30 22:15:33 +000061
62
63_realsocket = socket
Skip Montanaro0de65802001-02-15 22:15:14 +000064
Fred Drakea6070f02000-08-16 14:14:32 +000065# WSA error codes
66if sys.platform.lower().startswith("win"):
67 errorTab = {}
68 errorTab[10004] = "The operation was interrupted."
69 errorTab[10009] = "A bad file handle was passed."
70 errorTab[10013] = "Permission denied."
71 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT
72 errorTab[10022] = "An invalid operation was attempted."
73 errorTab[10035] = "The socket operation would block"
74 errorTab[10036] = "A blocking operation is already in progress."
75 errorTab[10048] = "The network address is in use."
76 errorTab[10054] = "The connection has been reset."
77 errorTab[10058] = "The network has been shut down."
78 errorTab[10060] = "The operation timed out."
79 errorTab[10061] = "Connection refused."
80 errorTab[10063] = "The name is too long."
81 errorTab[10064] = "The host is down."
82 errorTab[10065] = "The host is unreachable."
Skip Montanaro64de1a42001-03-18 19:53:21 +000083 __all__.append("errorTab")
Guido van Rossumde7cade2002-08-08 15:25:28 +000084
Fred Drakea6070f02000-08-16 14:14:32 +000085
Guido van Rossum7d0a8262007-05-21 23:13:11 +000086class socket(_socket.socket):
87
88 """A subclass of _socket.socket adding the makefile() method."""
89
Guido van Rossum86bc33c2007-11-14 22:32:02 +000090 __slots__ = ["__weakref__", "_io_refs", "_closed"]
Guido van Rossum7d0a8262007-05-21 23:13:11 +000091
Jeremy Hylton5accbdb2007-08-03 20:40:09 +000092 def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None):
Guido van Rossum39eb8fa2007-11-16 01:24:05 +000093 _socket.socket.__init__(self, family, type, proto, fileno)
Guido van Rossum86bc33c2007-11-14 22:32:02 +000094 self._io_refs = 0
95 self._closed = False
Jeremy Hylton5accbdb2007-08-03 20:40:09 +000096
Giampaolo Rodolàb383dbb2010-09-08 22:44:12 +000097 def __enter__(self):
98 return self
99
100 def __exit__(self, *args):
101 if not self._closed:
102 self.close()
103
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000104 def __repr__(self):
105 """Wrap __repr__() to reveal the real class name."""
106 s = _socket.socket.__repr__(self)
107 if s.startswith("<socket object"):
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000108 s = "<%s.%s%s%s" % (self.__class__.__module__,
109 self.__class__.__name__,
Antoine Pitroue033e062010-10-29 10:38:18 +0000110 getattr(self, '_closed', False) and " [closed] " or "",
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000111 s[7:])
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000112 return s
113
Antoine Pitrou6d58d642011-03-20 23:56:36 +0100114 def __getstate__(self):
115 raise TypeError("Cannot serialize socket object")
116
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000117 def dup(self):
118 """dup() -> socket object
119
120 Return a new socket object connected to the same system resource.
121 """
122 fd = dup(self.fileno())
123 sock = self.__class__(self.family, self.type, self.proto, fileno=fd)
124 sock.settimeout(self.gettimeout())
125 return sock
126
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000127 def accept(self):
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000128 """accept() -> (socket object, address info)
129
130 Wait for an incoming connection. Return a new socket
131 representing the connection, and the address of the client.
132 For IP sockets, the address info is a pair (hostaddr, port).
133 """
134 fd, addr = self._accept()
Antoine Pitrou600232b2011-01-05 21:03:42 +0000135 sock = socket(self.family, self.type, self.proto, fileno=fd)
136 # Issue #7995: if no default timeout is set and the listening
137 # socket had a (non-zero) timeout, force the new socket in blocking
138 # mode to override platform-specific socket flags inheritance.
139 if getdefaulttimeout() is None and self.gettimeout():
140 sock.setblocking(True)
141 return sock, addr
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000142
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000143 def makefile(self, mode="r", buffering=None, *,
Antoine Pitrou834bd812010-10-13 16:17:14 +0000144 encoding=None, errors=None, newline=None):
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000145 """makefile(...) -> an I/O stream connected to the socket
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000146
147 The arguments are as for io.open() after the filename,
148 except the only mode characters supported are 'r', 'w' and 'b'.
149 The semantics are similar too. (XXX refactor to share code?)
150 """
151 for c in mode:
152 if c not in {"r", "w", "b"}:
153 raise ValueError("invalid mode %r (only r, w, b allowed)")
154 writing = "w" in mode
155 reading = "r" in mode or not writing
156 assert reading or writing
157 binary = "b" in mode
158 rawmode = ""
159 if reading:
160 rawmode += "r"
161 if writing:
162 rawmode += "w"
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000163 raw = SocketIO(self, rawmode)
164 self._io_refs += 1
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000165 if buffering is None:
166 buffering = -1
167 if buffering < 0:
168 buffering = io.DEFAULT_BUFFER_SIZE
169 if buffering == 0:
170 if not binary:
171 raise ValueError("unbuffered streams must be binary")
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000172 return raw
173 if reading and writing:
174 buffer = io.BufferedRWPair(raw, raw, buffering)
175 elif reading:
176 buffer = io.BufferedReader(raw, buffering)
177 else:
178 assert writing
179 buffer = io.BufferedWriter(raw, buffering)
180 if binary:
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000181 return buffer
Antoine Pitrou834bd812010-10-13 16:17:14 +0000182 text = io.TextIOWrapper(buffer, encoding, errors, newline)
Guido van Rossum93adc5d2007-07-17 20:41:19 +0000183 text.mode = mode
Guido van Rossum7d0a8262007-05-21 23:13:11 +0000184 return text
185
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000186 def _decref_socketios(self):
187 if self._io_refs > 0:
188 self._io_refs -= 1
189 if self._closed:
190 self.close()
191
Daniel Stutzbach19d6a4f2010-08-31 20:08:07 +0000192 def _real_close(self, _ss=_socket.socket):
Benjamin Peterson49203dc2010-08-31 20:10:55 +0000193 # This function should not reference any globals. See issue #808164.
Daniel Stutzbach19d6a4f2010-08-31 20:08:07 +0000194 _ss.close(self)
Bill Janssen54cc54c2007-12-14 22:08:56 +0000195
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000196 def close(self):
Benjamin Peterson49203dc2010-08-31 20:10:55 +0000197 # This function should not reference any globals. See issue #808164.
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000198 self._closed = True
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000199 if self._io_refs <= 0:
Bill Janssen54cc54c2007-12-14 22:08:56 +0000200 self._real_close()
Guido van Rossum39eb8fa2007-11-16 01:24:05 +0000201
202def fromfd(fd, family, type, proto=0):
203 """ fromfd(fd, family, type[, proto]) -> socket object
204
205 Create a socket object from a duplicate of the given file
206 descriptor. The remaining arguments are the same as for socket().
207 """
208 nfd = dup(fd)
209 return socket(family, type, proto, nfd)
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000210
211
Antoine Pitrou9e0b8642010-09-14 18:00:02 +0000212if hasattr(_socket, "socketpair"):
213
214 def socketpair(family=None, type=SOCK_STREAM, proto=0):
215 """socketpair([family[, type[, proto]]]) -> (socket object, socket object)
216
217 Create a pair of socket objects from the sockets returned by the platform
218 socketpair() function.
219 The arguments are the same as for socket() except the default family is
220 AF_UNIX if defined on the platform; otherwise, the default is AF_INET.
221 """
222 if family is None:
223 try:
224 family = AF_UNIX
225 except NameError:
226 family = AF_INET
227 a, b = _socket.socketpair(family, type, proto)
228 a = socket(family, type, proto, a.detach())
229 b = socket(family, type, proto, b.detach())
230 return a, b
231
232
Antoine Pitrou98b46702010-09-18 22:59:00 +0000233_blocking_errnos = { EAGAIN, EWOULDBLOCK }
234
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000235class SocketIO(io.RawIOBase):
236
237 """Raw I/O implementation for stream sockets.
238
239 This class supports the makefile() method on sockets. It provides
240 the raw I/O interface on top of a socket object.
241 """
242
Antoine Pitrou872b79d2010-09-15 08:39:25 +0000243 # One might wonder why not let FileIO do the job instead. There are two
244 # main reasons why FileIO is not adapted:
245 # - it wouldn't work under Windows (where you can't used read() and
246 # write() on a socket handle)
247 # - it wouldn't work with socket timeouts (FileIO would ignore the
248 # timeout and consider the socket non-blocking)
249
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000250 # XXX More docs
251
Guido van Rossum86bc33c2007-11-14 22:32:02 +0000252 def __init__(self, sock, mode):
Benjamin Peterson44309e62008-11-22 00:41:45 +0000253 if mode not in ("r", "w", "rw", "rb", "wb", "rwb"):
Guido van Rossum5abbf752007-08-27 17:39:33 +0000254 raise ValueError("invalid mode: %r" % mode)
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000255 io.RawIOBase.__init__(self)
256 self._sock = sock
Benjamin Peterson44309e62008-11-22 00:41:45 +0000257 if "b" not in mode:
258 mode += "b"
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000259 self._mode = mode
Guido van Rossum5abbf752007-08-27 17:39:33 +0000260 self._reading = "r" in mode
261 self._writing = "w" in mode
Antoine Pitrou68e5c042011-02-25 23:07:44 +0000262 self._timeout_occurred = False
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000263
264 def readinto(self, b):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000265 """Read up to len(b) bytes into the writable buffer *b* and return
266 the number of bytes read. If the socket is non-blocking and no bytes
267 are available, None is returned.
268
269 If *b* is non-empty, a 0 return value indicates that the connection
270 was shutdown at the other end.
271 """
Guido van Rossum5abbf752007-08-27 17:39:33 +0000272 self._checkClosed()
273 self._checkReadable()
Antoine Pitrou68e5c042011-02-25 23:07:44 +0000274 if self._timeout_occurred:
275 raise IOError("cannot read from timed out object")
Gregory P. Smithaafdca82010-01-04 04:50:36 +0000276 while True:
277 try:
278 return self._sock.recv_into(b)
Antoine Pitrou68e5c042011-02-25 23:07:44 +0000279 except timeout:
280 self._timeout_occurred = True
281 raise
Antoine Pitrou24d659d2011-10-23 23:49:42 +0200282 except InterruptedError:
283 continue
Gregory P. Smithaafdca82010-01-04 04:50:36 +0000284 except error as e:
Antoine Pitrou24d659d2011-10-23 23:49:42 +0200285 if e.args[0] in _blocking_errnos:
Antoine Pitrou98b46702010-09-18 22:59:00 +0000286 return None
Gregory P. Smithaafdca82010-01-04 04:50:36 +0000287 raise
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000288
289 def write(self, b):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000290 """Write the given bytes or bytearray object *b* to the socket
291 and return the number of bytes written. This can be less than
292 len(b) if not all data could be written. If the socket is
293 non-blocking and no bytes could be written None is returned.
294 """
Guido van Rossum5abbf752007-08-27 17:39:33 +0000295 self._checkClosed()
296 self._checkWritable()
Antoine Pitrou98b46702010-09-18 22:59:00 +0000297 try:
298 return self._sock.send(b)
299 except error as e:
300 # XXX what about EINTR?
301 if e.args[0] in _blocking_errnos:
302 return None
303 raise
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000304
305 def readable(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000306 """True if the SocketIO is open for reading.
307 """
Guido van Rossum5abbf752007-08-27 17:39:33 +0000308 return self._reading and not self.closed
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000309
310 def writable(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000311 """True if the SocketIO is open for writing.
312 """
Guido van Rossum5abbf752007-08-27 17:39:33 +0000313 return self._writing and not self.closed
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000314
315 def fileno(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000316 """Return the file descriptor of the underlying socket.
317 """
Gregory P. Smithde3369f2009-01-12 04:50:11 +0000318 self._checkClosed()
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000319 return self._sock.fileno()
320
Amaury Forgeot d'Arc9d24ff02008-11-20 23:15:52 +0000321 @property
322 def name(self):
Victor Stinnerc3a51ec2011-01-04 11:00:45 +0000323 if not self.closed:
324 return self.fileno()
325 else:
326 return -1
Amaury Forgeot d'Arc9d24ff02008-11-20 23:15:52 +0000327
328 @property
329 def mode(self):
330 return self._mode
331
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000332 def close(self):
Antoine Pitrou5aa0d102010-09-15 09:32:45 +0000333 """Close the SocketIO object. This doesn't close the underlying
334 socket, except if all references to it have disappeared.
335 """
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000336 if self.closed:
337 return
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000338 io.RawIOBase.close(self)
Gregory P. Smithde3369f2009-01-12 04:50:11 +0000339 self._sock._decref_socketios()
340 self._sock = None
Jeremy Hylton5accbdb2007-08-03 20:40:09 +0000341
Fred Drakea6070f02000-08-16 14:14:32 +0000342
343def getfqdn(name=''):
344 """Get fully qualified domain name from name.
345
346 An empty argument is interpreted as meaning the local host.
347
348 First the hostname returned by gethostbyaddr() is checked, then
349 possibly existing aliases. In case no FQDN is available, hostname
Brett Cannon01668a12005-03-11 00:04:17 +0000350 from gethostname() is returned.
Fred Drakea6070f02000-08-16 14:14:32 +0000351 """
352 name = name.strip()
Peter Schneider-Kamp2d2785a2000-08-16 20:30:21 +0000353 if not name or name == '0.0.0.0':
Fred Drakea6070f02000-08-16 14:14:32 +0000354 name = gethostname()
355 try:
356 hostname, aliases, ipaddrs = gethostbyaddr(name)
357 except error:
358 pass
359 else:
360 aliases.insert(0, hostname)
361 for name in aliases:
362 if '.' in name:
363 break
364 else:
365 name = hostname
366 return name
367
368
Georg Brandlf78e02b2008-06-10 17:40:04 +0000369_GLOBAL_DEFAULT_TIMEOUT = object()
Guido van Rossumd8faa362007-04-27 19:54:29 +0000370
Gregory P. Smithb4066372010-01-03 03:28:29 +0000371def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT,
372 source_address=None):
Georg Brandlf78e02b2008-06-10 17:40:04 +0000373 """Connect to *address* and return the socket object.
374
375 Convenience function. Connect to *address* (a 2-tuple ``(host,
376 port)``) and return the socket object. Passing the optional
377 *timeout* parameter will set the timeout on the socket instance
378 before attempting to connect. If no *timeout* is supplied, the
379 global default timeout setting returned by :func:`getdefaulttimeout`
Gregory P. Smithb4066372010-01-03 03:28:29 +0000380 is used. If *source_address* is set it must be a tuple of (host, port)
381 for the socket to bind as a source address before making the connection.
382 An host of '' or port 0 tells the OS to use the default.
Guido van Rossumd8faa362007-04-27 19:54:29 +0000383 """
384
Guido van Rossumd8faa362007-04-27 19:54:29 +0000385 host, port = address
Antoine Pitrou4b92b5f2010-09-07 21:05:49 +0000386 err = None
Guido van Rossumd8faa362007-04-27 19:54:29 +0000387 for res in getaddrinfo(host, port, 0, SOCK_STREAM):
388 af, socktype, proto, canonname, sa = res
389 sock = None
390 try:
391 sock = socket(af, socktype, proto)
Georg Brandlf78e02b2008-06-10 17:40:04 +0000392 if timeout is not _GLOBAL_DEFAULT_TIMEOUT:
Guido van Rossumd8faa362007-04-27 19:54:29 +0000393 sock.settimeout(timeout)
Gregory P. Smithb4066372010-01-03 03:28:29 +0000394 if source_address:
395 sock.bind(source_address)
Guido van Rossumd8faa362007-04-27 19:54:29 +0000396 sock.connect(sa)
397 return sock
398
Antoine Pitrou4b92b5f2010-09-07 21:05:49 +0000399 except error as _:
400 err = _
Guido van Rossumd8faa362007-04-27 19:54:29 +0000401 if sock is not None:
402 sock.close()
403
Antoine Pitrou4b92b5f2010-09-07 21:05:49 +0000404 if err is not None:
405 raise err
406 else:
407 raise error("getaddrinfo returns an empty list")