blob: 9589cbeef99f259d86025f66b53b8bc91a3c2f03 [file] [log] [blame]
Fred Drake295da241998-08-10 19:42:37 +00001\section{\module{socket} ---
Fred Drake318c0b11999-04-21 17:29:14 +00002 Low-level networking interface}
Fred Drakeb91e9341998-07-23 17:59:49 +00003
Fred Drake318c0b11999-04-21 17:29:14 +00004\declaremodule{builtin}{socket}
Fred Drakeb91e9341998-07-23 17:59:49 +00005\modulesynopsis{Low-level networking interface.}
6
Fred Draked883ca11998-03-10 05:20:33 +00007
Fred Drakeaf8a0151998-01-14 14:51:31 +00008This module provides access to the BSD \emph{socket} interface.
Fred Drake38e5d272000-04-03 20:13:55 +00009It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
10OS/2, and probably additional platforms.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000011
12For an introduction to socket programming (in C), see the following
Fred Drake37f15741999-11-10 16:21:37 +000013papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
14Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
15Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
16both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1}
Fred Drake38e5d272000-04-03 20:13:55 +000017(sections PS1:7 and PS1:8). The platform-specific reference material
18for the various socket-related system calls are also a valuable source
19of information on the details of socket semantics. For \UNIX, refer
20to the manual pages; for Windows, see the WinSock (or Winsock 2)
21specification.
Fred Drake3fc291a2001-09-27 04:17:20 +000022For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled
23\citetitle{Basic Socket Interface Extensions for IPv6}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000024
25The Python interface is a straightforward transliteration of the
26\UNIX{} system call and library interface for sockets to Python's
Fred Draked883ca11998-03-10 05:20:33 +000027object-oriented style: the \function{socket()} function returns a
Fred Drake318c0b11999-04-21 17:29:14 +000028\dfn{socket object}\obindex{socket} whose methods implement the
29various socket system calls. Parameter types are somewhat
30higher-level than in the C interface: as with \method{read()} and
31\method{write()} operations on Python files, buffer allocation on
32receive operations is automatic, and buffer length is implicit on send
33operations.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000034
Martin v. Löwisc9908c42001-08-04 22:22:45 +000035Socket addresses are represented as follows:
36A single string is used for the \constant{AF_UNIX} address family.
37A pair \code{(\var{host}, \var{port})} is used for the
38\constant{AF_INET} address family, where \var{host} is a string
39representing either a hostname in Internet domain notation like
40\code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'},
41and \var{port} is an integral port number.
42For \constant{AF_INET6} address family, a four-tuple
43\code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is
44used, 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.
47For \module{socket} module methods, \var{flowinfo} and \var{scopeid}
48can be omitted just for backward compatibility. Note, however,
49omission of \var{scopeid} can cause problems in manipulating scoped
50IPv6 addresses. Other address families are currently not supported.
51The address format required by a particular socket object is
52automatically selected based on the address family specified when the
53socket object was created.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000054
Martin v. Löwisc9908c42001-08-04 22:22:45 +000055For IPv4 addresses, two special forms are accepted instead of a host
Fred Draked883ca11998-03-10 05:20:33 +000056address: the empty string represents \constant{INADDR_ANY}, and the string
Fred Drake318c0b11999-04-21 17:29:14 +000057\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
Martin v. Löwisc9908c42001-08-04 22:22:45 +000058The behavior is not available for IPv6 for backward compatibility,
59therefore, you may want to avoid these if you intend to support IPv6 with
60your Python programs.
61
62If you use a hostname in the \var{host} portion of IPv4/v6 socket
63address, the program may show a nondeterministic behavior, as Python
64uses the first address returned from the DNS resolution. The socket
65address will be resolved differently into an actual IPv4/v6 address,
66depending on the results from DNS resolution and/or the host
67configuration. For deterministic behavior use a numeric address in
68\var{host} portion.
Guido van Rossume4f347e1997-05-09 02:21:51 +000069
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000070All errors raise exceptions. The normal exceptions for invalid
71argument types and out-of-memory conditions can be raised; errors
Fred Drake318c0b11999-04-21 17:29:14 +000072related to socket or address semantics raise the error
73\exception{socket.error}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000074
Fred Drake318c0b11999-04-21 17:29:14 +000075Non-blocking mode is supported through the
76\method{setblocking()} method.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000077
Fred Draked883ca11998-03-10 05:20:33 +000078The module \module{socket} exports the following constants and functions:
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000079
Fred Draked883ca11998-03-10 05:20:33 +000080
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000081\begin{excdesc}{error}
Martin v. Löwisc9908c42001-08-04 22:22:45 +000082This exception is raised for socket-related errors.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000083The accompanying value is either a string telling what went wrong or a
84pair \code{(\var{errno}, \var{string})}
85representing an error returned by a system
Fred Drake318c0b11999-04-21 17:29:14 +000086call, similar to the value accompanying \exception{os.error}.
87See the module \refmodule{errno}\refbimodindex{errno}, which contains
Guido van Rossum8e1e68d1998-02-06 15:18:25 +000088names for the error codes defined by the underlying operating system.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000089\end{excdesc}
90
Martin v. Löwisc9908c42001-08-04 22:22:45 +000091\begin{excdesc}{herror}
92This exception is raised for address-related errors, i.e. for
Fred Drake87fa3aa2001-12-21 17:45:03 +000093functions that use \var{h_errno} in the C API, including
94\function{gethostbyname_ex()} and \function{gethostbyaddr()}.
Martin v. Löwisc9908c42001-08-04 22:22:45 +000095
96The accompanying value is a pair \code{(\var{h_errno}, \var{string})}
97representing an error returned by a library call. \var{string}
98represents the description of \var{h_errno}, as returned by
Fred Drake87fa3aa2001-12-21 17:45:03 +000099the \cfunction{hstrerror()} C function.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000100\end{excdesc}
101
102\begin{excdesc}{gaierror}
103This exception is raised for address-related errors, for
Fred Drake87fa3aa2001-12-21 17:45:03 +0000104\function{getaddrinfo()} and \function{getnameinfo()}.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000105The accompanying value is a pair \code{(\var{error}, \var{string})}
106representing an error returned by a library call.
107\var{string} represents the description of \var{error}, as returned
Fred Drake87fa3aa2001-12-21 17:45:03 +0000108by the \cfunction{gai_strerror()} C function.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000109\end{excdesc}
110
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000111\begin{datadesc}{AF_UNIX}
112\dataline{AF_INET}
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000113\dataline{AF_INET6}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000114These constants represent the address (and protocol) families,
Fred Draked883ca11998-03-10 05:20:33 +0000115used for the first argument to \function{socket()}. If the
116\constant{AF_UNIX} constant is not defined then this protocol is
117unsupported.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000118\end{datadesc}
119
120\begin{datadesc}{SOCK_STREAM}
121\dataline{SOCK_DGRAM}
Guido van Rossum781db5d1994-08-05 13:37:36 +0000122\dataline{SOCK_RAW}
123\dataline{SOCK_RDM}
124\dataline{SOCK_SEQPACKET}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000125These constants represent the socket types,
Fred Draked883ca11998-03-10 05:20:33 +0000126used for the second argument to \function{socket()}.
127(Only \constant{SOCK_STREAM} and
128\constant{SOCK_DGRAM} appear to be generally useful.)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000129\end{datadesc}
130
Guido van Rossumed2bad81995-02-16 16:29:18 +0000131\begin{datadesc}{SO_*}
132\dataline{SOMAXCONN}
133\dataline{MSG_*}
134\dataline{SOL_*}
135\dataline{IPPROTO_*}
136\dataline{IPPORT_*}
137\dataline{INADDR_*}
138\dataline{IP_*}
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000139\dataline{IPV6_*}
140\dataline{EAI_*}
141\dataline{AI_*}
142\dataline{NI_*}
Fred Drake39960f62001-12-22 19:07:58 +0000143\dataline{TCP_*}
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000144Many constants of these forms, documented in the \UNIX{} documentation on
Guido van Rossumed2bad81995-02-16 16:29:18 +0000145sockets and/or the IP protocol, are also defined in the socket module.
Fred Draked883ca11998-03-10 05:20:33 +0000146They are generally used in arguments to the \method{setsockopt()} and
147\method{getsockopt()} methods of socket objects. In most cases, only
Guido van Rossum6bb1adc1995-03-13 10:03:32 +0000148those symbols that are defined in the \UNIX{} header files are defined;
Guido van Rossumed2bad81995-02-16 16:29:18 +0000149for a few symbols, default values are provided.
150\end{datadesc}
151
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000152\begin{funcdesc}{getaddrinfo}{host, port\optional{, family, socktype, proto, flags}}
153
154Resolves the \var{host}/\var{port} argument, into a sequence of
1555-tuples that contain all the necessary argument for the sockets
156manipulation. \var{host} is a domain name, a string representation of
157IPv4/v6 address or \code{None}.
158\var{port} is a string service name (like \code{``http''}), a numeric
159port number or \code{None}.
160
161The rest of the arguments are optional and must be numeric if
162specified. For \var{host} and \var{port}, by passing either an empty
163string or \code{None}, you can pass \code{NULL} to the C API. The
164\function{getaddrinfo()} function returns a list of 5-tuples with
165the following structure:
166
167\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, \var{sockaddr})}.
168
169\var{family}, \var{socktype}, \var{proto} are all integer and are meant to
170be passed to the \function{socket()} function.
171\var{canonname} is a string representing the canonical name of the \var{host}.
172It can be a numeric IPv4/v6 address when \code{AI_CANONNAME} is specified
173for a numeric \var{host}.
174\var{sockaddr} is a tuple describing a socket address, as described above.
175See \code{Lib/httplib.py} and other library files
176for a typical usage of the function.
177\versionadded{2.2}
178\end{funcdesc}
179
Fred Drake5772c862000-08-16 14:21:42 +0000180\begin{funcdesc}{getfqdn}{\optional{name}}
181Return a fully qualified domain name for \var{name}.
182If \var{name} is omitted or empty, it is interpreted as the local
183host. To find the fully qualified name, the hostname returned by
184\function{gethostbyaddr()} is checked, then aliases for the host, if
185available. The first name which includes a period is selected. In
186case no fully qualified domain name is available, the hostname is
187returned.
Fred Drake8b2e8f82000-09-06 02:22:16 +0000188\versionadded{2.0}
Fred Drake5772c862000-08-16 14:21:42 +0000189\end{funcdesc}
190
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000191\begin{funcdesc}{gethostbyname}{hostname}
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000192Translate a host name to IPv4 address format. The IPv4 address is
Fred Drake87fa3aa2001-12-21 17:45:03 +0000193returned as a string, such as \code{'100.50.200.5'}. If the host name
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000194is an IPv4 address itself it is returned unchanged. See
Fred Drake318c0b11999-04-21 17:29:14 +0000195\function{gethostbyname_ex()} for a more complete interface.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000196\function{gethostbyname()} does not support IPv6 name resolution, and
197\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
Guido van Rossumcdf6af11998-08-07 18:07:36 +0000198\end{funcdesc}
199
200\begin{funcdesc}{gethostbyname_ex}{hostname}
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000201Translate a host name to IPv4 address format, extended interface.
Guido van Rossumcdf6af11998-08-07 18:07:36 +0000202Return a triple \code{(hostname, aliaslist, ipaddrlist)} where
203\code{hostname} is the primary host name responding to the given
204\var{ip_address}, \code{aliaslist} is a (possibly empty) list of
205alternative host names for the same address, and \code{ipaddrlist} is
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000206a list of IPv4 addresses for the same interface on the same
Guido van Rossumcdf6af11998-08-07 18:07:36 +0000207host (often but not always a single address).
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000208\function{gethostbyname_ex()} does not support IPv6 name resolution, and
209\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000210\end{funcdesc}
211
Guido van Rossum781db5d1994-08-05 13:37:36 +0000212\begin{funcdesc}{gethostname}{}
Guido van Rossum16d6e711994-08-08 12:30:22 +0000213Return a string containing the hostname of the machine where
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000214the Python interpreter is currently executing.
215If you want to know the current machine's IP address, you may want to use
216\code{gethostbyname(gethostname())}.
217This operation assumes that there is a valid address-to-host mapping for
218the host, and the assumption does not always hold.
Fred Draked883ca11998-03-10 05:20:33 +0000219Note: \function{gethostname()} doesn't always return the fully qualified
220domain name; use \code{gethostbyaddr(gethostname())}
Guido van Rossumfe27a501997-01-11 17:04:56 +0000221(see below).
Guido van Rossum31cce971995-01-04 19:17:34 +0000222\end{funcdesc}
223
224\begin{funcdesc}{gethostbyaddr}{ip_address}
Fred Draked883ca11998-03-10 05:20:33 +0000225Return a triple \code{(\var{hostname}, \var{aliaslist},
226\var{ipaddrlist})} where \var{hostname} is the primary host name
227responding to the given \var{ip_address}, \var{aliaslist} is a
228(possibly empty) list of alternative host names for the same address,
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000229and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface
Fred Draked883ca11998-03-10 05:20:33 +0000230on the same host (most likely containing only a single address).
Fred Drake5772c862000-08-16 14:21:42 +0000231To find the fully qualified domain name, use the function
232\function{getfqdn()}.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000233\function{gethostbyaddr} supports both IPv4 and IPv6.
234\end{funcdesc}
235
236\begin{funcdesc}{getnameinfo}{sockaddr, flags}
237Translate a socket address \var{sockaddr} into a 2-tuple
238\code{(\var{host}, \var{port})}.
239Depending on the settings of \var{flags}, the result can contain a
240fully-qualified domain name or numeric address representation in
241\var{host}. Similarly, \var{port} can contain a string port name or a
242numeric port number.
243\versionadded{2.2}
Guido van Rossum781db5d1994-08-05 13:37:36 +0000244\end{funcdesc}
245
Guido van Rossum62ac99e1996-12-19 16:43:25 +0000246\begin{funcdesc}{getprotobyname}{protocolname}
Fred Drake87fa3aa2001-12-21 17:45:03 +0000247Translate an Internet protocol name (for example, \code{'icmp'}) to a constant
Guido van Rossum62ac99e1996-12-19 16:43:25 +0000248suitable for passing as the (optional) third argument to the
Fred Draked883ca11998-03-10 05:20:33 +0000249\function{socket()} function. This is usually only needed for sockets
250opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
251modes, the correct protocol is chosen automatically if the protocol is
Guido van Rossum62ac99e1996-12-19 16:43:25 +0000252omitted or zero.
253\end{funcdesc}
254
Fred Draked883ca11998-03-10 05:20:33 +0000255\begin{funcdesc}{getservbyname}{servicename, protocolname}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000256Translate an Internet service name and protocol name to a port number
257for that service. The protocol name should be \code{'tcp'} or
258\code{'udp'}.
259\end{funcdesc}
260
Fred Draked883ca11998-03-10 05:20:33 +0000261\begin{funcdesc}{socket}{family, type\optional{, proto}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000262Create a new socket using the given address family, socket type and
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000263protocol number. The address family should be \constant{AF_INET}, \constant{AF_INET6} or
Fred Draked883ca11998-03-10 05:20:33 +0000264\constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM},
265\constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000266The protocol number is usually zero and may be omitted in that case.
267\end{funcdesc}
268
Jeremy Hyltoncb43c082001-10-11 16:17:22 +0000269\begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}}
Fred Drake9081bb12001-09-25 15:48:11 +0000270Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is
271the name of a PEM formatted file that contains your private
272key. \var{certfile} is a PEM formatted certificate chain file. On
273success, a new \class{SSLObject} is returned.
274
Fred Drake0aa811c2001-10-20 04:24:09 +0000275\warning{This does not do any certificate verification!}
Fred Drake9081bb12001-09-25 15:48:11 +0000276\end{funcdesc}
277
Fred Draked883ca11998-03-10 05:20:33 +0000278\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000279Build a socket object from an existing file descriptor (an integer as
Fred Draked883ca11998-03-10 05:20:33 +0000280returned by a file object's \method{fileno()} method). Address family,
Fred Drake318c0b11999-04-21 17:29:14 +0000281socket type and protocol number are as for the \function{socket()} function
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000282above. The file descriptor should refer to a socket, but this is not
283checked --- subsequent operations on the object may fail if the file
284descriptor is invalid. This function is rarely needed, but can be
285used to get or set socket options on a socket passed to a program as
Fred Drake87fa3aa2001-12-21 17:45:03 +0000286standard input or output (such as a server started by the \UNIX{} inet
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000287daemon).
Fred Drake87fa3aa2001-12-21 17:45:03 +0000288Availability: \UNIX.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000289\end{funcdesc}
290
Guido van Rossumbda7ca71996-12-02 17:24:10 +0000291\begin{funcdesc}{ntohl}{x}
Fred Drakec5aec051997-12-08 21:25:41 +0000292Convert 32-bit integers from network to host byte order. On machines
293where the host byte order is the same as network byte order, this is a
294no-op; otherwise, it performs a 4-byte swap operation.
295\end{funcdesc}
296
297\begin{funcdesc}{ntohs}{x}
298Convert 16-bit integers from network to host byte order. On machines
299where the host byte order is the same as network byte order, this is a
300no-op; otherwise, it performs a 2-byte swap operation.
301\end{funcdesc}
302
303\begin{funcdesc}{htonl}{x}
304Convert 32-bit integers from host to network byte order. On machines
305where the host byte order is the same as network byte order, this is a
306no-op; otherwise, it performs a 4-byte swap operation.
307\end{funcdesc}
308
309\begin{funcdesc}{htons}{x}
310Convert 16-bit integers from host to network byte order. On machines
311where the host byte order is the same as network byte order, this is a
312no-op; otherwise, it performs a 2-byte swap operation.
Guido van Rossumbda7ca71996-12-02 17:24:10 +0000313\end{funcdesc}
314
Fred Drakee6fb1c41999-09-16 15:50:00 +0000315\begin{funcdesc}{inet_aton}{ip_string}
Fred Drake87fa3aa2001-12-21 17:45:03 +0000316Convert an IPv4 address from dotted-quad string format (for example,
317'123.45.67.89') to 32-bit packed binary format, as a string four
Fred Drakee6fb1c41999-09-16 15:50:00 +0000318characters in length.
319
320Useful when conversing with a program that uses the standard C library
321and needs objects of type \ctype{struct in_addr}, which is the C type
322for the 32-bit packed binary this function returns.
323
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000324If the IPv4 address string passed to this function is invalid,
Fred Drakee6fb1c41999-09-16 15:50:00 +0000325\exception{socket.error} will be raised. Note that exactly what is
326valid depends on the underlying C implementation of
327\cfunction{inet_aton()}.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000328
Fred Drake39960f62001-12-22 19:07:58 +0000329\function{inet_aton()} does not support IPv6, and
330\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
331support.
Fred Drakee6fb1c41999-09-16 15:50:00 +0000332\end{funcdesc}
333
334\begin{funcdesc}{inet_ntoa}{packed_ip}
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000335Convert a 32-bit packed IPv4 address (a string four characters in
Fred Drakee6fb1c41999-09-16 15:50:00 +0000336length) to its standard dotted-quad string representation
Fred Drake87fa3aa2001-12-21 17:45:03 +0000337(for example, '123.45.67.89').
Fred Drakee6fb1c41999-09-16 15:50:00 +0000338
339Useful when conversing with a program that uses the standard C library
340and needs objects of type \ctype{struct in_addr}, which is the C type
341for the 32-bit packed binary this function takes as an argument.
342
343If the string passed to this function is not exactly 4 bytes in
344length, \exception{socket.error} will be raised.
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000345
Fred Drake39960f62001-12-22 19:07:58 +0000346\function{inet_ntoa()} does not support IPv6, and
347\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
348support.
Fred Drakee6fb1c41999-09-16 15:50:00 +0000349\end{funcdesc}
350
Fred Drake5451d671997-10-13 21:31:02 +0000351\begin{datadesc}{SocketType}
Guido van Rossum2335c5e1997-05-21 14:41:42 +0000352This is a Python type object that represents the socket object type.
Fred Draked883ca11998-03-10 05:20:33 +0000353It is the same as \code{type(socket(...))}.
Guido van Rossum2335c5e1997-05-21 14:41:42 +0000354\end{datadesc}
355
Fred Drakeaa7524c2000-07-06 18:37:08 +0000356
357\begin{seealso}
358 \seemodule{SocketServer}{Classes that simplify writing network servers.}
359\end{seealso}
360
361
Fred Drakea94f6761999-08-05 13:41:04 +0000362\subsection{Socket Objects \label{socket-objects}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000363
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000364Socket objects have the following methods. Except for
Fred Draked883ca11998-03-10 05:20:33 +0000365\method{makefile()} these correspond to \UNIX{} system calls
366applicable to sockets.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000367
Fred Drake3f1c4721998-04-03 07:04:45 +0000368\begin{methoddesc}[socket]{accept}{}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000369Accept a connection.
370The socket must be bound to an address and listening for connections.
371The return value is a pair \code{(\var{conn}, \var{address})}
372where \var{conn} is a \emph{new} socket object usable to send and
373receive data on the connection, and \var{address} is the address bound
374to the socket on the other end of the connection.
Fred Drake3f1c4721998-04-03 07:04:45 +0000375\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000376
Fred Drake3f1c4721998-04-03 07:04:45 +0000377\begin{methoddesc}[socket]{bind}{address}
Guido van Rossuma84ec511994-06-23 12:13:52 +0000378Bind the socket to \var{address}. The socket must not already be bound.
Fred Drake7d686902000-04-04 17:48:30 +0000379(The format of \var{address} depends on the address family --- see
Fred Drake0aa811c2001-10-20 04:24:09 +0000380above.) \note{This method has historically accepted a pair
Fred Drake7d686902000-04-04 17:48:30 +0000381of parameters for \constant{AF_INET} addresses instead of only a
Eric S. Raymond83210262001-01-10 19:34:52 +0000382tuple. This was never intentional and is no longer be available in
Fred Drake0aa811c2001-10-20 04:24:09 +0000383Python 2.0.}
Fred Drake3f1c4721998-04-03 07:04:45 +0000384\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000385
Fred Drake3f1c4721998-04-03 07:04:45 +0000386\begin{methoddesc}[socket]{close}{}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000387Close the socket. All future operations on the socket object will fail.
388The remote end will receive no more data (after queued data is flushed).
389Sockets are automatically closed when they are garbage-collected.
Fred Drake3f1c4721998-04-03 07:04:45 +0000390\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000391
Fred Drake3f1c4721998-04-03 07:04:45 +0000392\begin{methoddesc}[socket]{connect}{address}
Guido van Rossuma84ec511994-06-23 12:13:52 +0000393Connect to a remote socket at \var{address}.
Fred Draked883ca11998-03-10 05:20:33 +0000394(The format of \var{address} depends on the address family --- see
Fred Drake0aa811c2001-10-20 04:24:09 +0000395above.) \note{This method has historically accepted a pair
Fred Drake7d686902000-04-04 17:48:30 +0000396of parameters for \constant{AF_INET} addresses instead of only a
Eric S. Raymond83210262001-01-10 19:34:52 +0000397tuple. This was never intentional and is no longer available in
Fred Drake0aa811c2001-10-20 04:24:09 +0000398Python 2.0 and later.}
Fred Drake3f1c4721998-04-03 07:04:45 +0000399\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000400
Fred Drake3f1c4721998-04-03 07:04:45 +0000401\begin{methoddesc}[socket]{connect_ex}{address}
Guido van Rossumeefcba61997-12-09 19:47:24 +0000402Like \code{connect(\var{address})}, but return an error indicator
Fred Drakeb0bc7f21999-05-06 22:03:50 +0000403instead of raising an exception for errors returned by the C-level
404\cfunction{connect()} call (other problems, such as ``host not found,''
405can still raise exceptions). The error indicator is \code{0} if the
Fred Draked883ca11998-03-10 05:20:33 +0000406operation succeeded, otherwise the value of the \cdata{errno}
Fred Drake87fa3aa2001-12-21 17:45:03 +0000407variable. This is useful to support, for example, asynchronous connects.
Fred Drake0aa811c2001-10-20 04:24:09 +0000408\note{This method has historically accepted a pair of
Fred Drake7d686902000-04-04 17:48:30 +0000409parameters for \constant{AF_INET} addresses instead of only a tuple.
Eric S. Raymond83210262001-01-10 19:34:52 +0000410This was never intentional and is no longer be available in Python
Fred Drake0aa811c2001-10-20 04:24:09 +00004112.0 and later.}
Fred Drake3f1c4721998-04-03 07:04:45 +0000412\end{methoddesc}
Guido van Rossumf7790c61997-11-18 15:29:20 +0000413
Fred Drake3f1c4721998-04-03 07:04:45 +0000414\begin{methoddesc}[socket]{fileno}{}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000415Return the socket's file descriptor (a small integer). This is useful
Fred Draked883ca11998-03-10 05:20:33 +0000416with \function{select.select()}.
Fred Drake3f1c4721998-04-03 07:04:45 +0000417\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000418
Fred Drake3f1c4721998-04-03 07:04:45 +0000419\begin{methoddesc}[socket]{getpeername}{}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000420Return the remote address to which the socket is connected. This is
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000421useful to find out the port number of a remote IPv4/v6 socket, for instance.
Guido van Rossum86751151995-02-28 17:14:32 +0000422(The format of the address returned depends on the address family ---
Guido van Rossum781db5d1994-08-05 13:37:36 +0000423see above.) On some systems this function is not supported.
Fred Drake3f1c4721998-04-03 07:04:45 +0000424\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000425
Fred Drake3f1c4721998-04-03 07:04:45 +0000426\begin{methoddesc}[socket]{getsockname}{}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000427Return the socket's own address. This is useful to find out the port
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000428number of an IPv4/v6 socket, for instance.
Guido van Rossum86751151995-02-28 17:14:32 +0000429(The format of the address returned depends on the address family ---
Guido van Rossuma84ec511994-06-23 12:13:52 +0000430see above.)
Fred Drake3f1c4721998-04-03 07:04:45 +0000431\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000432
Fred Drake3f1c4721998-04-03 07:04:45 +0000433\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000434Return the value of the given socket option (see the \UNIX{} man page
Fred Draked883ca11998-03-10 05:20:33 +0000435\manpage{getsockopt}{2}). The needed symbolic constants
436(\constant{SO_*} etc.) are defined in this module. If \var{buflen}
Guido van Rossum470be141995-03-17 16:07:09 +0000437is absent, an integer option is assumed and its integer value
Guido van Rossum8df36371995-02-27 17:52:15 +0000438is returned by the function. If \var{buflen} is present, it specifies
439the maximum length of the buffer used to receive the option in, and
Guido van Rossum470be141995-03-17 16:07:09 +0000440this buffer is returned as a string. It is up to the caller to decode
Guido van Rossum8df36371995-02-27 17:52:15 +0000441the contents of the buffer (see the optional built-in module
Fred Drake318c0b11999-04-21 17:29:14 +0000442\refmodule{struct} for a way to decode C structures encoded as strings).
Fred Drake3f1c4721998-04-03 07:04:45 +0000443\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000444
Fred Drake3f1c4721998-04-03 07:04:45 +0000445\begin{methoddesc}[socket]{listen}{backlog}
Guido van Rossum470be141995-03-17 16:07:09 +0000446Listen for connections made to the socket. The \var{backlog} argument
447specifies the maximum number of queued connections and should be at
448least 1; the maximum value is system-dependent (usually 5).
Fred Drake3f1c4721998-04-03 07:04:45 +0000449\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000450
Fred Drake3f1c4721998-04-03 07:04:45 +0000451\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}}
Guido van Rossum470be141995-03-17 16:07:09 +0000452Return a \dfn{file object} associated with the socket. (File objects
Fred Drakea94f6761999-08-05 13:41:04 +0000453are described in \ref{bltin-file-objects}, ``File Objects.'')
Fred Draked883ca11998-03-10 05:20:33 +0000454The file object references a \cfunction{dup()}ped version of the
455socket file descriptor, so the file object and socket object may be
Fred Drakea94f6761999-08-05 13:41:04 +0000456closed or garbage-collected independently.
457\index{I/O control!buffering}The optional \var{mode}
Fred Draked883ca11998-03-10 05:20:33 +0000458and \var{bufsize} arguments are interpreted the same way as by the
Fred Drakeaad8bb52001-10-19 17:22:29 +0000459built-in \function{file()} function; see ``Built-in Functions''
460(section \ref{built-in-funcs}) for more information.
Fred Drake3f1c4721998-04-03 07:04:45 +0000461\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000462
Fred Drake3f1c4721998-04-03 07:04:45 +0000463\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000464Receive data from the socket. The return value is a string representing
465the data received. The maximum amount of data to be received
466at once is specified by \var{bufsize}. See the \UNIX{} manual page
Fred Draked883ca11998-03-10 05:20:33 +0000467\manpage{recv}{2} for the meaning of the optional argument
468\var{flags}; it defaults to zero.
Fred Drake3f1c4721998-04-03 07:04:45 +0000469\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000470
Fred Drake3f1c4721998-04-03 07:04:45 +0000471\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000472Receive data from the socket. The return value is a pair
473\code{(\var{string}, \var{address})} where \var{string} is a string
474representing the data received and \var{address} is the address of the
Guido van Rossum470be141995-03-17 16:07:09 +0000475socket sending the data. The optional \var{flags} argument has the
Fred Draked883ca11998-03-10 05:20:33 +0000476same meaning as for \method{recv()} above.
Guido van Rossum86751151995-02-28 17:14:32 +0000477(The format of \var{address} depends on the address family --- see above.)
Fred Drake3f1c4721998-04-03 07:04:45 +0000478\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000479
Fred Drake3f1c4721998-04-03 07:04:45 +0000480\begin{methoddesc}[socket]{send}{string\optional{, flags}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000481Send data to the socket. The socket must be connected to a remote
Guido van Rossum470be141995-03-17 16:07:09 +0000482socket. The optional \var{flags} argument has the same meaning as for
Fred Draked883ca11998-03-10 05:20:33 +0000483\method{recv()} above. Returns the number of bytes sent.
Fred Drake39368c12001-12-05 05:25:59 +0000484Applications are responsible for checking that all data has been sent;
485if only some of the data was transmitted, the application needs to
486attempt delivery of the remaining data.
487\end{methoddesc}
488
489\begin{methoddesc}[socket]{sendall}{string\optional{, flags}}
490Send data to the socket. The socket must be connected to a remote
491socket. The optional \var{flags} argument has the same meaning as for
492\method{recv()} above. Unlike \method{send()}, this method continues
493to send data from \var{string} until either all data has been sent or
494an error occurs. \code{None} is returned on success. On error, an
495exception is raised, and there is no way to determine how much data,
496if any, was successfully sent.
Fred Drake3f1c4721998-04-03 07:04:45 +0000497\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000498
Fred Drake3f1c4721998-04-03 07:04:45 +0000499\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000500Send data to the socket. The socket should not be connected to a
501remote socket, since the destination socket is specified by
Fred Draked883ca11998-03-10 05:20:33 +0000502\var{address}. The optional \var{flags} argument has the same
503meaning as for \method{recv()} above. Return the number of bytes sent.
Guido van Rossum86751151995-02-28 17:14:32 +0000504(The format of \var{address} depends on the address family --- see above.)
Fred Drake3f1c4721998-04-03 07:04:45 +0000505\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000506
Fred Drake3f1c4721998-04-03 07:04:45 +0000507\begin{methoddesc}[socket]{setblocking}{flag}
Guido van Rossum91951481994-09-07 14:39:14 +0000508Set blocking or non-blocking mode of the socket: if \var{flag} is 0,
509the socket is set to non-blocking, else to blocking mode. Initially
510all sockets are in blocking mode. In non-blocking mode, if a
Fred Drake318c0b11999-04-21 17:29:14 +0000511\method{recv()} call doesn't find any data, or if a
512\method{send()} call can't immediately dispose of the data, a
513\exception{error} exception is raised; in blocking mode, the calls
514block until they can proceed.
Fred Drake3f1c4721998-04-03 07:04:45 +0000515\end{methoddesc}
Guido van Rossum91951481994-09-07 14:39:14 +0000516
Guido van Rossumbe946bf2002-06-06 21:51:01 +0000517\begin{methoddesc}[socket]{settimeout}{value}
Fred Drake6c6d6622002-06-06 21:57:48 +0000518Set a timeout on blocking socket operations. Value can be any numeric
519value or \code{None}. Socket operations will raise an
520\exception{error} exception if the timeout period \var{value} has
521elapsed before the operation has completed. Setting a timeout of
522\code{None} disables timeouts on socket operations.
Neal Norwitzbdbd84f2002-06-06 22:24:10 +0000523\versionadded{2.3}
Guido van Rossumbe946bf2002-06-06 21:51:01 +0000524\end{methoddesc}
525
526\begin{methoddesc}[socket]{gettimeout}{}
Fred Drake6c6d6622002-06-06 21:57:48 +0000527Returns the timeout in floating seconds associated with socket
528operations. A timeout of \code{None} indicates that timeouts on
529socket operations are disabled.
Neal Norwitzbdbd84f2002-06-06 22:24:10 +0000530\versionadded{2.3}
Guido van Rossumbe946bf2002-06-06 21:51:01 +0000531\end{methoddesc}
532
533Some notes on the interaction between socket blocking and timeouts:
Neal Norwitzbdbd84f2002-06-06 22:24:10 +0000534socket blocking mode takes precedence over timeouts. If a socket is
535set to non-blocking mode, then timeouts are not used.
Fred Drake6c6d6622002-06-06 21:57:48 +0000536The timeout value associated with the socket can still be set using
537\method{settimeout()} and its value retrieved using
538\method{gettimeout()}, but the timeout is never enforced (an exception
539will never be thrown). Otherwise, if the socket is in blocking mode,
540setting the timeout will raise an exception as expected.
Guido van Rossumbe946bf2002-06-06 21:51:01 +0000541
Fred Drake3f1c4721998-04-03 07:04:45 +0000542\begin{methoddesc}[socket]{setsockopt}{level, optname, value}
Fred Drake9a748aa2000-06-30 04:21:41 +0000543Set the value of the given socket option (see the \UNIX{} manual page
Fred Draked883ca11998-03-10 05:20:33 +0000544\manpage{setsockopt}{2}). The needed symbolic constants are defined in
545the \module{socket} module (\code{SO_*} etc.). The value can be an
Guido van Rossum8df36371995-02-27 17:52:15 +0000546integer or a string representing a buffer. In the latter case it is
547up to the caller to ensure that the string contains the proper bits
548(see the optional built-in module
Fred Drake318c0b11999-04-21 17:29:14 +0000549\refmodule{struct}\refbimodindex{struct} for a way to encode C
550structures as strings).
Fred Drake3f1c4721998-04-03 07:04:45 +0000551\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000552
Fred Drake3f1c4721998-04-03 07:04:45 +0000553\begin{methoddesc}[socket]{shutdown}{how}
Fred Draked883ca11998-03-10 05:20:33 +0000554Shut down one or both halves of the connection. If \var{how} is
555\code{0}, further receives are disallowed. If \var{how} is \code{1},
556further sends are disallowed. If \var{how} is \code{2}, further sends
557and receives are disallowed.
Fred Drake3f1c4721998-04-03 07:04:45 +0000558\end{methoddesc}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000559
Fred Draked883ca11998-03-10 05:20:33 +0000560Note that there are no methods \method{read()} or \method{write()};
561use \method{recv()} and \method{send()} without \var{flags} argument
562instead.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000563
Fred Drakeaa7524c2000-07-06 18:37:08 +0000564
Fred Drake9081bb12001-09-25 15:48:11 +0000565\subsection{SSL Objects \label{ssl-objects}}
566
567SSL objects have the following methods.
568
569\begin{methoddesc}{write}{s}
570Writes the string \var{s} to the on the object's SSL connection.
571The return value is the number of bytes written.
572\end{methoddesc}
573
574\begin{methoddesc}{read}{\optional{n}}
575If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise
576read until EOF. The return value is a string of the bytes read.
577\end{methoddesc}
578
Fred Drakeaa7524c2000-07-06 18:37:08 +0000579\subsection{Example \label{socket-example}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000580
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000581Here are four minimal example programs using the TCP/IP protocol:\ a
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000582server that echoes all data that it receives back (servicing only one
583client), and a client using it. Note that a server must perform the
Fred Draked883ca11998-03-10 05:20:33 +0000584sequence \function{socket()}, \method{bind()}, \method{listen()},
585\method{accept()} (possibly repeating the \method{accept()} to service
586more than one client), while a client only needs the sequence
587\function{socket()}, \method{connect()}. Also note that the server
588does not \method{send()}/\method{recv()} on the
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000589socket it is listening on but on the new socket returned by
Fred Draked883ca11998-03-10 05:20:33 +0000590\method{accept()}.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000591
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000592The first two examples support IPv4 only.
593
Fred Drake19479911998-02-13 06:58:54 +0000594\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000595# Echo server program
Fred Drakeef52f602000-10-10 20:36:29 +0000596import socket
597
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000598HOST = '' # Symbolic name meaning the local host
Fred Drakeef52f602000-10-10 20:36:29 +0000599PORT = 50007 # Arbitrary non-privileged port
600s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
Fred Drake3d69c0e2000-05-03 19:40:32 +0000601s.bind((HOST, PORT))
Guido van Rossum5da57551994-03-02 10:52:16 +0000602s.listen(1)
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000603conn, addr = s.accept()
604print 'Connected by', addr
605while 1:
606 data = conn.recv(1024)
607 if not data: break
608 conn.send(data)
609conn.close()
Fred Drake19479911998-02-13 06:58:54 +0000610\end{verbatim}
Fred Draked883ca11998-03-10 05:20:33 +0000611
Fred Drake19479911998-02-13 06:58:54 +0000612\begin{verbatim}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000613# Echo client program
Fred Drakeef52f602000-10-10 20:36:29 +0000614import socket
615
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000616HOST = 'daring.cwi.nl' # The remote host
617PORT = 50007 # The same port as used by the server
Fred Drakeef52f602000-10-10 20:36:29 +0000618s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
Fred Drake3d69c0e2000-05-03 19:40:32 +0000619s.connect((HOST, PORT))
Guido van Rossum5fdeeea1994-01-02 01:22:07 +0000620s.send('Hello, world')
621data = s.recv(1024)
622s.close()
623print 'Received', `data`
Fred Drake19479911998-02-13 06:58:54 +0000624\end{verbatim}
Martin v. Löwisc9908c42001-08-04 22:22:45 +0000625
626The next two examples are identical to the above two, but support both
627IPv4 and IPv6.
628The server side will listen to the first address family available
629(it should listen to both instead).
630On most of IPv6-ready systems, IPv6 will take precedence
631and the server may not accept IPv4 traffic.
632The client side will try to connect to the all addresses returned as a result
633of the name resolution, and sends traffic to the first one connected
634successfully.
635
636\begin{verbatim}
637# Echo server program
638import socket
639import sys
640
641HOST = '' # Symbolic name meaning the local host
642PORT = 50007 # Arbitrary non-privileged port
643s = None
644for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
645 af, socktype, proto, canonname, sa = res
646 try:
647 s = socket.socket(af, socktype, proto)
648 except socket.error, msg:
649 s = None
650 continue
651 try:
652 s.bind(sa)
653 s.listen(1)
654 except socket.error, msg:
655 s.close()
656 s = None
657 continue
658 break
659if s is None:
660 print 'could not open socket'
661 sys.exit(1)
662conn, addr = s.accept()
663print 'Connected by', addr
664while 1:
665 data = conn.recv(1024)
666 if not data: break
667 conn.send(data)
668conn.close()
669\end{verbatim}
670
671\begin{verbatim}
672# Echo client program
673import socket
674import sys
675
676HOST = 'daring.cwi.nl' # The remote host
677PORT = 50007 # The same port as used by the server
678s = None
679for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
680 af, socktype, proto, canonname, sa = res
681 try:
682 s = socket.socket(af, socktype, proto)
683 except socket.error, msg:
684 s = None
685 continue
686 try:
687 s.connect(sa)
688 except socket.error, msg:
689 s.close()
690 s = None
691 continue
692 break
693if s is None:
694 print 'could not open socket'
695 sys.exit(1)
696s.send('Hello, world')
697data = s.recv(1024)
698s.close()
699print 'Received', `data`
700\end{verbatim}