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