1 # Wrapper module for _socket, providing some additional facilities 2 # implemented in Python. 3 4 """\ 5 This module provides socket operations and some related functions. 6 On Unix, it supports IP (Internet Protocol) and Unix domain sockets. 7 On other systems, it only supports IP. Functions specific for a 8 socket are available as methods of the socket object. 9 10 Functions: 11 12 socket() -- create a new socket object 13 socketpair() -- create a pair of new socket objects [*] 14 fromfd() -- create a socket object from an open file descriptor [*] 15 fromshare() -- create a socket object from data received from socket.share() [*] 16 gethostname() -- return the current hostname 17 gethostbyname() -- map a hostname to its IP number 18 gethostbyaddr() -- map an IP number or hostname to DNS info 19 getservbyname() -- map a service name and a protocol name to a port number 20 getprotobyname() -- map a protocol name (e.g. 'tcp') to a number 21 ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order 22 htons(), htonl() -- convert 16, 32 bit int from host to network byte order 23 inet_aton() -- convert IP addr string (123.45.67.89) to 32-bit packed format 24 inet_ntoa() -- convert 32-bit packed format IP to string (123.45.67.89) 25 socket.getdefaulttimeout() -- get the default timeout value 26 socket.setdefaulttimeout() -- set the default timeout value 27 create_connection() -- connects to an address, with an optional timeout and 28 optional source address. 29 30 [*] not available on all platforms! 31 32 Special objects: 33 34 SocketType -- type object for socket objects 35 error -- exception raised for I/O errors 36 has_ipv6 -- boolean value indicating if IPv6 is supported 37 38 IntEnum constants: 39 40 AF_INET, AF_UNIX -- socket domains (first argument to socket() call) 41 SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument) 42 43 Integer constants: 44 45 Many other constants may be defined; these may be used in calls to 46 the setsockopt() and getsockopt() methods. 47 """ 48 49 import _socket 50 from _socket import * 51 52 import os, sys, io, selectors 53 from enum import IntEnum, IntFlag 54 55 try: 56 import errno 57 except ImportError: 58 errno = None 59 EBADF = getattr(errno, 'EBADF', 9) 60 EAGAIN = getattr(errno, 'EAGAIN', 11) 61 EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11) 62 63 __all__ = ["fromfd", "getfqdn", "create_connection", 64 "AddressFamily", "SocketKind"] 65 __all__.extend(os._get_exports_list(_socket)) 66 67 # Set up the socket.AF_* socket.SOCK_* constants as members of IntEnums for 68 # nicer string representations. 69 # Note that _socket only knows about the integer values. The public interface 70 # in this module understands the enums and translates them back from integers 71 # where needed (e.g. .family property of a socket object). 72 73 IntEnum._convert( 74 'AddressFamily', 75 __name__, 76 lambda C: C.isupper() and C.startswith('AF_')) 77 78 IntEnum._convert( 79 'SocketKind', 80 __name__, 81 lambda C: C.isupper() and C.startswith('SOCK_')) 82 83 IntFlag._convert( 84 'MsgFlag', 85 __name__, 86 lambda C: C.isupper() and C.startswith('MSG_')) 87 88 IntFlag._convert( 89 'AddressInfo', 90 __name__, 91 lambda C: C.isupper() and C.startswith('AI_')) 92 93 _LOCALHOST = '127.0.0.1' 94 _LOCALHOST_V6 = '::1' 95 96 97 def _intenum_converter(value, enum_klass): 98 """Convert a numeric family value to an IntEnum member. 99 100 If it's not a known member, return the numeric value itself. 101 """ 102 try: 103 return enum_klass(value) 104 except ValueError: 105 return value 106 107 _realsocket = socket 108 109 # WSA error codes 110 if sys.platform.lower().startswith("win"): 111 errorTab = {} 112 errorTab[10004] = "The operation was interrupted." 113 errorTab[10009] = "A bad file handle was passed." 114 errorTab[10013] = "Permission denied." 115 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT 116 errorTab[10022] = "An invalid operation was attempted." 117 errorTab[10035] = "The socket operation would block" 118 errorTab[10036] = "A blocking operation is already in progress." 119 errorTab[10048] = "The network address is in use." 120 errorTab[10054] = "The connection has been reset." 121 errorTab[10058] = "The network has been shut down." 122 errorTab[10060] = "The operation timed out." 123 errorTab[10061] = "Connection refused." 124 errorTab[10063] = "The name is too long." 125 errorTab[10064] = "The host is down." 126 errorTab[10065] = "The host is unreachable." 127 __all__.append("errorTab") 128 129 130 class _GiveupOnSendfile(Exception): pass 131 132 133 class socket(_socket.socket): 134 135 """A subclass of _socket.socket adding the makefile() method.""" 136 137 __slots__ = ["__weakref__", "_io_refs", "_closed"] 138 139 def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None): 140 # For user code address family and type values are IntEnum members, but 141 # for the underlying _socket.socket they're just integers. The 142 # constructor of _socket.socket converts the given argument to an 143 # integer automatically. 144 _socket.socket.__init__(self, family, type, proto, fileno) 145 self._io_refs = 0 146 self._closed = False 147 148 def __enter__(self): 149 return self 150 151 def __exit__(self, *args): 152 if not self._closed: 153 self.close() 154 155 def __repr__(self): 156 """Wrap __repr__() to reveal the real class name and socket 157 address(es). 158 """ 159 closed = getattr(self, '_closed', False) 160 s = "<%s.%s%s fd=%i, family=%s, type=%s, proto=%i" \ 161 % (self.__class__.__module__, 162 self.__class__.__qualname__, 163 " [closed]" if closed else "", 164 self.fileno(), 165 self.family, 166 self.type, 167 self.proto) 168 if not closed: 169 try: 170 laddr = self.getsockname() 171 if laddr: 172 s += ", laddr=%s" % str(laddr) 173 except error: 174 pass 175 try: 176 raddr = self.getpeername() 177 if raddr: 178 s += ", raddr=%s" % str(raddr) 179 except error: 180 pass 181 s += '>' 182 return s 183 184 def __getstate__(self): 185 raise TypeError("Cannot serialize socket object") 186 187 def dup(self): 188 """dup() -> socket object 189 190 Duplicate the socket. Return a new socket object connected to the same 191 system resource. The new socket is non-inheritable. 192 """ 193 fd = dup(self.fileno()) 194 sock = self.__class__(self.family, self.type, self.proto, fileno=fd) 195 sock.settimeout(self.gettimeout()) 196 return sock 197 198 def accept(self): 199 """accept() -> (socket object, address info) 200 201 Wait for an incoming connection. Return a new socket 202 representing the connection, and the address of the client. 203 For IP sockets, the address info is a pair (hostaddr, port). 204 """ 205 fd, addr = self._accept() 206 # If our type has the SOCK_NONBLOCK flag, we shouldn't pass it onto the 207 # new socket. We do not currently allow passing SOCK_NONBLOCK to 208 # accept4, so the returned socket is always blocking. 209 type = self.type & ~globals().get("SOCK_NONBLOCK", 0) 210 sock = socket(self.family, type, self.proto, fileno=fd) 211 # Issue #7995: if no default timeout is set and the listening 212 # socket had a (non-zero) timeout, force the new socket in blocking 213 # mode to override platform-specific socket flags inheritance. 214 if getdefaulttimeout() is None and self.gettimeout(): 215 sock.setblocking(True) 216 return sock, addr 217 218 def makefile(self, mode="r", buffering=None, *, 219 encoding=None, errors=None, newline=None): 220 """makefile(...) -> an I/O stream connected to the socket 221 222 The arguments are as for io.open() after the filename, except the only 223 supported mode values are 'r' (default), 'w' and 'b'. 224 """ 225 # XXX refactor to share code? 226 if not set(mode) <= {"r", "w", "b"}: 227 raise ValueError("invalid mode %r (only r, w, b allowed)" % (mode,)) 228 writing = "w" in mode 229 reading = "r" in mode or not writing 230 assert reading or writing 231 binary = "b" in mode 232 rawmode = "" 233 if reading: 234 rawmode += "r" 235 if writing: 236 rawmode += "w" 237 raw = SocketIO(self, rawmode) 238 self._io_refs += 1 239 if buffering is None: 240 buffering = -1 241 if buffering < 0: 242 buffering = io.DEFAULT_BUFFER_SIZE 243 if buffering == 0: 244 if not binary: 245 raise ValueError("unbuffered streams must be binary") 246 return raw 247 if reading and writing: 248 buffer = io.BufferedRWPair(raw, raw, buffering) 249 elif reading: 250 buffer = io.BufferedReader(raw, buffering) 251 else: 252 assert writing 253 buffer = io.BufferedWriter(raw, buffering) 254 if binary: 255 return buffer 256 text = io.TextIOWrapper(buffer, encoding, errors, newline) 257 text.mode = mode 258 return text 259 260 if hasattr(os, 'sendfile'): 261 262 def _sendfile_use_sendfile(self, file, offset=0, count=None): 263 self._check_sendfile_params(file, offset, count) 264 sockno = self.fileno() 265 try: 266 fileno = file.fileno() 267 except (AttributeError, io.UnsupportedOperation) as err: 268 raise _GiveupOnSendfile(err) # not a regular file 269 try: 270 fsize = os.fstat(fileno).st_size 271 except OSError as err: 272 raise _GiveupOnSendfile(err) # not a regular file 273 if not fsize: 274 return 0 # empty file 275 blocksize = fsize if not count else count 276 277 timeout = self.gettimeout() 278 if timeout == 0: 279 raise ValueError("non-blocking sockets are not supported") 280 # poll/select have the advantage of not requiring any 281 # extra file descriptor, contrarily to epoll/kqueue 282 # (also, they require a single syscall). 283 if hasattr(selectors, 'PollSelector'): 284 selector = selectors.PollSelector() 285 else: 286 selector = selectors.SelectSelector() 287 selector.register(sockno, selectors.EVENT_WRITE) 288 289 total_sent = 0 290 # localize variable access to minimize overhead 291 selector_select = selector.select 292 os_sendfile = os.sendfile 293 try: 294 while True: 295 if timeout and not selector_select(timeout): 296 raise _socket.timeout('timed out') 297 if count: 298 blocksize = count - total_sent 299 if blocksize <= 0: 300 break 301 try: 302 sent = os_sendfile(sockno, fileno, offset, blocksize) 303 except BlockingIOError: 304 if not timeout: 305 # Block until the socket is ready to send some 306 # data; avoids hogging CPU resources. 307 selector_select() 308 continue 309 except OSError as err: 310 if total_sent == 0: 311 # We can get here for different reasons, the main 312 # one being 'file' is not a regular mmap(2)-like 313 # file, in which case we'll fall back on using 314 # plain send(). 315 raise _GiveupOnSendfile(err) 316 raise err from None 317 else: 318 if sent == 0: 319 break # EOF 320 offset += sent 321 total_sent += sent 322 return total_sent 323 finally: 324 if total_sent > 0 and hasattr(file, 'seek'): 325 file.seek(offset) 326 else: 327 def _sendfile_use_sendfile(self, file, offset=0, count=None): 328 raise _GiveupOnSendfile( 329 "os.sendfile() not available on this platform") 330 331 def _sendfile_use_send(self, file, offset=0, count=None): 332 self._check_sendfile_params(file, offset, count) 333 if self.gettimeout() == 0: 334 raise ValueError("non-blocking sockets are not supported") 335 if offset: 336 file.seek(offset) 337 blocksize = min(count, 8192) if count else 8192 338 total_sent = 0 339 # localize variable access to minimize overhead 340 file_read = file.read 341 sock_send = self.send 342 try: 343 while True: 344 if count: 345 blocksize = min(count - total_sent, blocksize) 346 if blocksize <= 0: 347 break 348 data = memoryview(file_read(blocksize)) 349 if not data: 350 break # EOF 351 while True: 352 try: 353 sent = sock_send(data) 354 except BlockingIOError: 355 continue 356 else: 357 total_sent += sent 358 if sent < len(data): 359 data = data[sent:] 360 else: 361 break 362 return total_sent 363 finally: 364 if total_sent > 0 and hasattr(file, 'seek'): 365 file.seek(offset + total_sent) 366 367 def _check_sendfile_params(self, file, offset, count): 368 if 'b' not in getattr(file, 'mode', 'b'): 369 raise ValueError("file should be opened in binary mode") 370 if not self.type & SOCK_STREAM: 371 raise ValueError("only SOCK_STREAM type sockets are supported") 372 if count is not None: 373 if not isinstance(count, int): 374 raise TypeError( 375 "count must be a positive integer (got {!r})".format(count)) 376 if count <= 0: 377 raise ValueError( 378 "count must be a positive integer (got {!r})".format(count)) 379 380 def sendfile(self, file, offset=0, count=None): 381 """sendfile(file[, offset[, count]]) -> sent 382 383 Send a file until EOF is reached by using high-performance 384 os.sendfile() and return the total number of bytes which 385 were sent. 386 *file* must be a regular file object opened in binary mode. 387 If os.sendfile() is not available (e.g. Windows) or file is 388 not a regular file socket.send() will be used instead. 389 *offset* tells from where to start reading the file. 390 If specified, *count* is the total number of bytes to transmit 391 as opposed to sending the file until EOF is reached. 392 File position is updated on return or also in case of error in 393 which case file.tell() can be used to figure out the number of 394 bytes which were sent. 395 The socket must be of SOCK_STREAM type. 396 Non-blocking sockets are not supported. 397 """ 398 try: 399 return self._sendfile_use_sendfile(file, offset, count) 400 except _GiveupOnSendfile: 401 return self._sendfile_use_send(file, offset, count) 402 403 def _decref_socketios(self): 404 if self._io_refs > 0: 405 self._io_refs -= 1 406 if self._closed: 407 self.close() 408 409 def _real_close(self, _ss=_socket.socket): 410 # This function should not reference any globals. See issue #808164. 411 _ss.close(self) 412 413 def close(self): 414 # This function should not reference any globals. See issue #808164. 415 self._closed = True 416 if self._io_refs <= 0: 417 self._real_close() 418 419 def detach(self): 420 """detach() -> file descriptor 421 422 Close the socket object without closing the underlying file descriptor. 423 The object cannot be used after this call, but the file descriptor 424 can be reused for other purposes. The file descriptor is returned. 425 """ 426 self._closed = True 427 return super().detach() 428 429 @property 430 def family(self): 431 """Read-only access to the address family for this socket. 432 """ 433 return _intenum_converter(super().family, AddressFamily) 434 435 @property 436 def type(self): 437 """Read-only access to the socket type. 438 """ 439 return _intenum_converter(super().type, SocketKind) 440 441 if os.name == 'nt': 442 def get_inheritable(self): 443 return os.get_handle_inheritable(self.fileno()) 444 def set_inheritable(self, inheritable): 445 os.set_handle_inheritable(self.fileno(), inheritable) 446 else: 447 def get_inheritable(self): 448 return os.get_inheritable(self.fileno()) 449 def set_inheritable(self, inheritable): 450 os.set_inheritable(self.fileno(), inheritable) 451 get_inheritable.__doc__ = "Get the inheritable flag of the socket" 452 set_inheritable.__doc__ = "Set the inheritable flag of the socket" 453 454 def fromfd(fd, family, type, proto=0): 455 """ fromfd(fd, family, type[, proto]) -> socket object 456 457 Create a socket object from a duplicate of the given file 458 descriptor. The remaining arguments are the same as for socket(). 459 """ 460 nfd = dup(fd) 461 return socket(family, type, proto, nfd) 462 463 if hasattr(_socket.socket, "share"): 464 def fromshare(info): 465 """ fromshare(info) -> socket object 466 467 Create a socket object from the bytes object returned by 468 socket.share(pid). 469 """ 470 return socket(0, 0, 0, info) 471 __all__.append("fromshare") 472 473 if hasattr(_socket, "socketpair"): 474 475 def socketpair(family=None, type=SOCK_STREAM, proto=0): 476 """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 477 478 Create a pair of socket objects from the sockets returned by the platform 479 socketpair() function. 480 The arguments are the same as for socket() except the default family is 481 AF_UNIX if defined on the platform; otherwise, the default is AF_INET. 482 """ 483 if family is None: 484 try: 485 family = AF_UNIX 486 except NameError: 487 family = AF_INET 488 a, b = _socket.socketpair(family, type, proto) 489 a = socket(family, type, proto, a.detach()) 490 b = socket(family, type, proto, b.detach()) 491 return a, b 492 493 else: 494 495 # Origin: https://gist.github.com/4325783, by Geert Jansen. Public domain. 496 def socketpair(family=AF_INET, type=SOCK_STREAM, proto=0): 497 if family == AF_INET: 498 host = _LOCALHOST 499 elif family == AF_INET6: 500 host = _LOCALHOST_V6 501 else: 502 raise ValueError("Only AF_INET and AF_INET6 socket address families " 503 "are supported") 504 if type != SOCK_STREAM: 505 raise ValueError("Only SOCK_STREAM socket type is supported") 506 if proto != 0: 507 raise ValueError("Only protocol zero is supported") 508 509 # We create a connected TCP socket. Note the trick with 510 # setblocking(False) that prevents us from having to create a thread. 511 lsock = socket(family, type, proto) 512 try: 513 lsock.bind((host, 0)) 514 lsock.listen() 515 # On IPv6, ignore flow_info and scope_id 516 addr, port = lsock.getsockname()[:2] 517 csock = socket(family, type, proto) 518 try: 519 csock.setblocking(False) 520 try: 521 csock.connect((addr, port)) 522 except (BlockingIOError, InterruptedError): 523 pass 524 csock.setblocking(True) 525 ssock, _ = lsock.accept() 526 except: 527 csock.close() 528 raise 529 finally: 530 lsock.close() 531 return (ssock, csock) 532 __all__.append("socketpair") 533 534 socketpair.__doc__ = """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 535 Create a pair of socket objects from the sockets returned by the platform 536 socketpair() function. 537 The arguments are the same as for socket() except the default family is AF_UNIX 538 if defined on the platform; otherwise, the default is AF_INET. 539 """ 540 541 _blocking_errnos = { EAGAIN, EWOULDBLOCK } 542 543 class SocketIO(io.RawIOBase): 544 545 """Raw I/O implementation for stream sockets. 546 547 This class supports the makefile() method on sockets. It provides 548 the raw I/O interface on top of a socket object. 549 """ 550 551 # One might wonder why not let FileIO do the job instead. There are two 552 # main reasons why FileIO is not adapted: 553 # - it wouldn't work under Windows (where you can't used read() and 554 # write() on a socket handle) 555 # - it wouldn't work with socket timeouts (FileIO would ignore the 556 # timeout and consider the socket non-blocking) 557 558 # XXX More docs 559 560 def __init__(self, sock, mode): 561 if mode not in ("r", "w", "rw", "rb", "wb", "rwb"): 562 raise ValueError("invalid mode: %r" % mode) 563 io.RawIOBase.__init__(self) 564 self._sock = sock 565 if "b" not in mode: 566 mode += "b" 567 self._mode = mode 568 self._reading = "r" in mode 569 self._writing = "w" in mode 570 self._timeout_occurred = False 571 572 def readinto(self, b): 573 """Read up to len(b) bytes into the writable buffer *b* and return 574 the number of bytes read. If the socket is non-blocking and no bytes 575 are available, None is returned. 576 577 If *b* is non-empty, a 0 return value indicates that the connection 578 was shutdown at the other end. 579 """ 580 self._checkClosed() 581 self._checkReadable() 582 if self._timeout_occurred: 583 raise OSError("cannot read from timed out object") 584 while True: 585 try: 586 return self._sock.recv_into(b) 587 except timeout: 588 self._timeout_occurred = True 589 raise 590 except error as e: 591 if e.args[0] in _blocking_errnos: 592 return None 593 raise 594 595 def write(self, b): 596 """Write the given bytes or bytearray object *b* to the socket 597 and return the number of bytes written. This can be less than 598 len(b) if not all data could be written. If the socket is 599 non-blocking and no bytes could be written None is returned. 600 """ 601 self._checkClosed() 602 self._checkWritable() 603 try: 604 return self._sock.send(b) 605 except error as e: 606 # XXX what about EINTR? 607 if e.args[0] in _blocking_errnos: 608 return None 609 raise 610 611 def readable(self): 612 """True if the SocketIO is open for reading. 613 """ 614 if self.closed: 615 raise ValueError("I/O operation on closed socket.") 616 return self._reading 617 618 def writable(self): 619 """True if the SocketIO is open for writing. 620 """ 621 if self.closed: 622 raise ValueError("I/O operation on closed socket.") 623 return self._writing 624 625 def seekable(self): 626 """True if the SocketIO is open for seeking. 627 """ 628 if self.closed: 629 raise ValueError("I/O operation on closed socket.") 630 return super().seekable() 631 632 def fileno(self): 633 """Return the file descriptor of the underlying socket. 634 """ 635 self._checkClosed() 636 return self._sock.fileno() 637 638 @property 639 def name(self): 640 if not self.closed: 641 return self.fileno() 642 else: 643 return -1 644 645 @property 646 def mode(self): 647 return self._mode 648 649 def close(self): 650 """Close the SocketIO object. This doesn't close the underlying 651 socket, except if all references to it have disappeared. 652 """ 653 if self.closed: 654 return 655 io.RawIOBase.close(self) 656 self._sock._decref_socketios() 657 self._sock = None 658 659 660 def getfqdn(name=''): 661 """Get fully qualified domain name from name. 662 663 An empty argument is interpreted as meaning the local host. 664 665 First the hostname returned by gethostbyaddr() is checked, then 666 possibly existing aliases. In case no FQDN is available, hostname 667 from gethostname() is returned. 668 """ 669 name = name.strip() 670 if not name or name == '0.0.0.0': 671 name = gethostname() 672 try: 673 hostname, aliases, ipaddrs = gethostbyaddr(name) 674 except error: 675 pass 676 else: 677 aliases.insert(0, hostname) 678 for name in aliases: 679 if '.' in name: 680 break 681 else: 682 name = hostname 683 return name 684 685 686 _GLOBAL_DEFAULT_TIMEOUT = object() 687 688 def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT, 689 source_address=None): 690 """Connect to *address* and return the socket object. 691 692 Convenience function. Connect to *address* (a 2-tuple ``(host, 693 port)``) and return the socket object. Passing the optional 694 *timeout* parameter will set the timeout on the socket instance 695 before attempting to connect. If no *timeout* is supplied, the 696 global default timeout setting returned by :func:`getdefaulttimeout` 697 is used. If *source_address* is set it must be a tuple of (host, port) 698 for the socket to bind as a source address before making the connection. 699 A host of '' or port 0 tells the OS to use the default. 700 """ 701 702 host, port = address 703 err = None 704 for res in getaddrinfo(host, port, 0, SOCK_STREAM): 705 af, socktype, proto, canonname, sa = res 706 sock = None 707 try: 708 sock = socket(af, socktype, proto) 709 if timeout is not _GLOBAL_DEFAULT_TIMEOUT: 710 sock.settimeout(timeout) 711 if source_address: 712 sock.bind(source_address) 713 sock.connect(sa) 714 return sock 715 716 except error as _: 717 err = _ 718 if sock is not None: 719 sock.close() 720 721 if err is not None: 722 raise err 723 else: 724 raise error("getaddrinfo returns an empty list") 725 726 def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0): 727 """Resolve host and port into list of address info entries. 728 729 Translate the host/port argument into a sequence of 5-tuples that contain 730 all the necessary arguments for creating a socket connected to that service. 731 host is a domain name, a string representation of an IPv4/v6 address or 732 None. port is a string service name such as 'http', a numeric port number or 733 None. By passing None as the value of host and port, you can pass NULL to 734 the underlying C API. 735 736 The family, type and proto arguments can be optionally specified in order to 737 narrow the list of addresses returned. Passing zero as a value for each of 738 these arguments selects the full range of results. 739 """ 740 # We override this function since we want to translate the numeric family 741 # and socket type values to enum constants. 742 addrlist = [] 743 for res in _socket.getaddrinfo(host, port, family, type, proto, flags): 744 af, socktype, proto, canonname, sa = res 745 addrlist.append((_intenum_converter(af, AddressFamily), 746 _intenum_converter(socktype, SocketKind), 747 proto, canonname, sa)) 748 return addrlist 749
