| \section{\module{socket} --- |
| Low-level networking interface} |
| |
| \declaremodule{builtin}{socket} |
| \modulesynopsis{Low-level networking interface.} |
| |
| |
| This module provides access to the BSD \emph{socket} interface. |
| It is available on all modern \UNIX{} systems, Windows, MacOS, 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: \citetitle{An Introductory 4.3BSD Interprocess Communication |
| Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD |
| Interprocess Communication Tutorial}, by Samuel J. Leffler et al, |
| both in the \citetitle{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 want to refer to \rfc{2553} titled |
| \citetitle{Basic Socket Interface Extensions for IPv6}. |
| |
| The Python interface is a straightforward transliteration of the |
| \UNIX{} system call and library interface for sockets to Python's |
| object-oriented style: the \function{socket()} function returns a |
| \dfn{socket object}\obindex{socket} whose methods implement the |
| various socket system calls. Parameter types are somewhat |
| higher-level than in the C interface: as with \method{read()} and |
| \method{write()} operations on Python files, buffer allocation on |
| receive operations is automatic, and buffer length is implicit on send |
| operations. |
| |
| Socket addresses are represented as follows: |
| A single string is used for the \constant{AF_UNIX} address family. |
| A pair \code{(\var{host}, \var{port})} is used for the |
| \constant{AF_INET} address family, where \var{host} is a string |
| representing either a hostname in Internet domain notation like |
| \code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'}, |
| and \var{port} is an integral port number. |
| For \constant{AF_INET6} address family, a four-tuple |
| \code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is |
| used, where \var{flowinfo} and \var{scopeid} represents |
| \code{sin6_flowinfo} and \code{sin6_scope_id} member in |
| \constant{struct sockaddr_in6} in C. |
| For \module{socket} module methods, \var{flowinfo} and \var{scopeid} |
| can be omitted just for backward compatibility. Note, however, |
| omission of \var{scopeid} can cause problems in manipulating scoped |
| IPv6 addresses. Other address families are currently not supported. |
| The address format required by a particular socket object is |
| automatically selected based on the address family specified when the |
| socket object was created. |
| |
| For IPv4 addresses, two special forms are accepted instead of a host |
| address: the empty string represents \constant{INADDR_ANY}, and the string |
| \code{'<broadcast>'} represents \constant{INADDR_BROADCAST}. |
| The behavior is not available for IPv6 for backward compatibility, |
| therefore, you may want to avoid these if you intend to support IPv6 with |
| your Python programs. |
| |
| If you use a hostname in the \var{host} portion of IPv4/v6 socket |
| address, the program may show a nondeterministic behavior, as Python |
| uses the first address 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 |
| \var{host} portion. |
| |
| \versionadded[AF_NETLINK sockets are represented as |
| pairs \code{\var{pid}, \var{groups}}]{2.5} |
| |
| 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 |
| \exception{socket.error}. |
| |
| Non-blocking mode is supported through |
| \method{setblocking()}. A generalization of this based on timeouts |
| is supported through \method{settimeout()}. |
| |
| The module \module{socket} exports the following constants and functions: |
| |
| |
| \begin{excdesc}{error} |
| This exception is raised for socket-related errors. |
| The accompanying value is either a string telling what went wrong or a |
| pair \code{(\var{errno}, \var{string})} |
| representing an error returned by a system |
| call, similar to the value accompanying \exception{os.error}. |
| See the module \refmodule{errno}\refbimodindex{errno}, which contains |
| names for the error codes defined by the underlying operating system. |
| \end{excdesc} |
| |
| \begin{excdesc}{herror} |
| This exception is raised for address-related errors, i.e. for |
| functions that use \var{h_errno} in the C API, including |
| \function{gethostbyname_ex()} and \function{gethostbyaddr()}. |
| |
| The accompanying value is a pair \code{(\var{h_errno}, \var{string})} |
| representing an error returned by a library call. \var{string} |
| represents the description of \var{h_errno}, as returned by |
| the \cfunction{hstrerror()} C function. |
| \end{excdesc} |
| |
| \begin{excdesc}{gaierror} |
| This exception is raised for address-related errors, for |
| \function{getaddrinfo()} and \function{getnameinfo()}. |
| The accompanying value is a pair \code{(\var{error}, \var{string})} |
| representing an error returned by a library call. |
| \var{string} represents the description of \var{error}, as returned |
| by the \cfunction{gai_strerror()} C function. |
| The \var{error} value will match one of the \constant{EAI_*} constants |
| defined in this module. |
| \end{excdesc} |
| |
| \begin{excdesc}{timeout} |
| This exception is raised when a timeout occurs on a socket which has |
| had timeouts enabled via a prior call to \method{settimeout()}. The |
| accompanying value is a string whose value is currently always ``timed |
| out''. |
| \versionadded{2.3} |
| \end{excdesc} |
| |
| \begin{datadesc}{AF_UNIX} |
| \dataline{AF_INET} |
| \dataline{AF_INET6} |
| These constants represent the address (and protocol) families, |
| used for the first argument to \function{socket()}. If the |
| \constant{AF_UNIX} constant is not defined then this protocol is |
| unsupported. |
| \end{datadesc} |
| |
| \begin{datadesc}{SOCK_STREAM} |
| \dataline{SOCK_DGRAM} |
| \dataline{SOCK_RAW} |
| \dataline{SOCK_RDM} |
| \dataline{SOCK_SEQPACKET} |
| These constants represent the socket types, |
| used for the second argument to \function{socket()}. |
| (Only \constant{SOCK_STREAM} and |
| \constant{SOCK_DGRAM} appear to be generally useful.) |
| \end{datadesc} |
| |
| \begin{datadesc}{SO_*} |
| \dataline{SOMAXCONN} |
| \dataline{MSG_*} |
| \dataline{SOL_*} |
| \dataline{IPPROTO_*} |
| \dataline{IPPORT_*} |
| \dataline{INADDR_*} |
| \dataline{IP_*} |
| \dataline{IPV6_*} |
| \dataline{EAI_*} |
| \dataline{AI_*} |
| \dataline{NI_*} |
| \dataline{TCP_*} |
| 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 \method{setsockopt()} and |
| \method{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. |
| \end{datadesc} |
| |
| \begin{datadesc}{has_ipv6} |
| This constant contains a boolean value which indicates if IPv6 is |
| supported on this platform. |
| \versionadded{2.3} |
| \end{datadesc} |
| |
| \begin{funcdesc}{create_connection}{address\optional{, timeout}} |
| Connects to the \var{address} received (as usual, a \code{(host, port)} |
| pair), with an optional timeout for the connection. Specially useful for |
| higher-level protocols, it is not normally used directly from |
| application-level code. Passing the optional \var{timeout} parameter |
| will set the timeout on the socket instance (if it is not given or |
| \code{None}, the global default timeout setting is used). |
| \versionadded{2.6} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{, |
| socktype\optional{, proto\optional{, |
| flags}}}}} |
| Resolves the \var{host}/\var{port} argument, into a sequence of |
| 5-tuples that contain all the necessary argument for the sockets |
| manipulation. \var{host} is a domain name, a string representation of |
| IPv4/v6 address or \code{None}. |
| \var{port} is a string service name (like \code{'http'}), a numeric |
| port number or \code{None}. |
| |
| The rest of the arguments are optional and must be numeric if |
| specified. For \var{host} and \var{port}, by passing either an empty |
| string or \code{None}, you can pass \code{NULL} to the C API. The |
| \function{getaddrinfo()} function returns a list of 5-tuples with |
| the following structure: |
| |
| \code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, |
| \var{sockaddr})} |
| |
| \var{family}, \var{socktype}, \var{proto} are all integer and are meant to |
| be passed to the \function{socket()} function. |
| \var{canonname} is a string representing the canonical name of the \var{host}. |
| It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified |
| for a numeric \var{host}. |
| \var{sockaddr} is a tuple describing a socket address, as described above. |
| See the source for the \refmodule{httplib} and other library modules |
| for a typical usage of the function. |
| \versionadded{2.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getfqdn}{\optional{name}} |
| Return a fully qualified domain name for \var{name}. |
| If \var{name} is omitted or empty, it is interpreted as the local |
| host. To find the fully qualified name, the hostname returned by |
| \function{gethostbyaddr()} is checked, then 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 \function{gethostname()} is returned. |
| \versionadded{2.0} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{gethostbyname}{hostname} |
| Translate a host name to IPv4 address format. The IPv4 address is |
| returned as a string, such as \code{'100.50.200.5'}. If the host name |
| is an IPv4 address itself it is returned unchanged. See |
| \function{gethostbyname_ex()} for a more complete interface. |
| \function{gethostbyname()} does not support IPv6 name resolution, and |
| \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{gethostbyname_ex}{hostname} |
| Translate a host name to IPv4 address format, extended interface. |
| Return a triple \code{(\var{hostname}, \var{aliaslist}, |
| \var{ipaddrlist})} where |
| \var{hostname} is the primary host name responding to the given |
| \var{ip_address}, \var{aliaslist} is a (possibly empty) list of |
| alternative host names for the same address, and \var{ipaddrlist} is |
| a list of IPv4 addresses for the same interface on the same |
| host (often but not always a single address). |
| \function{gethostbyname_ex()} does not support IPv6 name resolution, and |
| \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{gethostname}{} |
| Return a string containing the hostname of the machine where |
| the Python interpreter is currently executing. |
| If you want to know the current machine's IP address, you may want to use |
| \code{gethostbyname(gethostname())}. |
| This operation assumes that there is a valid address-to-host mapping for |
| the host, and the assumption does not always hold. |
| Note: \function{gethostname()} doesn't always return the fully qualified |
| domain name; use \code{getfqdn()} |
| (see above). |
| \end{funcdesc} |
| |
| \begin{funcdesc}{gethostbyaddr}{ip_address} |
| Return a triple \code{(\var{hostname}, \var{aliaslist}, |
| \var{ipaddrlist})} where \var{hostname} is the primary host name |
| responding to the given \var{ip_address}, \var{aliaslist} is a |
| (possibly empty) list of alternative host names for the same address, |
| and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface |
| on the same host (most likely containing only a single address). |
| To find the fully qualified domain name, use the function |
| \function{getfqdn()}. |
| \function{gethostbyaddr} supports both IPv4 and IPv6. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getnameinfo}{sockaddr, flags} |
| Translate a socket address \var{sockaddr} into a 2-tuple |
| \code{(\var{host}, \var{port})}. |
| Depending on the settings of \var{flags}, the result can contain a |
| fully-qualified domain name or numeric address representation in |
| \var{host}. Similarly, \var{port} can contain a string port name or a |
| numeric port number. |
| \versionadded{2.2} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getprotobyname}{protocolname} |
| Translate an Internet protocol name (for example, \code{'icmp'}) to a constant |
| suitable for passing as the (optional) third argument to the |
| \function{socket()} function. This is usually only needed for sockets |
| opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket |
| modes, the correct protocol is chosen automatically if the protocol is |
| omitted or zero. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}} |
| Translate an Internet service name and protocol name to a port number |
| for that service. The optional protocol name, if given, should be |
| \code{'tcp'} or \code{'udp'}, otherwise any protocol will match. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getservbyport}{port\optional{, protocolname}} |
| Translate an Internet port number and protocol name to a service name |
| for that service. The optional protocol name, if given, should be |
| \code{'tcp'} or \code{'udp'}, otherwise any protocol will match. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{socket}{\optional{family\optional{, |
| type\optional{, proto}}}} |
| Create a new socket using the given address family, socket type and |
| protocol number. The address family should be \constant{AF_INET} (the |
| default), \constant{AF_INET6} or \constant{AF_UNIX}. The socket type |
| should be \constant{SOCK_STREAM} (the default), \constant{SOCK_DGRAM} |
| or perhaps one of the other \samp{SOCK_} constants. The protocol |
| number is usually zero and may be omitted in that case. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}} |
| Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is |
| the name of a PEM formatted file that contains your private |
| key. \var{certfile} is a PEM formatted certificate chain file. On |
| success, a new \class{SSLObject} is returned. |
| |
| \warning{This does not do any certificate verification!} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, 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 \function{socket()} function above. |
| The default family is \constant{AF_UNIX} if defined on the platform; |
| otherwise, the default is \constant{AF_INET}. |
| Availability: \UNIX. \versionadded{2.4} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}} |
| Duplicate the file descriptor \var{fd} (an integer as returned by a file |
| object's \method{fileno()} method) and build a socket object from the |
| result. Address family, socket type and protocol number are as for the |
| \function{socket()} function above. |
| The file descriptor should refer to a socket, but this is not |
| checked --- subsequent operations on the object may fail if the file |
| descriptor is invalid. 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. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ntohl}{x} |
| Convert 32-bit positive integers from network to host byte order. On machines |
| where the host byte order is the same as network byte order, this is a |
| no-op; otherwise, it performs a 4-byte swap operation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{ntohs}{x} |
| Convert 16-bit positive integers from network to host byte order. On machines |
| where the host byte order is the same as network byte order, this is a |
| no-op; otherwise, it performs a 2-byte swap operation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{htonl}{x} |
| Convert 32-bit positive integers from host to network byte order. On machines |
| where the host byte order is the same as network byte order, this is a |
| no-op; otherwise, it performs a 4-byte swap operation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{htons}{x} |
| Convert 16-bit positive integers from host to network byte order. On machines |
| where the host byte order is the same as network byte order, this is a |
| no-op; otherwise, it performs a 2-byte swap operation. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{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 for the 32-bit packed |
| binary this function returns. |
| |
| If the IPv4 address string passed to this function is invalid, |
| \exception{socket.error} will be raised. Note that exactly what is |
| valid depends on the underlying C implementation of |
| \cfunction{inet_aton()}. |
| |
| \function{inet_aton()} does not support IPv6, and |
| \function{getnameinfo()} should be used instead for IPv4/v6 dual stack |
| support. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{inet_ntoa}{packed_ip} |
| Convert a 32-bit packed IPv4 address (a string four characters in |
| length) to its standard dotted-quad string representation (for |
| example, '123.45.67.89'). 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 for the 32-bit packed |
| binary data this function takes as an argument. |
| |
| If the string passed to this function is not exactly 4 bytes in |
| length, \exception{socket.error} will be raised. |
| \function{inet_ntoa()} does not support IPv6, and |
| \function{getnameinfo()} should be used instead for IPv4/v6 dual stack |
| support. |
| \end{funcdesc} |
| |
| \begin{funcdesc}{inet_pton}{address_family, ip_string} |
| Convert an IP address from its family-specific string format to a packed, |
| binary format. |
| \function{inet_pton()} is useful when a library or network protocol calls for |
| an object of type \ctype{struct in_addr} (similar to \function{inet_aton()}) |
| or \ctype{struct in6_addr}. |
| |
| Supported values for \var{address_family} are currently |
| \constant{AF_INET} and \constant{AF_INET6}. |
| If the IP address string \var{ip_string} is invalid, |
| \exception{socket.error} will be raised. Note that exactly what is valid |
| depends on both the value of \var{address_family} and the underlying |
| implementation of \cfunction{inet_pton()}. |
| |
| Availability: \UNIX{} (maybe not all platforms). |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{inet_ntop}{address_family, packed_ip} |
| Convert a packed IP address (a string of some number of characters) to |
| its standard, family-specific string representation (for example, |
| \code{'7.10.0.5'} or \code{'5aef:2b::8'}) |
| \function{inet_ntop()} is useful when a library or network protocol returns |
| an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()}) |
| or \ctype{struct in6_addr}. |
| |
| Supported values for \var{address_family} are currently |
| \constant{AF_INET} and \constant{AF_INET6}. |
| If the string \var{packed_ip} is not the correct length for the |
| specified address family, \exception{ValueError} will be raised. A |
| \exception{socket.error} is raised for errors from the call to |
| \function{inet_ntop()}. |
| |
| Availability: \UNIX{} (maybe not all platforms). |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{getdefaulttimeout}{} |
| Return the default timeout in floating seconds for new socket objects. |
| A value of \code{None} indicates that new socket objects have no timeout. |
| When the socket module is first imported, the default is \code{None}. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{funcdesc}{setdefaulttimeout}{timeout} |
| Set the default timeout in floating seconds for new socket objects. |
| A value of \code{None} indicates that new socket objects have no timeout. |
| When the socket module is first imported, the default is \code{None}. |
| \versionadded{2.3} |
| \end{funcdesc} |
| |
| \begin{datadesc}{SocketType} |
| This is a Python type object that represents the socket object type. |
| It is the same as \code{type(socket(...))}. |
| \end{datadesc} |
| |
| |
| \begin{seealso} |
| \seemodule{SocketServer}{Classes that simplify writing network servers.} |
| \end{seealso} |
| |
| |
| \subsection{Socket Objects \label{socket-objects}} |
| |
| Socket objects have the following methods. Except for |
| \method{makefile()} these correspond to \UNIX{} system calls |
| applicable to sockets. |
| |
| \begin{methoddesc}[socket]{accept}{} |
| Accept a connection. |
| The socket must be bound to an address and listening for connections. |
| The return value is a pair \code{(\var{conn}, \var{address})} |
| where \var{conn} is a \emph{new} socket object usable to send and |
| receive data on the connection, and \var{address} is the address bound |
| to the socket on the other end of the connection. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{bind}{address} |
| Bind the socket to \var{address}. The socket must not already be bound. |
| (The format of \var{address} depends on the address family --- see |
| above.) \note{This method has historically accepted a pair |
| of parameters for \constant{AF_INET} addresses instead of only a |
| tuple. This was never intentional and is no longer available in |
| Python 2.0 and later.} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{close}{} |
| Close the socket. All future operations on the socket object will fail. |
| The remote end will receive no more data (after queued data is flushed). |
| Sockets are automatically closed when they are garbage-collected. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{connect}{address} |
| Connect to a remote socket at \var{address}. |
| (The format of \var{address} depends on the address family --- see |
| above.) \note{This method has historically accepted a pair |
| of parameters for \constant{AF_INET} addresses instead of only a |
| tuple. This was never intentional and is no longer available in |
| Python 2.0 and later.} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{connect_ex}{address} |
| Like \code{connect(\var{address})}, but return an error indicator |
| instead of raising an exception for errors returned by the C-level |
| \cfunction{connect()} call (other problems, such as ``host not found,'' |
| can still raise exceptions). The error indicator is \code{0} if the |
| operation succeeded, otherwise the value of the \cdata{errno} |
| variable. This is useful to support, for example, asynchronous connects. |
| \note{This method has historically accepted a pair of |
| parameters for \constant{AF_INET} addresses instead of only a tuple. |
| This was never intentional and is no longer available in Python |
| 2.0 and later.} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{fileno}{} |
| Return the socket's file descriptor (a small integer). This is useful |
| with \function{select.select()}. |
| |
| Under Windows the small integer returned by this method cannot be used where |
| a file descriptor can be used (such as \function{os.fdopen()}). \UNIX{} does |
| not have this limitation. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{getpeername}{} |
| Return the remote address to which the socket is connected. This is |
| useful to find out the port number of a remote IPv4/v6 socket, for instance. |
| (The format of the address returned depends on the address family --- |
| see above.) On some systems this function is not supported. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{getsockname}{} |
| Return the socket's own address. This is useful to find out the port |
| number of an IPv4/v6 socket, for instance. |
| (The format of the address returned depends on the address family --- |
| see above.) |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}} |
| Return the value of the given socket option (see the \UNIX{} man page |
| \manpage{getsockopt}{2}). The needed symbolic constants |
| (\constant{SO_*} etc.) are defined in this module. If \var{buflen} |
| is absent, an integer option is assumed and its integer value |
| is returned by the function. If \var{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 |
| \refmodule{struct} for a way to decode C structures encoded as strings). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{listen}{backlog} |
| Listen for connections made to the socket. The \var{backlog} argument |
| specifies the maximum number of queued connections and should be at |
| least 1; the maximum value is system-dependent (usually 5). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}} |
| Return a \dfn{file object} associated with the socket. (File objects |
| are described in \ref{bltin-file-objects}, ``File Objects.'') |
| The file object references a \cfunction{dup()}ped version of the |
| socket file descriptor, so the file object and socket object may be |
| closed or garbage-collected independently. |
| The socket must be in blocking mode (it can not have a timeout). |
| \index{I/O control!buffering}The optional \var{mode} |
| and \var{bufsize} arguments are interpreted the same way as by the |
| built-in \function{file()} function; see ``Built-in Functions'' |
| (section \ref{built-in-funcs}) for more information. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{recv}{bufsize\optional{, 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 \var{bufsize}. See the \UNIX{} manual page |
| \manpage{recv}{2} for the meaning of the optional argument |
| \var{flags}; it defaults to zero. |
| \note{For best match with hardware and network realities, the value of |
| \var{bufsize} should be a relatively small power of 2, for example, 4096.} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}} |
| Receive data from the socket. The return value is a pair |
| \code{(\var{string}, \var{address})} where \var{string} is a string |
| representing the data received and \var{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 |
| \var{flags}; it defaults to zero. |
| (The format of \var{address} depends on the address family --- see above.) |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}} |
| Receive data from the socket, writing it into \var{buffer} instead of |
| creating a new string. The return value is a pair |
| \code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number |
| of bytes received and \var{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 |
| \var{flags}; it defaults to zero. (The format of \var{address} |
| depends on the address family --- see above.) |
| \versionadded{2.5} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}} |
| Receive up to \var{nbytes} bytes from the socket, |
| storing the data into a buffer rather than creating a new string. |
| If \var{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 \var{flags}; it defaults to zero. |
| \versionadded{2.5} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{send}{string\optional{, flags}} |
| Send data to the socket. The socket must be connected to a remote |
| socket. The optional \var{flags} argument has the same meaning as for |
| \method{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 application needs to |
| attempt delivery of the remaining data. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{sendall}{string\optional{, flags}} |
| Send data to the socket. The socket must be connected to a remote |
| socket. The optional \var{flags} argument has the same meaning as for |
| \method{recv()} above. Unlike \method{send()}, this method continues |
| to send data from \var{string} until either all data has been sent or |
| an error occurs. \code{None} is returned on success. On error, an |
| exception is raised, and there is no way to determine how much data, |
| if any, was successfully sent. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address} |
| Send data to the socket. The socket should not be connected to a |
| remote socket, since the destination socket is specified by |
| \var{address}. The optional \var{flags} argument has the same |
| meaning as for \method{recv()} above. Return the number of bytes sent. |
| (The format of \var{address} depends on the address family --- see above.) |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{setblocking}{flag} |
| Set blocking or non-blocking mode of the socket: if \var{flag} is 0, |
| the socket is set to non-blocking, else to blocking mode. Initially |
| all sockets are in blocking mode. In non-blocking mode, if a |
| \method{recv()} call doesn't find any data, or if a |
| \method{send()} call can't immediately dispose of the data, a |
| \exception{error} exception is raised; in blocking mode, the calls |
| block until they can proceed. |
| \code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)}; |
| \code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{settimeout}{value} |
| Set a timeout on blocking socket operations. The \var{value} argument |
| can be a nonnegative float expressing seconds, or \code{None}. |
| If a float is |
| given, subsequent socket operations will raise an \exception{timeout} |
| exception if the timeout period \var{value} has elapsed before the |
| operation has completed. Setting a timeout of \code{None} disables |
| timeouts on socket operations. |
| \code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)}; |
| \code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}. |
| \versionadded{2.3} |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{gettimeout}{} |
| Return the timeout in floating seconds associated with socket |
| operations, or \code{None} if no timeout is set. This reflects |
| the last call to \method{setblocking()} or \method{settimeout()}. |
| \versionadded{2.3} |
| \end{methoddesc} |
| |
| 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 blocking mode. In blocking mode, operations block |
| until complete. In non-blocking mode, operations fail (with an error |
| that is unfortunately system-dependent) if they cannot be completed |
| immediately. In timeout mode, operations fail if they cannot be |
| completed within the timeout specified for the socket. The |
| \method{setblocking()} method is simply a shorthand for certain |
| \method{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 \method{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. |
| |
| Note that the \method{connect()} operation is subject to the timeout |
| setting, and in general it is recommended to call |
| \method{settimeout()} before calling \method{connect()}. |
| |
| \begin{methoddesc}[socket]{setsockopt}{level, optname, value} |
| Set the value of the given socket option (see the \UNIX{} manual page |
| \manpage{setsockopt}{2}). The needed symbolic constants are defined in |
| the \module{socket} module (\constant{SO_*} etc.). The value can be an |
| integer or a string representing a buffer. In the latter case it is |
| up to the caller to ensure that the string contains the proper bits |
| (see the optional built-in module |
| \refmodule{struct}\refbimodindex{struct} for a way to encode C |
| structures as strings). |
| \end{methoddesc} |
| |
| \begin{methoddesc}[socket]{shutdown}{how} |
| Shut down one or both halves of the connection. If \var{how} is |
| \constant{SHUT_RD}, further receives are disallowed. If \var{how} is \constant{SHUT_WR}, |
| further sends are disallowed. If \var{how} is \constant{SHUT_RDWR}, further sends |
| and receives are disallowed. |
| \end{methoddesc} |
| |
| Note that there are no methods \method{read()} or \method{write()}; |
| use \method{recv()} and \method{send()} without \var{flags} argument |
| instead. |
| |
| |
| Socket objects also have these (read-only) attributes that correspond |
| to the values given to the \class{socket} constructor. |
| |
| \begin{memberdesc}[socket]{family} |
| The socket family. |
| \versionadded{2.5} |
| \end{memberdesc} |
| |
| \begin{memberdesc}[socket]{type} |
| The socket type. |
| \versionadded{2.5} |
| \end{memberdesc} |
| |
| \begin{memberdesc}[socket]{proto} |
| The socket protocol. |
| \versionadded{2.5} |
| \end{memberdesc} |
| |
| |
| \subsection{SSL Objects \label{ssl-objects}} |
| |
| SSL objects have the following methods. |
| |
| \begin{methoddesc}[SSL]{write}{s} |
| Writes the string \var{s} to the on the object's SSL connection. |
| The return value is the number of bytes written. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[SSL]{read}{\optional{n}} |
| If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise |
| read until EOF. The return value is a string of the bytes read. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[SSL]{server}{} |
| Returns a string describing the server's certificate. |
| Useful for debugging purposes; do not parse the content of this string |
| because its format can't be parsed unambiguously. |
| \end{methoddesc} |
| |
| \begin{methoddesc}[SSL]{issuer}{} |
| Returns a string describing the issuer of the server's certificate. |
| Useful for debugging purposes; do not parse the content of this string |
| because its format can't be parsed unambiguously. |
| \end{methoddesc} |
| |
| \subsection{Example \label{socket-example}} |
| |
| Here are four minimal example programs using the TCP/IP protocol:\ a |
| server that echoes all data that it receives back (servicing only one |
| client), and a client using it. Note that a server must perform the |
| sequence \function{socket()}, \method{bind()}, \method{listen()}, |
| \method{accept()} (possibly repeating the \method{accept()} to service |
| more than one client), while a client only needs the sequence |
| \function{socket()}, \method{connect()}. Also note that the server |
| does not \method{send()}/\method{recv()} on the |
| socket it is listening on but on the new socket returned by |
| \method{accept()}. |
| |
| The first two examples support IPv4 only. |
| |
| \begin{verbatim} |
| # Echo server program |
| import socket |
| |
| HOST = '' # Symbolic name meaning the local host |
| PORT = 50007 # Arbitrary non-privileged port |
| s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| s.bind((HOST, PORT)) |
| s.listen(1) |
| conn, addr = s.accept() |
| print 'Connected by', addr |
| while 1: |
| data = conn.recv(1024) |
| if not data: break |
| conn.send(data) |
| conn.close() |
| \end{verbatim} |
| |
| \begin{verbatim} |
| # Echo client program |
| import socket |
| |
| HOST = 'daring.cwi.nl' # The remote host |
| PORT = 50007 # The same port as used by the server |
| s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| s.connect((HOST, PORT)) |
| s.send('Hello, world') |
| data = s.recv(1024) |
| s.close() |
| print 'Received', repr(data) |
| \end{verbatim} |
| |
| The next two examples are identical to the above two, but support both |
| IPv4 and IPv6. |
| The server side will listen to the first address family available |
| (it should listen to both instead). |
| On most of IPv6-ready systems, IPv6 will take 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. |
| |
| \begin{verbatim} |
| # Echo server program |
| import socket |
| import sys |
| |
| HOST = '' # Symbolic name meaning the local host |
| PORT = 50007 # Arbitrary non-privileged port |
| s = None |
| for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE): |
| af, socktype, proto, canonname, sa = res |
| try: |
| s = socket.socket(af, socktype, proto) |
| except socket.error, msg: |
| s = None |
| continue |
| try: |
| s.bind(sa) |
| s.listen(1) |
| except socket.error, msg: |
| s.close() |
| s = None |
| 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) |
| if not data: break |
| conn.send(data) |
| conn.close() |
| \end{verbatim} |
| |
| \begin{verbatim} |
| # Echo client program |
| import socket |
| 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: |
| s = socket.socket(af, socktype, proto) |
| except socket.error, msg: |
| s = None |
| continue |
| try: |
| s.connect(sa) |
| except socket.error, msg: |
| s.close() |
| s = None |
| 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) |
| \end{verbatim} |
| |
| This example connects to an SSL server, prints the |
| server and issuer's distinguished names, sends some bytes, |
| and reads part of the response: |
| |
| \begin{verbatim} |
| import socket |
| |
| s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
| s.connect(('www.verisign.com', 443)) |
| |
| ssl_sock = socket.ssl(s) |
| |
| print repr(ssl_sock.server()) |
| print repr(ssl_sock.issuer()) |
| |
| # Set a simple HTTP request -- use httplib in actual code. |
| ssl_sock.write("""GET / HTTP/1.0\r |
| Host: www.verisign.com\r\n\r\n""") |
| |
| # Read a chunk of data. Will not necessarily |
| # read all the data returned by the server. |
| data = ssl_sock.read() |
| |
| # Note that you need to close the underlying socket, not the SSL object. |
| del ssl_sock |
| s.close() |
| \end{verbatim} |
| |
| At this writing, this SSL example prints the following output (line |
| breaks inserted for readability): |
| |
| \begin{verbatim} |
| '/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' |
| \end{verbatim} |