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