Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{socket} --- |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 2 | Low-level networking interface} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 4 | \declaremodule{builtin}{socket} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Low-level networking interface.} |
| 6 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 7 | |
Fred Drake | af8a015 | 1998-01-14 14:51:31 +0000 | [diff] [blame] | 8 | This module provides access to the BSD \emph{socket} interface. |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 9 | It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS, |
| 10 | OS/2, and probably additional platforms. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 11 | |
| 12 | For an introduction to socket programming (in C), see the following |
Fred Drake | 37f1574 | 1999-11-10 16:21:37 +0000 | [diff] [blame] | 13 | papers: \citetitle{An Introductory 4.3BSD Interprocess Communication |
| 14 | Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD |
| 15 | Interprocess Communication Tutorial}, by Samuel J. Leffler et al, |
| 16 | both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1} |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 17 | (sections PS1:7 and PS1:8). The platform-specific reference material |
| 18 | for the various socket-related system calls are also a valuable source |
| 19 | of information on the details of socket semantics. For \UNIX, refer |
| 20 | to the manual pages; for Windows, see the WinSock (or Winsock 2) |
| 21 | specification. |
Fred Drake | 3fc291a | 2001-09-27 04:17:20 +0000 | [diff] [blame] | 22 | For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled |
| 23 | \citetitle{Basic Socket Interface Extensions for IPv6}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 24 | |
| 25 | The Python interface is a straightforward transliteration of the |
| 26 | \UNIX{} system call and library interface for sockets to Python's |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 27 | object-oriented style: the \function{socket()} function returns a |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 28 | \dfn{socket object}\obindex{socket} whose methods implement the |
| 29 | various socket system calls. Parameter types are somewhat |
| 30 | higher-level than in the C interface: as with \method{read()} and |
| 31 | \method{write()} operations on Python files, buffer allocation on |
| 32 | receive operations is automatic, and buffer length is implicit on send |
| 33 | operations. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 34 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 35 | Socket addresses are represented as follows: |
| 36 | A single string is used for the \constant{AF_UNIX} address family. |
| 37 | A pair \code{(\var{host}, \var{port})} is used for the |
| 38 | \constant{AF_INET} address family, where \var{host} is a string |
| 39 | representing either a hostname in Internet domain notation like |
| 40 | \code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'}, |
| 41 | and \var{port} is an integral port number. |
| 42 | For \constant{AF_INET6} address family, a four-tuple |
| 43 | \code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is |
| 44 | used, where \var{flowinfo} and \var{scopeid} represents |
| 45 | \code{sin6_flowinfo} and \code{sin6_scope_id} member in |
| 46 | \constant{struct sockaddr_in6} in C. |
| 47 | For \module{socket} module methods, \var{flowinfo} and \var{scopeid} |
| 48 | can be omitted just for backward compatibility. Note, however, |
| 49 | omission of \var{scopeid} can cause problems in manipulating scoped |
| 50 | IPv6 addresses. Other address families are currently not supported. |
| 51 | The address format required by a particular socket object is |
| 52 | automatically selected based on the address family specified when the |
| 53 | socket object was created. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 54 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 55 | For IPv4 addresses, two special forms are accepted instead of a host |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 56 | address: the empty string represents \constant{INADDR_ANY}, and the string |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 57 | \code{'<broadcast>'} represents \constant{INADDR_BROADCAST}. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 58 | The behavior is not available for IPv6 for backward compatibility, |
| 59 | therefore, you may want to avoid these if you intend to support IPv6 with |
| 60 | your Python programs. |
| 61 | |
| 62 | If you use a hostname in the \var{host} portion of IPv4/v6 socket |
| 63 | address, the program may show a nondeterministic behavior, as Python |
| 64 | uses the first address returned from the DNS resolution. The socket |
| 65 | address will be resolved differently into an actual IPv4/v6 address, |
| 66 | depending on the results from DNS resolution and/or the host |
| 67 | configuration. For deterministic behavior use a numeric address in |
| 68 | \var{host} portion. |
Guido van Rossum | e4f347e | 1997-05-09 02:21:51 +0000 | [diff] [blame] | 69 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 70 | All errors raise exceptions. The normal exceptions for invalid |
| 71 | argument types and out-of-memory conditions can be raised; errors |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 72 | related to socket or address semantics raise the error |
| 73 | \exception{socket.error}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 74 | |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 75 | Non-blocking mode is supported through |
| 76 | \method{setblocking()}. A generalization of this based on timeouts |
| 77 | is supported through \method{settimeout()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 78 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 79 | The module \module{socket} exports the following constants and functions: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 80 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 81 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 82 | \begin{excdesc}{error} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 83 | This exception is raised for socket-related errors. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 84 | The accompanying value is either a string telling what went wrong or a |
| 85 | pair \code{(\var{errno}, \var{string})} |
| 86 | representing an error returned by a system |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 87 | call, similar to the value accompanying \exception{os.error}. |
| 88 | See the module \refmodule{errno}\refbimodindex{errno}, which contains |
Guido van Rossum | 8e1e68d | 1998-02-06 15:18:25 +0000 | [diff] [blame] | 89 | names for the error codes defined by the underlying operating system. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 90 | \end{excdesc} |
| 91 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 92 | \begin{excdesc}{herror} |
| 93 | This exception is raised for address-related errors, i.e. for |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 94 | functions that use \var{h_errno} in the C API, including |
| 95 | \function{gethostbyname_ex()} and \function{gethostbyaddr()}. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 96 | |
| 97 | The accompanying value is a pair \code{(\var{h_errno}, \var{string})} |
| 98 | representing an error returned by a library call. \var{string} |
| 99 | represents the description of \var{h_errno}, as returned by |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 100 | the \cfunction{hstrerror()} C function. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 101 | \end{excdesc} |
| 102 | |
| 103 | \begin{excdesc}{gaierror} |
| 104 | This exception is raised for address-related errors, for |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 105 | \function{getaddrinfo()} and \function{getnameinfo()}. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 106 | The accompanying value is a pair \code{(\var{error}, \var{string})} |
| 107 | representing an error returned by a library call. |
| 108 | \var{string} represents the description of \var{error}, as returned |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 109 | by the \cfunction{gai_strerror()} C function. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 110 | \end{excdesc} |
| 111 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 112 | \begin{datadesc}{AF_UNIX} |
| 113 | \dataline{AF_INET} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 114 | \dataline{AF_INET6} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 115 | These constants represent the address (and protocol) families, |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 116 | used for the first argument to \function{socket()}. If the |
| 117 | \constant{AF_UNIX} constant is not defined then this protocol is |
| 118 | unsupported. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 119 | \end{datadesc} |
| 120 | |
| 121 | \begin{datadesc}{SOCK_STREAM} |
| 122 | \dataline{SOCK_DGRAM} |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 123 | \dataline{SOCK_RAW} |
| 124 | \dataline{SOCK_RDM} |
| 125 | \dataline{SOCK_SEQPACKET} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 126 | These constants represent the socket types, |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 127 | used for the second argument to \function{socket()}. |
| 128 | (Only \constant{SOCK_STREAM} and |
| 129 | \constant{SOCK_DGRAM} appear to be generally useful.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 130 | \end{datadesc} |
| 131 | |
Guido van Rossum | ed2bad8 | 1995-02-16 16:29:18 +0000 | [diff] [blame] | 132 | \begin{datadesc}{SO_*} |
| 133 | \dataline{SOMAXCONN} |
| 134 | \dataline{MSG_*} |
| 135 | \dataline{SOL_*} |
| 136 | \dataline{IPPROTO_*} |
| 137 | \dataline{IPPORT_*} |
| 138 | \dataline{INADDR_*} |
| 139 | \dataline{IP_*} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 140 | \dataline{IPV6_*} |
| 141 | \dataline{EAI_*} |
| 142 | \dataline{AI_*} |
| 143 | \dataline{NI_*} |
Fred Drake | 39960f6 | 2001-12-22 19:07:58 +0000 | [diff] [blame] | 144 | \dataline{TCP_*} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 145 | Many constants of these forms, documented in the \UNIX{} documentation on |
Guido van Rossum | ed2bad8 | 1995-02-16 16:29:18 +0000 | [diff] [blame] | 146 | sockets and/or the IP protocol, are also defined in the socket module. |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 147 | They are generally used in arguments to the \method{setsockopt()} and |
| 148 | \method{getsockopt()} methods of socket objects. In most cases, only |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 149 | those symbols that are defined in the \UNIX{} header files are defined; |
Guido van Rossum | ed2bad8 | 1995-02-16 16:29:18 +0000 | [diff] [blame] | 150 | for a few symbols, default values are provided. |
| 151 | \end{datadesc} |
| 152 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 153 | \begin{funcdesc}{getaddrinfo}{host, port\optional{, family, socktype, proto, flags}} |
| 154 | |
| 155 | Resolves the \var{host}/\var{port} argument, into a sequence of |
| 156 | 5-tuples that contain all the necessary argument for the sockets |
| 157 | manipulation. \var{host} is a domain name, a string representation of |
| 158 | IPv4/v6 address or \code{None}. |
| 159 | \var{port} is a string service name (like \code{``http''}), a numeric |
| 160 | port number or \code{None}. |
| 161 | |
| 162 | The rest of the arguments are optional and must be numeric if |
| 163 | specified. For \var{host} and \var{port}, by passing either an empty |
| 164 | string or \code{None}, you can pass \code{NULL} to the C API. The |
| 165 | \function{getaddrinfo()} function returns a list of 5-tuples with |
| 166 | the following structure: |
| 167 | |
| 168 | \code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, \var{sockaddr})}. |
| 169 | |
| 170 | \var{family}, \var{socktype}, \var{proto} are all integer and are meant to |
| 171 | be passed to the \function{socket()} function. |
| 172 | \var{canonname} is a string representing the canonical name of the \var{host}. |
| 173 | It can be a numeric IPv4/v6 address when \code{AI_CANONNAME} is specified |
| 174 | for a numeric \var{host}. |
| 175 | \var{sockaddr} is a tuple describing a socket address, as described above. |
| 176 | See \code{Lib/httplib.py} and other library files |
| 177 | for a typical usage of the function. |
| 178 | \versionadded{2.2} |
| 179 | \end{funcdesc} |
| 180 | |
Fred Drake | 5772c86 | 2000-08-16 14:21:42 +0000 | [diff] [blame] | 181 | \begin{funcdesc}{getfqdn}{\optional{name}} |
| 182 | Return a fully qualified domain name for \var{name}. |
| 183 | If \var{name} is omitted or empty, it is interpreted as the local |
| 184 | host. To find the fully qualified name, the hostname returned by |
| 185 | \function{gethostbyaddr()} is checked, then aliases for the host, if |
| 186 | available. The first name which includes a period is selected. In |
| 187 | case no fully qualified domain name is available, the hostname is |
| 188 | returned. |
Fred Drake | 8b2e8f8 | 2000-09-06 02:22:16 +0000 | [diff] [blame] | 189 | \versionadded{2.0} |
Fred Drake | 5772c86 | 2000-08-16 14:21:42 +0000 | [diff] [blame] | 190 | \end{funcdesc} |
| 191 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 192 | \begin{funcdesc}{gethostbyname}{hostname} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 193 | Translate a host name to IPv4 address format. The IPv4 address is |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 194 | returned as a string, such as \code{'100.50.200.5'}. If the host name |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 195 | is an IPv4 address itself it is returned unchanged. See |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 196 | \function{gethostbyname_ex()} for a more complete interface. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 197 | \function{gethostbyname()} does not support IPv6 name resolution, and |
| 198 | \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. |
Guido van Rossum | cdf6af1 | 1998-08-07 18:07:36 +0000 | [diff] [blame] | 199 | \end{funcdesc} |
| 200 | |
| 201 | \begin{funcdesc}{gethostbyname_ex}{hostname} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 202 | Translate a host name to IPv4 address format, extended interface. |
Guido van Rossum | cdf6af1 | 1998-08-07 18:07:36 +0000 | [diff] [blame] | 203 | Return a triple \code{(hostname, aliaslist, ipaddrlist)} where |
| 204 | \code{hostname} is the primary host name responding to the given |
| 205 | \var{ip_address}, \code{aliaslist} is a (possibly empty) list of |
| 206 | alternative host names for the same address, and \code{ipaddrlist} is |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 207 | a list of IPv4 addresses for the same interface on the same |
Guido van Rossum | cdf6af1 | 1998-08-07 18:07:36 +0000 | [diff] [blame] | 208 | host (often but not always a single address). |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 209 | \function{gethostbyname_ex()} does not support IPv6 name resolution, and |
| 210 | \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 211 | \end{funcdesc} |
| 212 | |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 213 | \begin{funcdesc}{gethostname}{} |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 214 | Return a string containing the hostname of the machine where |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 215 | the Python interpreter is currently executing. |
| 216 | If you want to know the current machine's IP address, you may want to use |
| 217 | \code{gethostbyname(gethostname())}. |
| 218 | This operation assumes that there is a valid address-to-host mapping for |
| 219 | the host, and the assumption does not always hold. |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 220 | Note: \function{gethostname()} doesn't always return the fully qualified |
| 221 | domain name; use \code{gethostbyaddr(gethostname())} |
Guido van Rossum | fe27a50 | 1997-01-11 17:04:56 +0000 | [diff] [blame] | 222 | (see below). |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 223 | \end{funcdesc} |
| 224 | |
| 225 | \begin{funcdesc}{gethostbyaddr}{ip_address} |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 226 | Return a triple \code{(\var{hostname}, \var{aliaslist}, |
| 227 | \var{ipaddrlist})} where \var{hostname} is the primary host name |
| 228 | responding to the given \var{ip_address}, \var{aliaslist} is a |
| 229 | (possibly empty) list of alternative host names for the same address, |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 230 | and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 231 | on the same host (most likely containing only a single address). |
Fred Drake | 5772c86 | 2000-08-16 14:21:42 +0000 | [diff] [blame] | 232 | To find the fully qualified domain name, use the function |
| 233 | \function{getfqdn()}. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 234 | \function{gethostbyaddr} supports both IPv4 and IPv6. |
| 235 | \end{funcdesc} |
| 236 | |
| 237 | \begin{funcdesc}{getnameinfo}{sockaddr, flags} |
| 238 | Translate a socket address \var{sockaddr} into a 2-tuple |
| 239 | \code{(\var{host}, \var{port})}. |
| 240 | Depending on the settings of \var{flags}, the result can contain a |
| 241 | fully-qualified domain name or numeric address representation in |
| 242 | \var{host}. Similarly, \var{port} can contain a string port name or a |
| 243 | numeric port number. |
| 244 | \versionadded{2.2} |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 245 | \end{funcdesc} |
| 246 | |
Guido van Rossum | 62ac99e | 1996-12-19 16:43:25 +0000 | [diff] [blame] | 247 | \begin{funcdesc}{getprotobyname}{protocolname} |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 248 | Translate an Internet protocol name (for example, \code{'icmp'}) to a constant |
Guido van Rossum | 62ac99e | 1996-12-19 16:43:25 +0000 | [diff] [blame] | 249 | suitable for passing as the (optional) third argument to the |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 250 | \function{socket()} function. This is usually only needed for sockets |
| 251 | opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket |
| 252 | modes, the correct protocol is chosen automatically if the protocol is |
Guido van Rossum | 62ac99e | 1996-12-19 16:43:25 +0000 | [diff] [blame] | 253 | omitted or zero. |
| 254 | \end{funcdesc} |
| 255 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 256 | \begin{funcdesc}{getservbyname}{servicename, protocolname} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 257 | Translate an Internet service name and protocol name to a port number |
| 258 | for that service. The protocol name should be \code{'tcp'} or |
| 259 | \code{'udp'}. |
| 260 | \end{funcdesc} |
| 261 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 262 | \begin{funcdesc}{socket}{family, type\optional{, proto}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 263 | Create a new socket using the given address family, socket type and |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 264 | protocol number. The address family should be \constant{AF_INET}, \constant{AF_INET6} or |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 265 | \constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM}, |
| 266 | \constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 267 | The protocol number is usually zero and may be omitted in that case. |
| 268 | \end{funcdesc} |
| 269 | |
Jeremy Hylton | cb43c08 | 2001-10-11 16:17:22 +0000 | [diff] [blame] | 270 | \begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}} |
Fred Drake | 9081bb1 | 2001-09-25 15:48:11 +0000 | [diff] [blame] | 271 | Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is |
| 272 | the name of a PEM formatted file that contains your private |
| 273 | key. \var{certfile} is a PEM formatted certificate chain file. On |
| 274 | success, a new \class{SSLObject} is returned. |
| 275 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 276 | \warning{This does not do any certificate verification!} |
Fred Drake | 9081bb1 | 2001-09-25 15:48:11 +0000 | [diff] [blame] | 277 | \end{funcdesc} |
| 278 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 279 | \begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 280 | Build a socket object from an existing file descriptor (an integer as |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 281 | returned by a file object's \method{fileno()} method). Address family, |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 282 | socket type and protocol number are as for the \function{socket()} function |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 283 | above. The file descriptor should refer to a socket, but this is not |
| 284 | checked --- subsequent operations on the object may fail if the file |
| 285 | descriptor is invalid. This function is rarely needed, but can be |
| 286 | used to get or set socket options on a socket passed to a program as |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 287 | standard input or output (such as a server started by the \UNIX{} inet |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 288 | daemon). The socket is assumed to be in blocking mode. |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 289 | Availability: \UNIX. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 290 | \end{funcdesc} |
| 291 | |
Guido van Rossum | bda7ca7 | 1996-12-02 17:24:10 +0000 | [diff] [blame] | 292 | \begin{funcdesc}{ntohl}{x} |
Fred Drake | c5aec05 | 1997-12-08 21:25:41 +0000 | [diff] [blame] | 293 | Convert 32-bit integers from network to host byte order. On machines |
| 294 | where the host byte order is the same as network byte order, this is a |
| 295 | no-op; otherwise, it performs a 4-byte swap operation. |
| 296 | \end{funcdesc} |
| 297 | |
| 298 | \begin{funcdesc}{ntohs}{x} |
| 299 | Convert 16-bit integers from network to host byte order. On machines |
| 300 | where the host byte order is the same as network byte order, this is a |
| 301 | no-op; otherwise, it performs a 2-byte swap operation. |
| 302 | \end{funcdesc} |
| 303 | |
| 304 | \begin{funcdesc}{htonl}{x} |
| 305 | Convert 32-bit integers from host to network byte order. On machines |
| 306 | where the host byte order is the same as network byte order, this is a |
| 307 | no-op; otherwise, it performs a 4-byte swap operation. |
| 308 | \end{funcdesc} |
| 309 | |
| 310 | \begin{funcdesc}{htons}{x} |
| 311 | Convert 16-bit integers from host to network byte order. On machines |
| 312 | where the host byte order is the same as network byte order, this is a |
| 313 | no-op; otherwise, it performs a 2-byte swap operation. |
Guido van Rossum | bda7ca7 | 1996-12-02 17:24:10 +0000 | [diff] [blame] | 314 | \end{funcdesc} |
| 315 | |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 316 | \begin{funcdesc}{inet_aton}{ip_string} |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 317 | Convert an IPv4 address from dotted-quad string format (for example, |
| 318 | '123.45.67.89') to 32-bit packed binary format, as a string four |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 319 | characters in length. |
| 320 | |
| 321 | Useful when conversing with a program that uses the standard C library |
| 322 | and needs objects of type \ctype{struct in_addr}, which is the C type |
| 323 | for the 32-bit packed binary this function returns. |
| 324 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 325 | If the IPv4 address string passed to this function is invalid, |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 326 | \exception{socket.error} will be raised. Note that exactly what is |
| 327 | valid depends on the underlying C implementation of |
| 328 | \cfunction{inet_aton()}. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 329 | |
Fred Drake | 39960f6 | 2001-12-22 19:07:58 +0000 | [diff] [blame] | 330 | \function{inet_aton()} does not support IPv6, and |
| 331 | \function{getnameinfo()} should be used instead for IPv4/v6 dual stack |
| 332 | support. |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 333 | \end{funcdesc} |
| 334 | |
| 335 | \begin{funcdesc}{inet_ntoa}{packed_ip} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 336 | Convert a 32-bit packed IPv4 address (a string four characters in |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 337 | length) to its standard dotted-quad string representation |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 338 | (for example, '123.45.67.89'). |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 339 | |
| 340 | Useful when conversing with a program that uses the standard C library |
| 341 | and needs objects of type \ctype{struct in_addr}, which is the C type |
| 342 | for the 32-bit packed binary this function takes as an argument. |
| 343 | |
| 344 | If the string passed to this function is not exactly 4 bytes in |
| 345 | length, \exception{socket.error} will be raised. |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 346 | |
Fred Drake | 39960f6 | 2001-12-22 19:07:58 +0000 | [diff] [blame] | 347 | \function{inet_ntoa()} does not support IPv6, and |
| 348 | \function{getnameinfo()} should be used instead for IPv4/v6 dual stack |
| 349 | support. |
Fred Drake | e6fb1c4 | 1999-09-16 15:50:00 +0000 | [diff] [blame] | 350 | \end{funcdesc} |
| 351 | |
Skip Montanaro | 2a403e8 | 2003-03-20 17:58:12 +0000 | [diff] [blame] | 352 | \begin{funcdesc}{getdefaulttimeout}{} |
| 353 | Return the default timeout in floating seconds for new socket objects. |
| 354 | A value of \code{None} indicates that new socket objects have no timeout. |
| 355 | When the socket module is first imported, the default is \code{None}. |
| 356 | \versionadded{2.3} |
| 357 | \end{funcdesc} |
| 358 | |
| 359 | \begin{funcdesc}{setdefaulttimeout}{timeout} |
| 360 | Set the default timeout in floating seconds for new socket objects. |
| 361 | A value of \code{None} indicates that new socket objects have no timeout. |
| 362 | When the socket module is first imported, the default is \code{None}. |
| 363 | \versionadded{2.3} |
| 364 | \end{funcdesc} |
| 365 | |
Fred Drake | 5451d67 | 1997-10-13 21:31:02 +0000 | [diff] [blame] | 366 | \begin{datadesc}{SocketType} |
Guido van Rossum | 2335c5e | 1997-05-21 14:41:42 +0000 | [diff] [blame] | 367 | This is a Python type object that represents the socket object type. |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 368 | It is the same as \code{type(socket(...))}. |
Guido van Rossum | 2335c5e | 1997-05-21 14:41:42 +0000 | [diff] [blame] | 369 | \end{datadesc} |
| 370 | |
Fred Drake | aa7524c | 2000-07-06 18:37:08 +0000 | [diff] [blame] | 371 | |
| 372 | \begin{seealso} |
| 373 | \seemodule{SocketServer}{Classes that simplify writing network servers.} |
| 374 | \end{seealso} |
| 375 | |
| 376 | |
Fred Drake | a94f676 | 1999-08-05 13:41:04 +0000 | [diff] [blame] | 377 | \subsection{Socket Objects \label{socket-objects}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 378 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 379 | Socket objects have the following methods. Except for |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 380 | \method{makefile()} these correspond to \UNIX{} system calls |
| 381 | applicable to sockets. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 382 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 383 | \begin{methoddesc}[socket]{accept}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 384 | Accept a connection. |
| 385 | The socket must be bound to an address and listening for connections. |
| 386 | The return value is a pair \code{(\var{conn}, \var{address})} |
| 387 | where \var{conn} is a \emph{new} socket object usable to send and |
| 388 | receive data on the connection, and \var{address} is the address bound |
| 389 | to the socket on the other end of the connection. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 390 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 391 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 392 | \begin{methoddesc}[socket]{bind}{address} |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 393 | Bind the socket to \var{address}. The socket must not already be bound. |
Fred Drake | 7d68690 | 2000-04-04 17:48:30 +0000 | [diff] [blame] | 394 | (The format of \var{address} depends on the address family --- see |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 395 | above.) \note{This method has historically accepted a pair |
Fred Drake | 7d68690 | 2000-04-04 17:48:30 +0000 | [diff] [blame] | 396 | of parameters for \constant{AF_INET} addresses instead of only a |
Eric S. Raymond | 8321026 | 2001-01-10 19:34:52 +0000 | [diff] [blame] | 397 | tuple. This was never intentional and is no longer be available in |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 398 | Python 2.0.} |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 399 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 400 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 401 | \begin{methoddesc}[socket]{close}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 402 | Close the socket. All future operations on the socket object will fail. |
| 403 | The remote end will receive no more data (after queued data is flushed). |
| 404 | Sockets are automatically closed when they are garbage-collected. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 405 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 406 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 407 | \begin{methoddesc}[socket]{connect}{address} |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 408 | Connect to a remote socket at \var{address}. |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 409 | (The format of \var{address} depends on the address family --- see |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 410 | above.) \note{This method has historically accepted a pair |
Fred Drake | 7d68690 | 2000-04-04 17:48:30 +0000 | [diff] [blame] | 411 | of parameters for \constant{AF_INET} addresses instead of only a |
Eric S. Raymond | 8321026 | 2001-01-10 19:34:52 +0000 | [diff] [blame] | 412 | tuple. This was never intentional and is no longer available in |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 413 | Python 2.0 and later.} |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 414 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 415 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 416 | \begin{methoddesc}[socket]{connect_ex}{address} |
Guido van Rossum | eefcba6 | 1997-12-09 19:47:24 +0000 | [diff] [blame] | 417 | Like \code{connect(\var{address})}, but return an error indicator |
Fred Drake | b0bc7f2 | 1999-05-06 22:03:50 +0000 | [diff] [blame] | 418 | instead of raising an exception for errors returned by the C-level |
| 419 | \cfunction{connect()} call (other problems, such as ``host not found,'' |
| 420 | can still raise exceptions). The error indicator is \code{0} if the |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 421 | operation succeeded, otherwise the value of the \cdata{errno} |
Fred Drake | 87fa3aa | 2001-12-21 17:45:03 +0000 | [diff] [blame] | 422 | variable. This is useful to support, for example, asynchronous connects. |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 423 | \note{This method has historically accepted a pair of |
Fred Drake | 7d68690 | 2000-04-04 17:48:30 +0000 | [diff] [blame] | 424 | parameters for \constant{AF_INET} addresses instead of only a tuple. |
Eric S. Raymond | 8321026 | 2001-01-10 19:34:52 +0000 | [diff] [blame] | 425 | This was never intentional and is no longer be available in Python |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 426 | 2.0 and later.} |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 427 | \end{methoddesc} |
Guido van Rossum | f7790c6 | 1997-11-18 15:29:20 +0000 | [diff] [blame] | 428 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 429 | \begin{methoddesc}[socket]{fileno}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 430 | Return the socket's file descriptor (a small integer). This is useful |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 431 | with \function{select.select()}. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 432 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 433 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 434 | \begin{methoddesc}[socket]{getpeername}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 435 | Return the remote address to which the socket is connected. This is |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 436 | useful to find out the port number of a remote IPv4/v6 socket, for instance. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 437 | (The format of the address returned depends on the address family --- |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 438 | see above.) On some systems this function is not supported. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 439 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 440 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 441 | \begin{methoddesc}[socket]{getsockname}{} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 442 | Return the socket's own address. This is useful to find out the port |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 443 | number of an IPv4/v6 socket, for instance. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 444 | (The format of the address returned depends on the address family --- |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 445 | see above.) |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 446 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 447 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 448 | \begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 449 | Return the value of the given socket option (see the \UNIX{} man page |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 450 | \manpage{getsockopt}{2}). The needed symbolic constants |
| 451 | (\constant{SO_*} etc.) are defined in this module. If \var{buflen} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 452 | is absent, an integer option is assumed and its integer value |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 453 | is returned by the function. If \var{buflen} is present, it specifies |
| 454 | the maximum length of the buffer used to receive the option in, and |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 455 | this buffer is returned as a string. It is up to the caller to decode |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 456 | the contents of the buffer (see the optional built-in module |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 457 | \refmodule{struct} for a way to decode C structures encoded as strings). |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 458 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 459 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 460 | \begin{methoddesc}[socket]{listen}{backlog} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 461 | Listen for connections made to the socket. The \var{backlog} argument |
| 462 | specifies the maximum number of queued connections and should be at |
| 463 | least 1; the maximum value is system-dependent (usually 5). |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 464 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 465 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 466 | \begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 467 | Return a \dfn{file object} associated with the socket. (File objects |
Fred Drake | a94f676 | 1999-08-05 13:41:04 +0000 | [diff] [blame] | 468 | are described in \ref{bltin-file-objects}, ``File Objects.'') |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 469 | The file object references a \cfunction{dup()}ped version of the |
| 470 | socket file descriptor, so the file object and socket object may be |
Fred Drake | a94f676 | 1999-08-05 13:41:04 +0000 | [diff] [blame] | 471 | closed or garbage-collected independently. |
Guido van Rossum | 715b861 | 2002-06-07 12:38:23 +0000 | [diff] [blame] | 472 | The socket should be in blocking mode. |
Fred Drake | a94f676 | 1999-08-05 13:41:04 +0000 | [diff] [blame] | 473 | \index{I/O control!buffering}The optional \var{mode} |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 474 | and \var{bufsize} arguments are interpreted the same way as by the |
Fred Drake | aad8bb5 | 2001-10-19 17:22:29 +0000 | [diff] [blame] | 475 | built-in \function{file()} function; see ``Built-in Functions'' |
| 476 | (section \ref{built-in-funcs}) for more information. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 477 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 478 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 479 | \begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 480 | Receive data from the socket. The return value is a string representing |
| 481 | the data received. The maximum amount of data to be received |
| 482 | at once is specified by \var{bufsize}. See the \UNIX{} manual page |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 483 | \manpage{recv}{2} for the meaning of the optional argument |
| 484 | \var{flags}; it defaults to zero. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 485 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 486 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 487 | \begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 488 | Receive data from the socket. The return value is a pair |
| 489 | \code{(\var{string}, \var{address})} where \var{string} is a string |
| 490 | representing the data received and \var{address} is the address of the |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 491 | socket sending the data. The optional \var{flags} argument has the |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 492 | same meaning as for \method{recv()} above. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 493 | (The format of \var{address} depends on the address family --- see above.) |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 494 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 495 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 496 | \begin{methoddesc}[socket]{send}{string\optional{, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 497 | Send data to the socket. The socket must be connected to a remote |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 498 | socket. The optional \var{flags} argument has the same meaning as for |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 499 | \method{recv()} above. Returns the number of bytes sent. |
Fred Drake | 39368c1 | 2001-12-05 05:25:59 +0000 | [diff] [blame] | 500 | Applications are responsible for checking that all data has been sent; |
| 501 | if only some of the data was transmitted, the application needs to |
| 502 | attempt delivery of the remaining data. |
| 503 | \end{methoddesc} |
| 504 | |
| 505 | \begin{methoddesc}[socket]{sendall}{string\optional{, flags}} |
| 506 | Send data to the socket. The socket must be connected to a remote |
| 507 | socket. The optional \var{flags} argument has the same meaning as for |
| 508 | \method{recv()} above. Unlike \method{send()}, this method continues |
| 509 | to send data from \var{string} until either all data has been sent or |
| 510 | an error occurs. \code{None} is returned on success. On error, an |
| 511 | exception is raised, and there is no way to determine how much data, |
| 512 | if any, was successfully sent. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 513 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 514 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 515 | \begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 516 | Send data to the socket. The socket should not be connected to a |
| 517 | remote socket, since the destination socket is specified by |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 518 | \var{address}. The optional \var{flags} argument has the same |
| 519 | meaning as for \method{recv()} above. Return the number of bytes sent. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 520 | (The format of \var{address} depends on the address family --- see above.) |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 521 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 522 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 523 | \begin{methoddesc}[socket]{setblocking}{flag} |
Guido van Rossum | 9195148 | 1994-09-07 14:39:14 +0000 | [diff] [blame] | 524 | Set blocking or non-blocking mode of the socket: if \var{flag} is 0, |
| 525 | the socket is set to non-blocking, else to blocking mode. Initially |
| 526 | all sockets are in blocking mode. In non-blocking mode, if a |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 527 | \method{recv()} call doesn't find any data, or if a |
| 528 | \method{send()} call can't immediately dispose of the data, a |
| 529 | \exception{error} exception is raised; in blocking mode, the calls |
| 530 | block until they can proceed. |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 531 | \code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)}; |
| 532 | \code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 533 | \end{methoddesc} |
Guido van Rossum | 9195148 | 1994-09-07 14:39:14 +0000 | [diff] [blame] | 534 | |
Guido van Rossum | be946bf | 2002-06-06 21:51:01 +0000 | [diff] [blame] | 535 | \begin{methoddesc}[socket]{settimeout}{value} |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 536 | Set a timeout on blocking socket operations. The \var{value} argument |
| 537 | can be a nonnegative float expressing seconds, or \code{None}. |
| 538 | If a float is |
Neal Norwitz | 62a7f63 | 2002-06-07 12:36:44 +0000 | [diff] [blame] | 539 | given, subsequent socket operations will raise an \exception{error} |
Guido van Rossum | fc9823b | 2002-06-07 03:39:21 +0000 | [diff] [blame] | 540 | exception if the timeout period \var{value} has elapsed before the |
| 541 | operation has completed. Setting a timeout of \code{None} disables |
| 542 | timeouts on socket operations. |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 543 | \code{s.settimeout(0.0)} is equivalent to \code{s.blocking(0)}; |
| 544 | \code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}. |
Neal Norwitz | bdbd84f | 2002-06-06 22:24:10 +0000 | [diff] [blame] | 545 | \versionadded{2.3} |
Guido van Rossum | be946bf | 2002-06-06 21:51:01 +0000 | [diff] [blame] | 546 | \end{methoddesc} |
| 547 | |
| 548 | \begin{methoddesc}[socket]{gettimeout}{} |
Fred Drake | 6c6d662 | 2002-06-06 21:57:48 +0000 | [diff] [blame] | 549 | Returns the timeout in floating seconds associated with socket |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 550 | operations, or \code{None} if no timeout is set. This reflects |
| 551 | the last call to \method{setblocking()} or \method{settimeout()}. |
Neal Norwitz | bdbd84f | 2002-06-06 22:24:10 +0000 | [diff] [blame] | 552 | \versionadded{2.3} |
Guido van Rossum | be946bf | 2002-06-06 21:51:01 +0000 | [diff] [blame] | 553 | \end{methoddesc} |
| 554 | |
Guido van Rossum | 11ba094 | 2002-06-13 15:07:44 +0000 | [diff] [blame] | 555 | Some notes on socket blocking and timeouts: A socket object can be in |
| 556 | one of three modes: blocking, non-blocking, or timout. Sockets are |
| 557 | always created in blocking mode. In blocking mode, operations block |
| 558 | until complete. In non-blocking mode, operations fail (with an error |
| 559 | that is unfortunately system-dependent) if they cannot be completed |
| 560 | immediately. In timeout mode, operations fail if they cannot be |
| 561 | completed within the timeout specified for the socket. The |
| 562 | \method{setblocking()} method is simply a shorthand for certain |
| 563 | \method{settimeout()} calls. |
Guido van Rossum | be946bf | 2002-06-06 21:51:01 +0000 | [diff] [blame] | 564 | |
Guido van Rossum | 715b861 | 2002-06-07 12:38:23 +0000 | [diff] [blame] | 565 | Timeout mode internally sets the socket in non-blocking mode. The |
| 566 | blocking and timeout modes are shared between file descriptors and |
| 567 | socket objects that refer to the same network endpoint. A consequence |
| 568 | of this is that file objects returned by the \method{makefile()} |
| 569 | method should only be used when the socket is in blocking mode; in |
| 570 | timeout or non-blocking mode file operations that cannot be completed |
| 571 | immediately will fail. |
| 572 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 573 | \begin{methoddesc}[socket]{setsockopt}{level, optname, value} |
Fred Drake | 9a748aa | 2000-06-30 04:21:41 +0000 | [diff] [blame] | 574 | Set the value of the given socket option (see the \UNIX{} manual page |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 575 | \manpage{setsockopt}{2}). The needed symbolic constants are defined in |
| 576 | the \module{socket} module (\code{SO_*} etc.). The value can be an |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 577 | integer or a string representing a buffer. In the latter case it is |
| 578 | up to the caller to ensure that the string contains the proper bits |
| 579 | (see the optional built-in module |
Fred Drake | 318c0b1 | 1999-04-21 17:29:14 +0000 | [diff] [blame] | 580 | \refmodule{struct}\refbimodindex{struct} for a way to encode C |
| 581 | structures as strings). |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 582 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 583 | |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 584 | \begin{methoddesc}[socket]{shutdown}{how} |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 585 | Shut down one or both halves of the connection. If \var{how} is |
| 586 | \code{0}, further receives are disallowed. If \var{how} is \code{1}, |
| 587 | further sends are disallowed. If \var{how} is \code{2}, further sends |
| 588 | and receives are disallowed. |
Fred Drake | 3f1c472 | 1998-04-03 07:04:45 +0000 | [diff] [blame] | 589 | \end{methoddesc} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 590 | |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 591 | Note that there are no methods \method{read()} or \method{write()}; |
| 592 | use \method{recv()} and \method{send()} without \var{flags} argument |
| 593 | instead. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 594 | |
Fred Drake | aa7524c | 2000-07-06 18:37:08 +0000 | [diff] [blame] | 595 | |
Fred Drake | 9081bb1 | 2001-09-25 15:48:11 +0000 | [diff] [blame] | 596 | \subsection{SSL Objects \label{ssl-objects}} |
| 597 | |
| 598 | SSL objects have the following methods. |
| 599 | |
| 600 | \begin{methoddesc}{write}{s} |
| 601 | Writes the string \var{s} to the on the object's SSL connection. |
| 602 | The return value is the number of bytes written. |
| 603 | \end{methoddesc} |
| 604 | |
| 605 | \begin{methoddesc}{read}{\optional{n}} |
| 606 | If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise |
| 607 | read until EOF. The return value is a string of the bytes read. |
| 608 | \end{methoddesc} |
| 609 | |
Fred Drake | aa7524c | 2000-07-06 18:37:08 +0000 | [diff] [blame] | 610 | \subsection{Example \label{socket-example}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 611 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 612 | Here are four minimal example programs using the TCP/IP protocol:\ a |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 613 | server that echoes all data that it receives back (servicing only one |
| 614 | client), and a client using it. Note that a server must perform the |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 615 | sequence \function{socket()}, \method{bind()}, \method{listen()}, |
| 616 | \method{accept()} (possibly repeating the \method{accept()} to service |
| 617 | more than one client), while a client only needs the sequence |
| 618 | \function{socket()}, \method{connect()}. Also note that the server |
| 619 | does not \method{send()}/\method{recv()} on the |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 620 | socket it is listening on but on the new socket returned by |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 621 | \method{accept()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 622 | |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 623 | The first two examples support IPv4 only. |
| 624 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 625 | \begin{verbatim} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 626 | # Echo server program |
Fred Drake | ef52f60 | 2000-10-10 20:36:29 +0000 | [diff] [blame] | 627 | import socket |
| 628 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 629 | HOST = '' # Symbolic name meaning the local host |
Fred Drake | ef52f60 | 2000-10-10 20:36:29 +0000 | [diff] [blame] | 630 | PORT = 50007 # Arbitrary non-privileged port |
| 631 | s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
Fred Drake | 3d69c0e | 2000-05-03 19:40:32 +0000 | [diff] [blame] | 632 | s.bind((HOST, PORT)) |
Guido van Rossum | 5da5755 | 1994-03-02 10:52:16 +0000 | [diff] [blame] | 633 | s.listen(1) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 634 | conn, addr = s.accept() |
| 635 | print 'Connected by', addr |
| 636 | while 1: |
| 637 | data = conn.recv(1024) |
| 638 | if not data: break |
| 639 | conn.send(data) |
| 640 | conn.close() |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 641 | \end{verbatim} |
Fred Drake | d883ca1 | 1998-03-10 05:20:33 +0000 | [diff] [blame] | 642 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 643 | \begin{verbatim} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 644 | # Echo client program |
Fred Drake | ef52f60 | 2000-10-10 20:36:29 +0000 | [diff] [blame] | 645 | import socket |
| 646 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 647 | HOST = 'daring.cwi.nl' # The remote host |
| 648 | PORT = 50007 # The same port as used by the server |
Fred Drake | ef52f60 | 2000-10-10 20:36:29 +0000 | [diff] [blame] | 649 | s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) |
Fred Drake | 3d69c0e | 2000-05-03 19:40:32 +0000 | [diff] [blame] | 650 | s.connect((HOST, PORT)) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 651 | s.send('Hello, world') |
| 652 | data = s.recv(1024) |
| 653 | s.close() |
| 654 | print 'Received', `data` |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 655 | \end{verbatim} |
Martin v. Löwis | c9908c4 | 2001-08-04 22:22:45 +0000 | [diff] [blame] | 656 | |
| 657 | The next two examples are identical to the above two, but support both |
| 658 | IPv4 and IPv6. |
| 659 | The server side will listen to the first address family available |
| 660 | (it should listen to both instead). |
| 661 | On most of IPv6-ready systems, IPv6 will take precedence |
| 662 | and the server may not accept IPv4 traffic. |
| 663 | The client side will try to connect to the all addresses returned as a result |
| 664 | of the name resolution, and sends traffic to the first one connected |
| 665 | successfully. |
| 666 | |
| 667 | \begin{verbatim} |
| 668 | # Echo server program |
| 669 | import socket |
| 670 | import sys |
| 671 | |
| 672 | HOST = '' # Symbolic name meaning the local host |
| 673 | PORT = 50007 # Arbitrary non-privileged port |
| 674 | s = None |
| 675 | for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE): |
| 676 | af, socktype, proto, canonname, sa = res |
| 677 | try: |
| 678 | s = socket.socket(af, socktype, proto) |
| 679 | except socket.error, msg: |
| 680 | s = None |
| 681 | continue |
| 682 | try: |
| 683 | s.bind(sa) |
| 684 | s.listen(1) |
| 685 | except socket.error, msg: |
| 686 | s.close() |
| 687 | s = None |
| 688 | continue |
| 689 | break |
| 690 | if s is None: |
| 691 | print 'could not open socket' |
| 692 | sys.exit(1) |
| 693 | conn, addr = s.accept() |
| 694 | print 'Connected by', addr |
| 695 | while 1: |
| 696 | data = conn.recv(1024) |
| 697 | if not data: break |
| 698 | conn.send(data) |
| 699 | conn.close() |
| 700 | \end{verbatim} |
| 701 | |
| 702 | \begin{verbatim} |
| 703 | # Echo client program |
| 704 | import socket |
| 705 | import sys |
| 706 | |
| 707 | HOST = 'daring.cwi.nl' # The remote host |
| 708 | PORT = 50007 # The same port as used by the server |
| 709 | s = None |
| 710 | for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): |
| 711 | af, socktype, proto, canonname, sa = res |
| 712 | try: |
| 713 | s = socket.socket(af, socktype, proto) |
| 714 | except socket.error, msg: |
| 715 | s = None |
| 716 | continue |
| 717 | try: |
| 718 | s.connect(sa) |
| 719 | except socket.error, msg: |
| 720 | s.close() |
| 721 | s = None |
| 722 | continue |
| 723 | break |
| 724 | if s is None: |
| 725 | print 'could not open socket' |
| 726 | sys.exit(1) |
| 727 | s.send('Hello, world') |
| 728 | data = s.recv(1024) |
| 729 | s.close() |
| 730 | print 'Received', `data` |
| 731 | \end{verbatim} |