Lines Matching full:socket
1 :mod:`socket` --- Low-level networking interface
4 .. module:: socket
8 This module provides access to the BSD *socket* interface. It is available on
15 system socket APIs.
17 For an introduction to socket programming (in C), see the following papers: An
22 socket-related system calls are also a valuable source of information on the
23 details of socket semantics. For Unix, refer to the manual pages; for Windows,
25 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6.
27 .. index:: object: socket
31 :func:`.socket` function returns a :dfn:`socket object` whose methods implement
32 the various socket system calls. Parameter types are somewhat higher-level than
39 Socket addresses are represented as follows: A single string is used for the
47 :mod:`socket` module methods, *flowinfo* and *scopeid* can be omitted just for
50 supported. The address format required by a particular socket object is
51 automatically selected based on the address family specified when the socket
60 If you use a hostname in the *host* portion of IPv4/v6 socket address, the
62 returned from the DNS resolution. The socket address will be resolved
92 and out-of-memory conditions can be raised; errors related to socket or address
93 semantics raise the error :exc:`socket.error`.
95 Non-blocking mode is supported through :meth:`~socket.setblocking`. A
97 :meth:`~socket.settimeout`.
99 The module :mod:`socket` exports the following constants and functions:
106 This exception is raised for socket-related errors. The accompanying value is
113 :exc:`socket.error` is now a child class of :exc:`IOError`.
139 This exception is raised when a timeout occurs on a socket which has had
151 first argument to :func:`.socket`. If the :const:`AF_UNIX` constant is not
161 These constants represent the socket types, used for the second argument to
162 :func:`socket`. (Only :const:`SOCK_STREAM` and :const:`SOCK_DGRAM` appear to be
181 and/or the IP protocol, are also defined in the socket module. They are
183 methods of socket objects. In most cases, only those symbols that are defined
191 :meth:`~socket.socket.ioctl` method of socket objects.
197 TIPC related constants, matching the ones exported by the C socket API. See
213 ``(host, port)``), and return the socket object. This is a higher-level
214 function than :meth:`socket.connect`: if *host* is a non-numeric hostname,
221 socket instance before attempting to connect. If no *timeout* is
226 socket to bind to as its source address before connecting. If host or port
238 all the necessary arguments for creating a socket connected to that service.
257 meant to be passed to the :func:`.socket` function. *canonname* will be
260 will be empty. *sockaddr* is a tuple describing a socket address, whose
263 :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
270 >>> socket.getaddrinfo("example.org", 80, 0, 0, socket.IPPROTO_TCP)
337 Translate a socket address *sockaddr* into a 2-tuple ``(host, port)``. Depending
348 suitable for passing as the (optional) third argument to the :func:`.socket`
350 (:const:`SOCK_RAW`); for the normal socket modes, the correct protocol is chosen
368 .. function:: socket([family[, type[, proto]]])
370 Create a new socket using the given address family, socket type and protocol
372 :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be
380 Build a pair of connected socket objects using the given address family, socket
381 type, and protocol number. Address family, socket type, and protocol number are
382 as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
392 :meth:`fileno` method) and build a socket object from the result. Address
393 family, socket type and protocol number are as for the :func:`.socket` function
394 above. The file descriptor should refer to a socket, but this is not checked ---
396 This function is rarely needed, but can be used to get or set socket options on
397 a socket passed to a program as standard input or output (such as a server
398 started by the Unix inet daemon). The socket is assumed to be in blocking mode.
442 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
458 :exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and
471 :exc:`socket.error` will be raised. Note that exactly what is valid depends on
491 :exc:`socket.error` is raised for errors from the call to :func:`inet_ntop`.
500 Return the default timeout in seconds (float) for new socket objects. A value
501 of ``None`` indicates that new socket objects have no timeout. When the socket
509 Set the default timeout in seconds (float) for new socket objects. A value of
510 ``None`` indicates that new socket objects have no timeout. When the socket
518 This is a Python type object that represents the socket object type. It is the
519 same as ``type(socket(...))``.
528 A TLS/SSL wrapper for socket objects.
533 Socket Objects
536 Socket objects have the following methods. Except for :meth:`makefile` these
540 .. method:: socket.accept()
542 Accept a connection. The socket must be bound to an address and listening for
544 *new* socket object usable to send and receive data on the connection, and
545 *address* is the address bound to the socket on the other end of the connection.
548 .. method:: socket.bind(address)
550 Bind the socket to *address*. The socket must not already be bound. (The format
560 .. method:: socket.close()
562 Close the socket. All future operations on the socket object will fail. The
574 .. method:: socket.connect(address)
576 Connect to a remote socket at *address*. (The format of *address* depends on the
586 .. method:: socket.connect_ex(address)
602 .. method:: socket.fileno()
604 Return the socket's file descriptor (a small integer). This is useful with
612 .. method:: socket.getpeername()
614 Return the remote address to which the socket is connected. This is useful to
615 find out the port number of a remote IPv4/v6 socket, for instance. (The format
620 .. method:: socket.getsockname()
622 Return the socket's own address. This is useful to find out the port number of
623 an IPv4/v6 socket, for instance. (The format of the address returned depends on
627 .. method:: socket.getsockopt(level, optname[, buflen])
629 Return the value of the given socket option (see the Unix man page
639 .. method:: socket.ioctl(control, option)
649 functions may be used; they accept a socket object as their first argument.
654 .. method:: socket.listen(backlog)
656 Listen for connections made to the socket. The *backlog* argument specifies the
661 .. method:: socket.makefile([mode[, bufsize]])
665 Return a :dfn:`file object` associated with the socket. (File objects are
667 socket explicitly when its :meth:`close` method is called, but only removes
668 its reference to the socket object, so that the socket will be closed if it
671 The socket must be in blocking mode (it can not have a timeout). The optional
682 .. method:: socket.recv(bufsize[, flags])
684 Receive data from the socket. The return value is a string representing the
695 .. method:: socket.recvfrom(bufsize[, flags])
697 Receive data from the socket. The return value is a pair ``(string, address)``
699 address of the socket sending the data. See the Unix manual page
704 .. method:: socket.recvfrom_into(buffer[, nbytes[, flags]])
706 Receive data from the socket, writing it into *buffer* instead of creating a
708 the number of bytes received and *address* is the address of the socket sending
716 .. method:: socket.recv_into(buffer[, nbytes[, flags]])
718 Receive up to *nbytes* bytes from the socket, storing the data into a buffer
727 .. method:: socket.send(string[, flags])
729 Send data to the socket. The socket must be connected to a remote socket. The
734 information on this concept, consult the :ref:`socket-howto`.
737 .. method:: socket.sendall(string[, flags])
739 Send data to the socket. The socket must be connected to a remote socket. The
747 .. method:: socket.sendto(string, address)
748 socket.sendto(string, flags, address)
750 Send data to the socket. The socket should not be connected to a remote socket,
751 since the destination socket is specified by *address*. The optional *flags*
757 .. method:: socket.setblocking(flag)
759 Set blocking or non-blocking mode of the socket: if *flag* is 0, the socket is
768 .. method:: socket.settimeout(value)
770 Set a timeout on blocking socket operations. The *value* argument can be a
772 subsequent socket operations will raise a :exc:`timeout` exception if the
774 a timeout of ``None`` disables timeouts on socket operations.
781 .. method:: socket.gettimeout()
783 Return the timeout in seconds (float) associated with socket operations, or
789 Some notes on socket blocking and timeouts: A socket object can be in one of
796 socket or if the system returns an error. The :meth:`~socket.setblocking`
797 method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
799 Timeout mode internally sets the socket in non-blocking mode. The blocking and
800 timeout modes are shared between file descriptors and socket objects that refer
802 returned by the :meth:`~socket.makefile` method must only be used when the
803 socket is in blocking mode; in timeout or non-blocking mode file operations
806 Note that the :meth:`~socket.connect` operation is subject to the timeout
807 setting, and in general it is recommended to call :meth:`~socket.settimeout`
808 before calling :meth:`~socket.connect` or pass a timeout parameter to
810 timeout error of its own regardless of any Python socket timeout setting.
813 .. method:: socket.setsockopt(level, optname, value)
817 Set the value of the given socket option (see the Unix manual page
819 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or a
825 .. method:: socket.shutdown(how)
835 :meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
837 Socket objects also have these (read-only) attributes that correspond to the
838 values given to the :class:`~socket.socket` constructor.
841 .. attribute:: socket.family
843 The socket family.
848 .. attribute:: socket.type
850 The socket type.
855 .. attribute:: socket.proto
857 The socket protocol.
869 using it. Note that a server must perform the sequence :func:`.socket`,
870 :meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
871 repeating the :meth:`~socket.accept` to service more than one client), while a
872 client only needs the sequence :func:`.socket`, :meth:`~socket.connect`. Also
873 note that the server does not :meth:`~socket.sendall`/:meth:`~socket.recv` on
874 the socket it is listening on but on the new socket returned by
875 :meth:`~socket.accept`.
880 import socket
884 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
898 import socket
902 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
917 import socket
923 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
924 socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
927 s = socket.socket(af, socktype, proto)
928 except socket.error as msg:
934 except socket.error as msg:
940 print 'could not open socket'
953 import socket
959 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
962 s = socket.socket(af, socktype, proto)
963 except socket.error as msg:
968 except socket.error as msg:
974 print 'could not open socket'
986 import socket
989 HOST = socket.gethostbyname(socket.gethostname())
991 # create a raw socket and bind it to the public interface
992 s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
996 s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)
999 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)
1005 s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)
1011 socket.error: [Errno 98] Address already in use
1013 This is because the previous execution has left the socket in a ``TIME_WAIT``
1016 There is a :mod:`socket` flag to set, in order to prevent this,
1017 :data:`socket.SO_REUSEADDR`::
1019 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
1020 s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
1023 the :data:`SO_REUSEADDR` flag tells the kernel to reuse a local socket in