| :mod:`socket` --- Low-level networking interface |
| ================================================ |
| |
| .. module:: socket |
| :synopsis: Low-level networking interface. |
| |
| |
| This module provides access to the BSD *socket* interface. It is available on |
n | all modern Unix systems, Windows, MacOS, BeOS, OS/2, and probably additional |
n | all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional |
| platforms. |
| |
| .. note:: |
| |
| Some behavior may be platform dependent, since calls are made to the operating |
| system socket APIs. |
| |
| For an introduction to socket programming (in C), see the following papers: An |
| Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and |
| An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et |
| al, both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections |
| PS1:7 and PS1:8). The platform-specific reference material for the various |
| socket-related system calls are also a valuable source of information on the |
| details of socket semantics. For Unix, refer to the manual pages; for Windows, |
| see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers may |
n | want to refer to :rfc:`2553` titled Basic Socket Interface Extensions for IPv6. |
n | want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv6. |
| |
| .. index:: object: socket |
| |
| The Python interface is a straightforward transliteration of the Unix system |
| call and library interface for sockets to Python's object-oriented style: the |
| :func:`socket` function returns a :dfn:`socket object` whose methods implement |
| the various socket system calls. Parameter types are somewhat higher-level than |
| in the C interface: as with :meth:`read` and :meth:`write` operations on Python |
| returned from the DNS resolution. The socket address will be resolved |
| differently into an actual IPv4/v6 address, depending on the results from DNS |
| resolution and/or the host configuration. For deterministic behavior use a |
| numeric address in *host* portion. |
| |
| .. versionadded:: 2.5 |
| AF_NETLINK sockets are represented as pairs ``pid, groups``. |
| |
n | .. versionadded:: 2.6 |
| Linux-only support for TIPC is also available using the :const:`AF_TIPC` |
| address family. TIPC is an open, non-IP based networked protocol designed |
| for use in clustered computer environments. Addresses are represented by a |
| tuple, and the fields depend on the address type. The general tuple form is |
| ``(addr_type, v1, v2, v3 [, scope])``, where: |
| |
| - *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or |
| TIPC_ADDR_ID. |
| - *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and |
| TIPC_NODE_SCOPE. |
| - If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is |
| the port identifier, and *v3* should be 0. |
| |
| If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2* |
| is the lower port number, and *v3* is the upper port number. |
| |
| If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the |
| reference, and *v3* should be set to 0. |
| |
| |
| All errors raise exceptions. The normal exceptions for invalid argument types |
| and out-of-memory conditions can be raised; errors related to socket or address |
| semantics raise the error :exc:`socket.error`. |
| |
| Non-blocking mode is supported through :meth:`setblocking`. A generalization of |
| this based on timeouts is supported through :meth:`settimeout`. |
| |
| The module :mod:`socket` exports the following constants and functions: |
| |
| Many constants of these forms, documented in the Unix documentation on sockets |
| and/or the IP protocol, are also defined in the socket module. They are |
| generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt` |
| methods of socket objects. In most cases, only those symbols that are defined |
| in the Unix header files are defined; for a few symbols, default values are |
| provided. |
| |
n | .. data:: SIO_* |
| RCVALL_* |
| |
| Constants for Windows' WSAIoctl(). The constants are used as arguments to the |
| :meth:`ioctl` method of socket objects. |
| |
| .. versionadded:: 2.6 |
| |
| .. data:: TIPC_* |
| |
| TIPC related constants, matching the ones exported by the C socket API. See |
| the TIPC documentation for more information. |
| |
| .. versionadded:: 2.6 |
| |
| .. data:: has_ipv6 |
| |
| This constant contains a boolean value which indicates if IPv6 is supported on |
| this platform. |
| |
| .. versionadded:: 2.3 |
| |
| |
n | .. function:: create_connection(address[, timeout]) |
| |
| Convenience function. Connect to *address* (a 2-tuple ``(host, port)``), |
| and return the socket object. Passing the optional *timeout* parameter will |
| set the timeout on the socket instance before attempting to connect. If no |
| *timeout* is supplied, the global default timeout setting returned by |
| :func:`getdefaulttimeout` is used. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]]) |
| |
| Resolves the *host*/*port* argument, into a sequence of 5-tuples that contain |
n | all the necessary argument for the sockets manipulation. *host* is a domain |
n | all the necessary arguments for creating the corresponding socket. *host* is a domain |
| name, a string representation of IPv4/v6 address or ``None``. *port* is a string |
| name, a string representation of an IPv4/v6 address or ``None``. *port* is a string |
| service name (like ``'http'``), a numeric port number or ``None``. |
| service name such as ``'http'``, a numeric port number or ``None``. |
| |
| The rest of the arguments are optional and must be numeric if specified. For |
| The rest of the arguments are optional and must be numeric if specified. |
| *host* and *port*, by passing either an empty string or ``None``, you can pass |
| By passing ``None`` as the value of *host* and *port*, , you can pass ``NULL`` to the C API. |
| ``NULL`` to the C API. The :func:`getaddrinfo` function returns a list of |
| |
| 5-tuples with the following structure: |
| The :func:`getaddrinfo` function returns a list of 5-tuples with the following |
| structure: |
| |
| ``(family, socktype, proto, canonname, sockaddr)`` |
| |
n | *family*, *socktype*, *proto* are all integer and are meant to be passed to the |
n | *family*, *socktype*, *proto* are all integers and are meant to be passed to the |
| :func:`socket` function. *canonname* is a string representing the canonical name |
| of the *host*. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is |
| specified for a numeric *host*. *sockaddr* is a tuple describing a socket |
n | address, as described above. See the source for the :mod:`httplib` and other |
n | address, as described above. See the source for :mod:`socket` and other |
| library modules for a typical usage of the function. |
| |
| .. versionadded:: 2.2 |
| |
| |
| .. function:: getfqdn([name]) |
| |
| Return a fully qualified domain name for *name*. If *name* is omitted or empty, |
| it is interpreted as the local host. To find the fully qualified name, the |
n | hostname returned by :func:`gethostbyaddr` is checked, then aliases for the |
n | hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the |
| host, if available. The first name which includes a period is selected. In |
| case no fully qualified domain name is available, the hostname as returned by |
| :func:`gethostname` is returned. |
| |
| .. versionadded:: 2.0 |
| |
| |
| .. function:: gethostbyname(hostname) |
| always a single address). :func:`gethostbyname_ex` does not support IPv6 name |
| resolution, and :func:`getaddrinfo` should be used instead for IPv4/v6 dual |
| stack support. |
| |
| |
| .. function:: gethostname() |
| |
| Return a string containing the hostname of the machine where the Python |
n | interpreter is currently executing. If you want to know the current machine's IP |
n | interpreter is currently executing. |
| address, you may want to use ``gethostbyname(gethostname())``. This operation |
| |
| assumes that there is a valid address-to-host mapping for the host, and the |
| If you want to know the current machine's IP address, you may want to use |
| assumption does not always hold. Note: :func:`gethostname` doesn't always return |
| ``gethostbyname(gethostname())``. This operation assumes that there is a |
| the fully qualified domain name; use ``gethostbyaddr(gethostname())`` (see |
| valid address-to-host mapping for the host, and the assumption does not |
| below). |
| always hold. |
| |
| Note: :func:`gethostname` doesn't always return the fully qualified domain |
| name; use ``getfqdn()`` (see above). |
| |
| |
| .. function:: gethostbyaddr(ip_address) |
| |
| Return a triple ``(hostname, aliaslist, ipaddrlist)`` where *hostname* is the |
| primary host name responding to the given *ip_address*, *aliaslist* is a |
| (possibly empty) list of alternative host names for the same address, and |
| *ipaddrlist* is a list of IPv4/v6 addresses for the same interface on the same |
| .. function:: socket([family[, type[, proto]]]) |
| |
| Create a new socket using the given address family, socket type and protocol |
| number. The address family should be :const:`AF_INET` (the default), |
| :const:`AF_INET6` or :const:`AF_UNIX`. The socket type should be |
| :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM` or perhaps one of the |
| other ``SOCK_`` constants. The protocol number is usually zero and may be |
| omitted in that case. |
n | |
| |
| .. function:: ssl(sock[, keyfile, certfile]) |
| |
| Initiate a SSL connection over the socket *sock*. *keyfile* is the name of a PEM |
| formatted file that contains your private key. *certfile* is a PEM formatted |
| certificate chain file. On success, a new :class:`SSLObject` is returned. |
| |
| .. warning:: |
| |
| This does not do any certificate verification! |
| |
| |
| .. function:: socketpair([family[, type[, proto]]]) |
| |
| Build a pair of connected socket objects using the given address family, socket |
| type, and protocol number. Address family, socket type, and protocol number are |
| as for the :func:`socket` function above. The default family is :const:`AF_UNIX` |
| if defined on the platform; otherwise, the default is :const:`AF_INET`. |
| This function is rarely needed, but can be used to get or set socket options on |
| a socket passed to a program as standard input or output (such as a server |
| started by the Unix inet daemon). The socket is assumed to be in blocking mode. |
| Availability: Unix. |
| |
| |
| .. function:: ntohl(x) |
| |
n | Convert 32-bit integers from network to host byte order. On machines where the |
n | Convert 32-bit positive integers from network to host byte order. On machines |
| host byte order is the same as network byte order, this is a no-op; otherwise, |
| where the host byte order is the same as network byte order, this is a no-op; |
| it performs a 4-byte swap operation. |
| otherwise, it performs a 4-byte swap operation. |
| |
| |
| .. function:: ntohs(x) |
| |
n | Convert 16-bit integers from network to host byte order. On machines where the |
n | Convert 16-bit positive integers from network to host byte order. On machines |
| host byte order is the same as network byte order, this is a no-op; otherwise, |
| where the host byte order is the same as network byte order, this is a no-op; |
| it performs a 2-byte swap operation. |
| otherwise, it performs a 2-byte swap operation. |
| |
| |
| .. function:: htonl(x) |
| |
n | Convert 32-bit integers from host to network byte order. On machines where the |
n | Convert 32-bit positive integers from host to network byte order. On machines |
| host byte order is the same as network byte order, this is a no-op; otherwise, |
| where the host byte order is the same as network byte order, this is a no-op; |
| it performs a 4-byte swap operation. |
| otherwise, it performs a 4-byte swap operation. |
| |
| |
| .. function:: htons(x) |
| |
n | Convert 16-bit integers from host to network byte order. On machines where the |
n | Convert 16-bit positive integers from host to network byte order. On machines |
| host byte order is the same as network byte order, this is a no-op; otherwise, |
| where the host byte order is the same as network byte order, this is a no-op; |
| it performs a 2-byte swap operation. |
| otherwise, it performs a 2-byte swap operation. |
| |
| |
| .. function:: inet_aton(ip_string) |
| |
| Convert an IPv4 address from dotted-quad string format (for example, |
| '123.45.67.89') to 32-bit packed binary format, as a string four characters in |
| length. This is useful when conversing with a program that uses the standard C |
| library and needs objects of type :ctype:`struct in_addr`, which is the C type |
| are defined in this module. If *buflen* is absent, an integer option is assumed |
| and its integer value is returned by the function. If *buflen* is present, it |
| specifies the maximum length of the buffer used to receive the option in, and |
| this buffer is returned as a string. It is up to the caller to decode the |
| contents of the buffer (see the optional built-in module :mod:`struct` for a way |
| to decode C structures encoded as strings). |
| |
| |
n | .. method:: socket.ioctl(control, option) |
| |
| :platform: Windows |
| |
| The :meth:`ioctl` method is a limited interface to the WSAIoctl system |
| interface. Please refer to the MSDN documentation for more information. |
| |
| .. versionadded:: 2.6 |
| |
| |
| .. method:: socket.listen(backlog) |
| |
| Listen for connections made to the socket. The *backlog* argument specifies the |
| maximum number of queued connections and should be at least 1; the maximum value |
| is system-dependent (usually 5). |
| |
| |
| .. method:: socket.makefile([mode[, bufsize]]) |
| |
| .. index:: single: I/O control; buffering |
| |
| Return a :dfn:`file object` associated with the socket. (File objects are |
n | described in :ref:`bltin-file-objects`, "File Objects.") The file object |
n | described in :ref:`bltin-file-objects`.) The file object |
| references a :cfunc:`dup`\ ped version of the socket file descriptor, so the |
| file object and socket object may be closed or garbage-collected independently. |
n | The socket must be in blocking mode. The optional *mode* and *bufsize* arguments |
n | The socket must be in blocking mode (it can not have a timeout). The optional |
| are interpreted the same way as by the built-in :func:`file` function; see |
| *mode* and *bufsize* arguments are interpreted the same way as by the built-in |
| "Built-in Functions" (section :ref:`built-in-funcs`) for more information. |
| :func:`file` function. |
| |
| |
| .. method:: socket.recv(bufsize[, flags]) |
| |
| Receive data from the socket. The return value is a string representing the |
| data received. The maximum amount of data to be received at once is specified |
| by *bufsize*. See the Unix manual page :manpage:`recv(2)` for the meaning of |
| the optional argument *flags*; it defaults to zero. |
| For best match with hardware and network realities, the value of *bufsize* |
| should be a relatively small power of 2, for example, 4096. |
| |
| |
| .. method:: socket.recvfrom(bufsize[, flags]) |
| |
| Receive data from the socket. The return value is a pair ``(string, address)`` |
| where *string* is a string representing the data received and *address* is the |
n | address of the socket sending the data. The optional *flags* argument has the |
n | address of the socket sending the data. See the Unix manual page |
| same meaning as for :meth:`recv` above. (The format of *address* depends on the |
| :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults |
| to zero. (The format of *address* depends on the address family --- see above.) |
| |
| |
| .. method:: socket.recvfrom_into(buffer[, nbytes[, flags]]) |
| |
| Receive data from the socket, writing it into *buffer* instead of creating a |
| new string. The return value is a pair ``(nbytes, address)`` where *nbytes* is |
| the number of bytes received and *address* is the address of the socket sending |
| the data. See the Unix manual page :manpage:`recv(2)` for the meaning of the |
| optional argument *flags*; it defaults to zero. (The format of *address* |
| address family --- see above.) |
| depends on the address family --- see above.) |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. method:: socket.recv_into(buffer[, nbytes[, flags]]) |
| |
| Receive up to *nbytes* bytes from the socket, storing the data into a buffer |
| rather than creating a new string. If *nbytes* is not specified (or 0), |
| receive up to the size available in the given buffer. See the Unix manual page |
| :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults |
| to zero. |
| |
| .. versionadded:: 2.5 |
| |
| |
| .. method:: socket.send(string[, flags]) |
| |
| Send data to the socket. The socket must be connected to a remote socket. The |
| optional *flags* argument has the same meaning as for :meth:`recv` above. |
| Returns the number of bytes sent. Applications are responsible for checking that |
| all data has been sent; if only some of the data was transmitted, the |
| Return the timeout in floating seconds associated with socket operations, or |
| ``None`` if no timeout is set. This reflects the last call to |
| :meth:`setblocking` or :meth:`settimeout`. |
| |
| .. versionadded:: 2.3 |
| |
| Some notes on socket blocking and timeouts: A socket object can be in one of |
| three modes: blocking, non-blocking, or timeout. Sockets are always created in |
n | blocking mode. In blocking mode, operations block until complete. In non- |
n | blocking mode. In blocking mode, operations block until complete. In |
| blocking mode, operations fail (with an error that is unfortunately system- |
| non-blocking mode, operations fail (with an error that is unfortunately |
| dependent) if they cannot be completed immediately. In timeout mode, operations |
| system-dependent) if they cannot be completed immediately. In timeout mode, |
| fail if they cannot be completed within the timeout specified for the socket. |
| operations fail if they cannot be completed within the timeout specified for the |
| The :meth:`setblocking` method is simply a shorthand for certain |
| socket. The :meth:`setblocking` method is simply a shorthand for certain |
| :meth:`settimeout` calls. |
| |
| Timeout mode internally sets the socket in non-blocking mode. The blocking and |
| timeout modes are shared between file descriptors and socket objects that refer |
| to the same network endpoint. A consequence of this is that file objects |
| returned by the :meth:`makefile` method must only be used when the socket is in |
| blocking mode; in timeout or non-blocking mode file operations that cannot be |
| completed immediately will fail. |
| .. versionadded:: 2.5 |
| |
| |
| .. attribute:: socket.proto |
| |
| The socket protocol. |
| |
| .. versionadded:: 2.5 |
n | |
| |
| .. _ssl-objects: |
| |
| SSL Objects |
| ----------- |
| |
| SSL objects have the following methods. |
| |
| |
| .. method:: XXX Class.write(s) |
| |
| Writes the string *s* to the on the object's SSL connection. The return value is |
| the number of bytes written. |
| |
| |
| .. method:: XXX Class.read([n]) |
| |
| If *n* is provided, read *n* bytes from the SSL connection, otherwise read until |
| EOF. The return value is a string of the bytes read. |
| |
| |
| .. method:: XXX Class.server() |
| |
| Returns a string containing the ASN.1 distinguished name identifying the |
| server's certificate. (See below for an example showing what distinguished |
| names look like.) |
| |
| |
| .. method:: XXX Class.issuer() |
| |
| Returns a string containing the ASN.1 distinguished name identifying the issuer |
| of the server's certificate. |
| |
| |
| .. _socket-example: |
| |
| Example |
| ------- |
| |
| Here are four minimal example programs using the TCP/IP protocol: a server that |
| precedence and the server may not accept IPv4 traffic. The client side will try |
| to connect to the all addresses returned as a result of the name resolution, and |
| sends traffic to the first one connected successfully. :: |
| |
| # Echo server program |
| import socket |
| import sys |
| |
n | HOST = '' # Symbolic name meaning the local host |
n | HOST = None # Symbolic name meaning all available interfaces |
| PORT = 50007 # Arbitrary non-privileged port |
| s = None |
n | for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE): |
n | for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, |
| socket.SOCK_STREAM, 0, socket.AI_PASSIVE): |
| af, socktype, proto, canonname, sa = res |
| try: |
n | s = socket.socket(af, socktype, proto) |
n | s = socket.socket(af, socktype, proto) |
| except socket.error, msg: |
n | s = None |
n | s = None |
| continue |
| continue |
| try: |
n | s.bind(sa) |
n | s.bind(sa) |
| s.listen(1) |
| s.listen(1) |
| except socket.error, msg: |
n | s.close() |
n | s.close() |
| s = None |
| s = None |
| continue |
| continue |
| break |
| if s is None: |
| print 'could not open socket' |
| sys.exit(1) |
| conn, addr = s.accept() |
| print 'Connected by', addr |
| while 1: |
| data = conn.recv(1024) |
| import sys |
| |
| HOST = 'daring.cwi.nl' # The remote host |
| PORT = 50007 # The same port as used by the server |
| s = None |
| for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): |
| af, socktype, proto, canonname, sa = res |
| try: |
n | s = socket.socket(af, socktype, proto) |
n | s = socket.socket(af, socktype, proto) |
| except socket.error, msg: |
n | s = None |
n | s = None |
| continue |
| continue |
| try: |
n | s.connect(sa) |
n | s.connect(sa) |
| except socket.error, msg: |
n | s.close() |
n | s.close() |
| s = None |
| s = None |
| continue |
| continue |
| break |
| if s is None: |
| print 'could not open socket' |
| sys.exit(1) |
| s.send('Hello, world') |
| data = s.recv(1024) |
| s.close() |
| print 'Received', repr(data) |
| |
n | This example connects to an SSL server, prints the server and issuer's |
n | |
| distinguished names, sends some bytes, and reads part of the response:: |
| The last example shows how to write a very simple network sniffer with raw |
| sockets on Windows. The example requires administrator privileges to modify |
| the interface:: |
| |
| import socket |
| |
n | # the public network interface |
| HOST = socket.gethostbyname(socket.gethostname()) |
| |
| # create a raw socket and bind it to the public interface |
| s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP) |
| s.connect(('www.verisign.com', 443)) |
| s.bind((HOST, 0)) |
| |
n | ssl_sock = socket.ssl(s) |
n | # Include IP headers |
| s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1) |
| |
n | print repr(ssl_sock.server()) |
n | # receive all packages |
| print repr(ssl_sock.issuer()) |
| s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON) |
| |
n | # Set a simple HTTP request -- use httplib in actual code. |
n | # receive a package |
| ssl_sock.write("""GET / HTTP/1.0\r |
| print s.recvfrom(65565) |
| Host: www.verisign.com\r\n\r\n""") |
| |
t | # Read a chunk of data. Will not necessarily |
t | # disabled promiscuous mode |
| # read all the data returned by the server. |
| s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) |
| data = ssl_sock.read() |
| |
| # Note that you need to close the underlying socket, not the SSL object. |
| del ssl_sock |
| s.close() |
| |
| At this writing, this SSL example prints the following output (line breaks |
| inserted for readability):: |
| |
| '/C=US/ST=California/L=Mountain View/ |
| O=VeriSign, Inc./OU=Production Services/ |
| OU=Terms of use at www.verisign.com/rpa (c)00/ |
| CN=www.verisign.com' |
| '/O=VeriSign Trust Network/OU=VeriSign, Inc./ |
| OU=VeriSign International Server CA - Class 3/ |
| OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign' |
| |