1# 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. 7On other systems, it only supports IP. Functions specific for a 8socket are available as methods of the socket object. 9 10Functions: 11 12socket() -- create a new socket object 13socketpair() -- create a pair of new socket objects [*] 14fromfd() -- create a socket object from an open file descriptor [*] 15fromshare() -- create a socket object from data received from socket.share() [*] 16gethostname() -- 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 20getprotobyname() -- map a protocol name (e.g. 'tcp') to a number 21ntohs(), 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) 25socket.getdefaulttimeout() -- get the default timeout value 26socket.setdefaulttimeout() -- set the default timeout value 27create_connection() -- connects to an address, with an optional timeout and 28 optional source address. 29 30 [*] not available on all platforms! 31 32Special objects: 33 34SocketType -- type object for socket objects 35error -- exception raised for I/O errors 36has_ipv6 -- boolean value indicating if IPv6 is supported 37 38IntEnum constants: 39 40AF_INET, AF_UNIX -- socket domains (first argument to socket() call) 41SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument) 42 43Integer constants: 44 45Many other constants may be defined; these may be used in calls to 46the setsockopt() and getsockopt() methods. 47""" 48 49import _socket 50from _socket import * 51 52import os, sys, io, selectors 53from enum import IntEnum, IntFlag 54 55try: 56 import errno 57except ImportError: 58 errno = None 59EBADF = getattr(errno, 'EBADF', 9) 60EAGAIN = getattr(errno, 'EAGAIN', 11) 61EWOULDBLOCK = getattr(errno, 'EWOULDBLOCK', 11) 62 63__all__ = ["fromfd", "getfqdn", "create_connection", "create_server", 64 "has_dualstack_ipv6", "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 73IntEnum._convert_( 74 'AddressFamily', 75 __name__, 76 lambda C: C.isupper() and C.startswith('AF_')) 77 78IntEnum._convert_( 79 'SocketKind', 80 __name__, 81 lambda C: C.isupper() and C.startswith('SOCK_')) 82 83IntFlag._convert_( 84 'MsgFlag', 85 __name__, 86 lambda C: C.isupper() and C.startswith('MSG_')) 87 88IntFlag._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 97def _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 110if sys.platform.lower().startswith("win"): 111 errorTab = {} 112 errorTab[6] = "Specified event object handle is invalid." 113 errorTab[8] = "Insufficient memory available." 114 errorTab[87] = "One or more parameters are invalid." 115 errorTab[995] = "Overlapped operation aborted." 116 errorTab[996] = "Overlapped I/O event object not in signaled state." 117 errorTab[997] = "Overlapped operation will complete later." 118 errorTab[10004] = "The operation was interrupted." 119 errorTab[10009] = "A bad file handle was passed." 120 errorTab[10013] = "Permission denied." 121 errorTab[10014] = "A fault occurred on the network??" # WSAEFAULT 122 errorTab[10022] = "An invalid operation was attempted." 123 errorTab[10024] = "Too many open files." 124 errorTab[10035] = "The socket operation would block" 125 errorTab[10036] = "A blocking operation is already in progress." 126 errorTab[10037] = "Operation already in progress." 127 errorTab[10038] = "Socket operation on nonsocket." 128 errorTab[10039] = "Destination address required." 129 errorTab[10040] = "Message too long." 130 errorTab[10041] = "Protocol wrong type for socket." 131 errorTab[10042] = "Bad protocol option." 132 errorTab[10043] = "Protocol not supported." 133 errorTab[10044] = "Socket type not supported." 134 errorTab[10045] = "Operation not supported." 135 errorTab[10046] = "Protocol family not supported." 136 errorTab[10047] = "Address family not supported by protocol family." 137 errorTab[10048] = "The network address is in use." 138 errorTab[10049] = "Cannot assign requested address." 139 errorTab[10050] = "Network is down." 140 errorTab[10051] = "Network is unreachable." 141 errorTab[10052] = "Network dropped connection on reset." 142 errorTab[10053] = "Software caused connection abort." 143 errorTab[10054] = "The connection has been reset." 144 errorTab[10055] = "No buffer space available." 145 errorTab[10056] = "Socket is already connected." 146 errorTab[10057] = "Socket is not connected." 147 errorTab[10058] = "The network has been shut down." 148 errorTab[10059] = "Too many references." 149 errorTab[10060] = "The operation timed out." 150 errorTab[10061] = "Connection refused." 151 errorTab[10062] = "Cannot translate name." 152 errorTab[10063] = "The name is too long." 153 errorTab[10064] = "The host is down." 154 errorTab[10065] = "The host is unreachable." 155 errorTab[10066] = "Directory not empty." 156 errorTab[10067] = "Too many processes." 157 errorTab[10068] = "User quota exceeded." 158 errorTab[10069] = "Disk quota exceeded." 159 errorTab[10070] = "Stale file handle reference." 160 errorTab[10071] = "Item is remote." 161 errorTab[10091] = "Network subsystem is unavailable." 162 errorTab[10092] = "Winsock.dll version out of range." 163 errorTab[10093] = "Successful WSAStartup not yet performed." 164 errorTab[10101] = "Graceful shutdown in progress." 165 errorTab[10102] = "No more results from WSALookupServiceNext." 166 errorTab[10103] = "Call has been canceled." 167 errorTab[10104] = "Procedure call table is invalid." 168 errorTab[10105] = "Service provider is invalid." 169 errorTab[10106] = "Service provider failed to initialize." 170 errorTab[10107] = "System call failure." 171 errorTab[10108] = "Service not found." 172 errorTab[10109] = "Class type not found." 173 errorTab[10110] = "No more results from WSALookupServiceNext." 174 errorTab[10111] = "Call was canceled." 175 errorTab[10112] = "Database query was refused." 176 errorTab[11001] = "Host not found." 177 errorTab[11002] = "Nonauthoritative host not found." 178 errorTab[11003] = "This is a nonrecoverable error." 179 errorTab[11004] = "Valid name, no data record requested type." 180 errorTab[11005] = "QoS receivers." 181 errorTab[11006] = "QoS senders." 182 errorTab[11007] = "No QoS senders." 183 errorTab[11008] = "QoS no receivers." 184 errorTab[11009] = "QoS request confirmed." 185 errorTab[11010] = "QoS admission error." 186 errorTab[11011] = "QoS policy failure." 187 errorTab[11012] = "QoS bad style." 188 errorTab[11013] = "QoS bad object." 189 errorTab[11014] = "QoS traffic control error." 190 errorTab[11015] = "QoS generic error." 191 errorTab[11016] = "QoS service type error." 192 errorTab[11017] = "QoS flowspec error." 193 errorTab[11018] = "Invalid QoS provider buffer." 194 errorTab[11019] = "Invalid QoS filter style." 195 errorTab[11020] = "Invalid QoS filter style." 196 errorTab[11021] = "Incorrect QoS filter count." 197 errorTab[11022] = "Invalid QoS object length." 198 errorTab[11023] = "Incorrect QoS flow count." 199 errorTab[11024] = "Unrecognized QoS object." 200 errorTab[11025] = "Invalid QoS policy object." 201 errorTab[11026] = "Invalid QoS flow descriptor." 202 errorTab[11027] = "Invalid QoS provider-specific flowspec." 203 errorTab[11028] = "Invalid QoS provider-specific filterspec." 204 errorTab[11029] = "Invalid QoS shape discard mode object." 205 errorTab[11030] = "Invalid QoS shaping rate object." 206 errorTab[11031] = "Reserved policy QoS element type." 207 __all__.append("errorTab") 208 209 210class _GiveupOnSendfile(Exception): pass 211 212 213class socket(_socket.socket): 214 215 """A subclass of _socket.socket adding the makefile() method.""" 216 217 __slots__ = ["__weakref__", "_io_refs", "_closed"] 218 219 def __init__(self, family=-1, type=-1, proto=-1, fileno=None): 220 # For user code address family and type values are IntEnum members, but 221 # for the underlying _socket.socket they're just integers. The 222 # constructor of _socket.socket converts the given argument to an 223 # integer automatically. 224 if fileno is None: 225 if family == -1: 226 family = AF_INET 227 if type == -1: 228 type = SOCK_STREAM 229 if proto == -1: 230 proto = 0 231 _socket.socket.__init__(self, family, type, proto, fileno) 232 self._io_refs = 0 233 self._closed = False 234 235 def __enter__(self): 236 return self 237 238 def __exit__(self, *args): 239 if not self._closed: 240 self.close() 241 242 def __repr__(self): 243 """Wrap __repr__() to reveal the real class name and socket 244 address(es). 245 """ 246 closed = getattr(self, '_closed', False) 247 s = "<%s.%s%s fd=%i, family=%s, type=%s, proto=%i" \ 248 % (self.__class__.__module__, 249 self.__class__.__qualname__, 250 " [closed]" if closed else "", 251 self.fileno(), 252 self.family, 253 self.type, 254 self.proto) 255 if not closed: 256 try: 257 laddr = self.getsockname() 258 if laddr: 259 s += ", laddr=%s" % str(laddr) 260 except error: 261 pass 262 try: 263 raddr = self.getpeername() 264 if raddr: 265 s += ", raddr=%s" % str(raddr) 266 except error: 267 pass 268 s += '>' 269 return s 270 271 def __getstate__(self): 272 raise TypeError(f"cannot pickle {self.__class__.__name__!r} object") 273 274 def dup(self): 275 """dup() -> socket object 276 277 Duplicate the socket. Return a new socket object connected to the same 278 system resource. The new socket is non-inheritable. 279 """ 280 fd = dup(self.fileno()) 281 sock = self.__class__(self.family, self.type, self.proto, fileno=fd) 282 sock.settimeout(self.gettimeout()) 283 return sock 284 285 def accept(self): 286 """accept() -> (socket object, address info) 287 288 Wait for an incoming connection. Return a new socket 289 representing the connection, and the address of the client. 290 For IP sockets, the address info is a pair (hostaddr, port). 291 """ 292 fd, addr = self._accept() 293 sock = socket(self.family, self.type, self.proto, fileno=fd) 294 # Issue #7995: if no default timeout is set and the listening 295 # socket had a (non-zero) timeout, force the new socket in blocking 296 # mode to override platform-specific socket flags inheritance. 297 if getdefaulttimeout() is None and self.gettimeout(): 298 sock.setblocking(True) 299 return sock, addr 300 301 def makefile(self, mode="r", buffering=None, *, 302 encoding=None, errors=None, newline=None): 303 """makefile(...) -> an I/O stream connected to the socket 304 305 The arguments are as for io.open() after the filename, except the only 306 supported mode values are 'r' (default), 'w' and 'b'. 307 """ 308 # XXX refactor to share code? 309 if not set(mode) <= {"r", "w", "b"}: 310 raise ValueError("invalid mode %r (only r, w, b allowed)" % (mode,)) 311 writing = "w" in mode 312 reading = "r" in mode or not writing 313 assert reading or writing 314 binary = "b" in mode 315 rawmode = "" 316 if reading: 317 rawmode += "r" 318 if writing: 319 rawmode += "w" 320 raw = SocketIO(self, rawmode) 321 self._io_refs += 1 322 if buffering is None: 323 buffering = -1 324 if buffering < 0: 325 buffering = io.DEFAULT_BUFFER_SIZE 326 if buffering == 0: 327 if not binary: 328 raise ValueError("unbuffered streams must be binary") 329 return raw 330 if reading and writing: 331 buffer = io.BufferedRWPair(raw, raw, buffering) 332 elif reading: 333 buffer = io.BufferedReader(raw, buffering) 334 else: 335 assert writing 336 buffer = io.BufferedWriter(raw, buffering) 337 if binary: 338 return buffer 339 text = io.TextIOWrapper(buffer, encoding, errors, newline) 340 text.mode = mode 341 return text 342 343 if hasattr(os, 'sendfile'): 344 345 def _sendfile_use_sendfile(self, file, offset=0, count=None): 346 self._check_sendfile_params(file, offset, count) 347 sockno = self.fileno() 348 try: 349 fileno = file.fileno() 350 except (AttributeError, io.UnsupportedOperation) as err: 351 raise _GiveupOnSendfile(err) # not a regular file 352 try: 353 fsize = os.fstat(fileno).st_size 354 except OSError as err: 355 raise _GiveupOnSendfile(err) # not a regular file 356 if not fsize: 357 return 0 # empty file 358 # Truncate to 1GiB to avoid OverflowError, see bpo-38319. 359 blocksize = min(count or fsize, 2 ** 30) 360 timeout = self.gettimeout() 361 if timeout == 0: 362 raise ValueError("non-blocking sockets are not supported") 363 # poll/select have the advantage of not requiring any 364 # extra file descriptor, contrarily to epoll/kqueue 365 # (also, they require a single syscall). 366 if hasattr(selectors, 'PollSelector'): 367 selector = selectors.PollSelector() 368 else: 369 selector = selectors.SelectSelector() 370 selector.register(sockno, selectors.EVENT_WRITE) 371 372 total_sent = 0 373 # localize variable access to minimize overhead 374 selector_select = selector.select 375 os_sendfile = os.sendfile 376 try: 377 while True: 378 if timeout and not selector_select(timeout): 379 raise _socket.timeout('timed out') 380 if count: 381 blocksize = count - total_sent 382 if blocksize <= 0: 383 break 384 try: 385 sent = os_sendfile(sockno, fileno, offset, blocksize) 386 except BlockingIOError: 387 if not timeout: 388 # Block until the socket is ready to send some 389 # data; avoids hogging CPU resources. 390 selector_select() 391 continue 392 except OSError as err: 393 if total_sent == 0: 394 # We can get here for different reasons, the main 395 # one being 'file' is not a regular mmap(2)-like 396 # file, in which case we'll fall back on using 397 # plain send(). 398 raise _GiveupOnSendfile(err) 399 raise err from None 400 else: 401 if sent == 0: 402 break # EOF 403 offset += sent 404 total_sent += sent 405 return total_sent 406 finally: 407 if total_sent > 0 and hasattr(file, 'seek'): 408 file.seek(offset) 409 else: 410 def _sendfile_use_sendfile(self, file, offset=0, count=None): 411 raise _GiveupOnSendfile( 412 "os.sendfile() not available on this platform") 413 414 def _sendfile_use_send(self, file, offset=0, count=None): 415 self._check_sendfile_params(file, offset, count) 416 if self.gettimeout() == 0: 417 raise ValueError("non-blocking sockets are not supported") 418 if offset: 419 file.seek(offset) 420 blocksize = min(count, 8192) if count else 8192 421 total_sent = 0 422 # localize variable access to minimize overhead 423 file_read = file.read 424 sock_send = self.send 425 try: 426 while True: 427 if count: 428 blocksize = min(count - total_sent, blocksize) 429 if blocksize <= 0: 430 break 431 data = memoryview(file_read(blocksize)) 432 if not data: 433 break # EOF 434 while True: 435 try: 436 sent = sock_send(data) 437 except BlockingIOError: 438 continue 439 else: 440 total_sent += sent 441 if sent < len(data): 442 data = data[sent:] 443 else: 444 break 445 return total_sent 446 finally: 447 if total_sent > 0 and hasattr(file, 'seek'): 448 file.seek(offset + total_sent) 449 450 def _check_sendfile_params(self, file, offset, count): 451 if 'b' not in getattr(file, 'mode', 'b'): 452 raise ValueError("file should be opened in binary mode") 453 if not self.type & SOCK_STREAM: 454 raise ValueError("only SOCK_STREAM type sockets are supported") 455 if count is not None: 456 if not isinstance(count, int): 457 raise TypeError( 458 "count must be a positive integer (got {!r})".format(count)) 459 if count <= 0: 460 raise ValueError( 461 "count must be a positive integer (got {!r})".format(count)) 462 463 def sendfile(self, file, offset=0, count=None): 464 """sendfile(file[, offset[, count]]) -> sent 465 466 Send a file until EOF is reached by using high-performance 467 os.sendfile() and return the total number of bytes which 468 were sent. 469 *file* must be a regular file object opened in binary mode. 470 If os.sendfile() is not available (e.g. Windows) or file is 471 not a regular file socket.send() will be used instead. 472 *offset* tells from where to start reading the file. 473 If specified, *count* is the total number of bytes to transmit 474 as opposed to sending the file until EOF is reached. 475 File position is updated on return or also in case of error in 476 which case file.tell() can be used to figure out the number of 477 bytes which were sent. 478 The socket must be of SOCK_STREAM type. 479 Non-blocking sockets are not supported. 480 """ 481 try: 482 return self._sendfile_use_sendfile(file, offset, count) 483 except _GiveupOnSendfile: 484 return self._sendfile_use_send(file, offset, count) 485 486 def _decref_socketios(self): 487 if self._io_refs > 0: 488 self._io_refs -= 1 489 if self._closed: 490 self.close() 491 492 def _real_close(self, _ss=_socket.socket): 493 # This function should not reference any globals. See issue #808164. 494 _ss.close(self) 495 496 def close(self): 497 # This function should not reference any globals. See issue #808164. 498 self._closed = True 499 if self._io_refs <= 0: 500 self._real_close() 501 502 def detach(self): 503 """detach() -> file descriptor 504 505 Close the socket object without closing the underlying file descriptor. 506 The object cannot be used after this call, but the file descriptor 507 can be reused for other purposes. The file descriptor is returned. 508 """ 509 self._closed = True 510 return super().detach() 511 512 @property 513 def family(self): 514 """Read-only access to the address family for this socket. 515 """ 516 return _intenum_converter(super().family, AddressFamily) 517 518 @property 519 def type(self): 520 """Read-only access to the socket type. 521 """ 522 return _intenum_converter(super().type, SocketKind) 523 524 if os.name == 'nt': 525 def get_inheritable(self): 526 return os.get_handle_inheritable(self.fileno()) 527 def set_inheritable(self, inheritable): 528 os.set_handle_inheritable(self.fileno(), inheritable) 529 else: 530 def get_inheritable(self): 531 return os.get_inheritable(self.fileno()) 532 def set_inheritable(self, inheritable): 533 os.set_inheritable(self.fileno(), inheritable) 534 get_inheritable.__doc__ = "Get the inheritable flag of the socket" 535 set_inheritable.__doc__ = "Set the inheritable flag of the socket" 536 537def fromfd(fd, family, type, proto=0): 538 """ fromfd(fd, family, type[, proto]) -> socket object 539 540 Create a socket object from a duplicate of the given file 541 descriptor. The remaining arguments are the same as for socket(). 542 """ 543 nfd = dup(fd) 544 return socket(family, type, proto, nfd) 545 546if hasattr(_socket.socket, "share"): 547 def fromshare(info): 548 """ fromshare(info) -> socket object 549 550 Create a socket object from the bytes object returned by 551 socket.share(pid). 552 """ 553 return socket(0, 0, 0, info) 554 __all__.append("fromshare") 555 556if hasattr(_socket, "socketpair"): 557 558 def socketpair(family=None, type=SOCK_STREAM, proto=0): 559 """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 560 561 Create a pair of socket objects from the sockets returned by the platform 562 socketpair() function. 563 The arguments are the same as for socket() except the default family is 564 AF_UNIX if defined on the platform; otherwise, the default is AF_INET. 565 """ 566 if family is None: 567 try: 568 family = AF_UNIX 569 except NameError: 570 family = AF_INET 571 a, b = _socket.socketpair(family, type, proto) 572 a = socket(family, type, proto, a.detach()) 573 b = socket(family, type, proto, b.detach()) 574 return a, b 575 576else: 577 578 # Origin: https://gist.github.com/4325783, by Geert Jansen. Public domain. 579 def socketpair(family=AF_INET, type=SOCK_STREAM, proto=0): 580 if family == AF_INET: 581 host = _LOCALHOST 582 elif family == AF_INET6: 583 host = _LOCALHOST_V6 584 else: 585 raise ValueError("Only AF_INET and AF_INET6 socket address families " 586 "are supported") 587 if type != SOCK_STREAM: 588 raise ValueError("Only SOCK_STREAM socket type is supported") 589 if proto != 0: 590 raise ValueError("Only protocol zero is supported") 591 592 # We create a connected TCP socket. Note the trick with 593 # setblocking(False) that prevents us from having to create a thread. 594 lsock = socket(family, type, proto) 595 try: 596 lsock.bind((host, 0)) 597 lsock.listen() 598 # On IPv6, ignore flow_info and scope_id 599 addr, port = lsock.getsockname()[:2] 600 csock = socket(family, type, proto) 601 try: 602 csock.setblocking(False) 603 try: 604 csock.connect((addr, port)) 605 except (BlockingIOError, InterruptedError): 606 pass 607 csock.setblocking(True) 608 ssock, _ = lsock.accept() 609 except: 610 csock.close() 611 raise 612 finally: 613 lsock.close() 614 return (ssock, csock) 615 __all__.append("socketpair") 616 617socketpair.__doc__ = """socketpair([family[, type[, proto]]]) -> (socket object, socket object) 618Create a pair of socket objects from the sockets returned by the platform 619socketpair() function. 620The arguments are the same as for socket() except the default family is AF_UNIX 621if defined on the platform; otherwise, the default is AF_INET. 622""" 623 624_blocking_errnos = { EAGAIN, EWOULDBLOCK } 625 626class SocketIO(io.RawIOBase): 627 628 """Raw I/O implementation for stream sockets. 629 630 This class supports the makefile() method on sockets. It provides 631 the raw I/O interface on top of a socket object. 632 """ 633 634 # One might wonder why not let FileIO do the job instead. There are two 635 # main reasons why FileIO is not adapted: 636 # - it wouldn't work under Windows (where you can't used read() and 637 # write() on a socket handle) 638 # - it wouldn't work with socket timeouts (FileIO would ignore the 639 # timeout and consider the socket non-blocking) 640 641 # XXX More docs 642 643 def __init__(self, sock, mode): 644 if mode not in ("r", "w", "rw", "rb", "wb", "rwb"): 645 raise ValueError("invalid mode: %r" % mode) 646 io.RawIOBase.__init__(self) 647 self._sock = sock 648 if "b" not in mode: 649 mode += "b" 650 self._mode = mode 651 self._reading = "r" in mode 652 self._writing = "w" in mode 653 self._timeout_occurred = False 654 655 def readinto(self, b): 656 """Read up to len(b) bytes into the writable buffer *b* and return 657 the number of bytes read. If the socket is non-blocking and no bytes 658 are available, None is returned. 659 660 If *b* is non-empty, a 0 return value indicates that the connection 661 was shutdown at the other end. 662 """ 663 self._checkClosed() 664 self._checkReadable() 665 if self._timeout_occurred: 666 raise OSError("cannot read from timed out object") 667 while True: 668 try: 669 return self._sock.recv_into(b) 670 except timeout: 671 self._timeout_occurred = True 672 raise 673 except error as e: 674 if e.args[0] in _blocking_errnos: 675 return None 676 raise 677 678 def write(self, b): 679 """Write the given bytes or bytearray object *b* to the socket 680 and return the number of bytes written. This can be less than 681 len(b) if not all data could be written. If the socket is 682 non-blocking and no bytes could be written None is returned. 683 """ 684 self._checkClosed() 685 self._checkWritable() 686 try: 687 return self._sock.send(b) 688 except error as e: 689 # XXX what about EINTR? 690 if e.args[0] in _blocking_errnos: 691 return None 692 raise 693 694 def readable(self): 695 """True if the SocketIO is open for reading. 696 """ 697 if self.closed: 698 raise ValueError("I/O operation on closed socket.") 699 return self._reading 700 701 def writable(self): 702 """True if the SocketIO is open for writing. 703 """ 704 if self.closed: 705 raise ValueError("I/O operation on closed socket.") 706 return self._writing 707 708 def seekable(self): 709 """True if the SocketIO is open for seeking. 710 """ 711 if self.closed: 712 raise ValueError("I/O operation on closed socket.") 713 return super().seekable() 714 715 def fileno(self): 716 """Return the file descriptor of the underlying socket. 717 """ 718 self._checkClosed() 719 return self._sock.fileno() 720 721 @property 722 def name(self): 723 if not self.closed: 724 return self.fileno() 725 else: 726 return -1 727 728 @property 729 def mode(self): 730 return self._mode 731 732 def close(self): 733 """Close the SocketIO object. This doesn't close the underlying 734 socket, except if all references to it have disappeared. 735 """ 736 if self.closed: 737 return 738 io.RawIOBase.close(self) 739 self._sock._decref_socketios() 740 self._sock = None 741 742 743def getfqdn(name=''): 744 """Get fully qualified domain name from name. 745 746 An empty argument is interpreted as meaning the local host. 747 748 First the hostname returned by gethostbyaddr() is checked, then 749 possibly existing aliases. In case no FQDN is available, hostname 750 from gethostname() is returned. 751 """ 752 name = name.strip() 753 if not name or name == '0.0.0.0': 754 name = gethostname() 755 try: 756 hostname, aliases, ipaddrs = gethostbyaddr(name) 757 except error: 758 pass 759 else: 760 aliases.insert(0, hostname) 761 for name in aliases: 762 if '.' in name: 763 break 764 else: 765 name = hostname 766 return name 767 768 769_GLOBAL_DEFAULT_TIMEOUT = object() 770 771def create_connection(address, timeout=_GLOBAL_DEFAULT_TIMEOUT, 772 source_address=None): 773 """Connect to *address* and return the socket object. 774 775 Convenience function. Connect to *address* (a 2-tuple ``(host, 776 port)``) and return the socket object. Passing the optional 777 *timeout* parameter will set the timeout on the socket instance 778 before attempting to connect. If no *timeout* is supplied, the 779 global default timeout setting returned by :func:`getdefaulttimeout` 780 is used. If *source_address* is set it must be a tuple of (host, port) 781 for the socket to bind as a source address before making the connection. 782 A host of '' or port 0 tells the OS to use the default. 783 """ 784 785 host, port = address 786 err = None 787 for res in getaddrinfo(host, port, 0, SOCK_STREAM): 788 af, socktype, proto, canonname, sa = res 789 sock = None 790 try: 791 sock = socket(af, socktype, proto) 792 if timeout is not _GLOBAL_DEFAULT_TIMEOUT: 793 sock.settimeout(timeout) 794 if source_address: 795 sock.bind(source_address) 796 sock.connect(sa) 797 # Break explicitly a reference cycle 798 err = None 799 return sock 800 801 except error as _: 802 err = _ 803 if sock is not None: 804 sock.close() 805 806 if err is not None: 807 try: 808 raise err 809 finally: 810 # Break explicitly a reference cycle 811 err = None 812 else: 813 raise error("getaddrinfo returns an empty list") 814 815 816def has_dualstack_ipv6(): 817 """Return True if the platform supports creating a SOCK_STREAM socket 818 which can handle both AF_INET and AF_INET6 (IPv4 / IPv6) connections. 819 """ 820 if not has_ipv6 \ 821 or not hasattr(_socket, 'IPPROTO_IPV6') \ 822 or not hasattr(_socket, 'IPV6_V6ONLY'): 823 return False 824 try: 825 with socket(AF_INET6, SOCK_STREAM) as sock: 826 sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 0) 827 return True 828 except error: 829 return False 830 831 832def create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, 833 dualstack_ipv6=False): 834 """Convenience function which creates a SOCK_STREAM type socket 835 bound to *address* (a 2-tuple (host, port)) and return the socket 836 object. 837 838 *family* should be either AF_INET or AF_INET6. 839 *backlog* is the queue size passed to socket.listen(). 840 *reuse_port* dictates whether to use the SO_REUSEPORT socket option. 841 *dualstack_ipv6*: if true and the platform supports it, it will 842 create an AF_INET6 socket able to accept both IPv4 or IPv6 843 connections. When false it will explicitly disable this option on 844 platforms that enable it by default (e.g. Linux). 845 846 >>> with create_server((None, 8000)) as server: 847 ... while True: 848 ... conn, addr = server.accept() 849 ... # handle new connection 850 """ 851 if reuse_port and not hasattr(_socket, "SO_REUSEPORT"): 852 raise ValueError("SO_REUSEPORT not supported on this platform") 853 if dualstack_ipv6: 854 if not has_dualstack_ipv6(): 855 raise ValueError("dualstack_ipv6 not supported on this platform") 856 if family != AF_INET6: 857 raise ValueError("dualstack_ipv6 requires AF_INET6 family") 858 sock = socket(family, SOCK_STREAM) 859 try: 860 # Note about Windows. We don't set SO_REUSEADDR because: 861 # 1) It's unnecessary: bind() will succeed even in case of a 862 # previous closed socket on the same address and still in 863 # TIME_WAIT state. 864 # 2) If set, another socket is free to bind() on the same 865 # address, effectively preventing this one from accepting 866 # connections. Also, it may set the process in a state where 867 # it'll no longer respond to any signals or graceful kills. 868 # See: msdn2.microsoft.com/en-us/library/ms740621(VS.85).aspx 869 if os.name not in ('nt', 'cygwin') and \ 870 hasattr(_socket, 'SO_REUSEADDR'): 871 try: 872 sock.setsockopt(SOL_SOCKET, SO_REUSEADDR, 1) 873 except error: 874 # Fail later on bind(), for platforms which may not 875 # support this option. 876 pass 877 if reuse_port: 878 sock.setsockopt(SOL_SOCKET, SO_REUSEPORT, 1) 879 if has_ipv6 and family == AF_INET6: 880 if dualstack_ipv6: 881 sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 0) 882 elif hasattr(_socket, "IPV6_V6ONLY") and \ 883 hasattr(_socket, "IPPROTO_IPV6"): 884 sock.setsockopt(IPPROTO_IPV6, IPV6_V6ONLY, 1) 885 try: 886 sock.bind(address) 887 except error as err: 888 msg = '%s (while attempting to bind on address %r)' % \ 889 (err.strerror, address) 890 raise error(err.errno, msg) from None 891 if backlog is None: 892 sock.listen() 893 else: 894 sock.listen(backlog) 895 return sock 896 except error: 897 sock.close() 898 raise 899 900 901def getaddrinfo(host, port, family=0, type=0, proto=0, flags=0): 902 """Resolve host and port into list of address info entries. 903 904 Translate the host/port argument into a sequence of 5-tuples that contain 905 all the necessary arguments for creating a socket connected to that service. 906 host is a domain name, a string representation of an IPv4/v6 address or 907 None. port is a string service name such as 'http', a numeric port number or 908 None. By passing None as the value of host and port, you can pass NULL to 909 the underlying C API. 910 911 The family, type and proto arguments can be optionally specified in order to 912 narrow the list of addresses returned. Passing zero as a value for each of 913 these arguments selects the full range of results. 914 """ 915 # We override this function since we want to translate the numeric family 916 # and socket type values to enum constants. 917 addrlist = [] 918 for res in _socket.getaddrinfo(host, port, family, type, proto, flags): 919 af, socktype, proto, canonname, sa = res 920 addrlist.append((_intenum_converter(af, AddressFamily), 921 _intenum_converter(socktype, SocketKind), 922 proto, canonname, sa)) 923 return addrlist 924