PageRenderTime 21ms CodeModel.GetById 3ms app.highlight 10ms RepoModel.GetById 1ms app.codeStats 1ms

/Doc/lib/libsocket.tex

https://bitbucket.org/mirror/python-release25-maint
LaTeX | 910 lines | 785 code | 125 blank | 0 comment | 0 complexity | 2a14cbf861dad04fa0f8aba1be28ee43 MD5 | raw file
  1\section{\module{socket} ---
  2         Low-level networking interface}
  3
  4\declaremodule{builtin}{socket}
  5\modulesynopsis{Low-level networking interface.}
  6
  7
  8This module provides access to the BSD \emph{socket} interface.
  9It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
 10OS/2, and probably additional platforms.  \note{Some behavior may be
 11platform dependent, since calls are made to the operating system socket APIs.}
 12
 13For an introduction to socket programming (in C), see the following
 14papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
 15Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
 16Interprocess Communication Tutorial}, by Samuel J.  Leffler et al,
 17both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1}
 18(sections PS1:7 and PS1:8).  The platform-specific reference material
 19for the various socket-related system calls are also a valuable source
 20of information on the details of socket semantics.  For \UNIX, refer
 21to the manual pages; for Windows, see the WinSock (or Winsock 2)
 22specification.
 23For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled
 24\citetitle{Basic Socket Interface Extensions for IPv6}.
 25
 26The Python interface is a straightforward transliteration of the
 27\UNIX{} system call and library interface for sockets to Python's
 28object-oriented style: the \function{socket()} function returns a
 29\dfn{socket object}\obindex{socket} whose methods implement the
 30various socket system calls.  Parameter types are somewhat
 31higher-level than in the C interface: as with \method{read()} and
 32\method{write()} operations on Python files, buffer allocation on
 33receive operations is automatic, and buffer length is implicit on send
 34operations.
 35
 36Socket addresses are represented as follows:
 37A single string is used for the \constant{AF_UNIX} address family.
 38A pair \code{(\var{host}, \var{port})} is used for the
 39\constant{AF_INET} address family, where \var{host} is a string
 40representing either a hostname in Internet domain notation like
 41\code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'},
 42and \var{port} is an integral port number.
 43For \constant{AF_INET6} address family, a four-tuple
 44\code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is
 45used, where \var{flowinfo} and \var{scopeid} represents
 46\code{sin6_flowinfo} and \code{sin6_scope_id} member in
 47\constant{struct sockaddr_in6} in C.
 48For \module{socket} module methods, \var{flowinfo} and \var{scopeid}
 49can be omitted just for backward compatibility. Note, however,
 50omission of \var{scopeid} can cause problems in manipulating scoped
 51IPv6 addresses. Other address families are currently not supported.
 52The address format required by a particular socket object is
 53automatically selected based on the address family specified when the
 54socket object was created.
 55
 56For IPv4 addresses, two special forms are accepted instead of a host
 57address: the empty string represents \constant{INADDR_ANY}, and the string
 58\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
 59The behavior is not available for IPv6 for backward compatibility,
 60therefore, you may want to avoid these if you intend to support IPv6 with
 61your Python programs.
 62
 63If you use a hostname in the \var{host} portion of IPv4/v6 socket
 64address, the program may show a nondeterministic behavior, as Python
 65uses the first address returned from the DNS resolution.  The socket
 66address will be resolved differently into an actual IPv4/v6 address,
 67depending on the results from DNS resolution and/or the host
 68configuration.  For deterministic behavior use a numeric address in
 69\var{host} portion.
 70
 71\versionadded[AF_NETLINK sockets are represented as 
 72pairs \code{\var{pid}, \var{groups}}]{2.5}
 73
 74All errors raise exceptions.  The normal exceptions for invalid
 75argument types and out-of-memory conditions can be raised; errors
 76related to socket or address semantics raise the error
 77\exception{socket.error}.
 78
 79Non-blocking mode is supported through
 80\method{setblocking()}.  A generalization of this based on timeouts
 81is supported through \method{settimeout()}.
 82
 83The module \module{socket} exports the following constants and functions:
 84
 85
 86\begin{excdesc}{error}
 87This exception is raised for socket-related errors.
 88The accompanying value is either a string telling what went wrong or a
 89pair \code{(\var{errno}, \var{string})}
 90representing an error returned by a system
 91call, similar to the value accompanying \exception{os.error}.
 92See the module \refmodule{errno}\refbimodindex{errno}, which contains
 93names for the error codes defined by the underlying operating system.
 94\end{excdesc}
 95
 96\begin{excdesc}{herror}
 97This exception is raised for address-related errors, i.e. for
 98functions that use \var{h_errno} in the C API, including
 99\function{gethostbyname_ex()} and \function{gethostbyaddr()}.
100
101The accompanying value is a pair \code{(\var{h_errno}, \var{string})}
102representing an error returned by a library call. \var{string}
103represents the description of \var{h_errno}, as returned by
104the \cfunction{hstrerror()} C function.
105\end{excdesc}
106
107\begin{excdesc}{gaierror}
108This exception is raised for address-related errors, for
109\function{getaddrinfo()} and \function{getnameinfo()}.
110The accompanying value is a pair \code{(\var{error}, \var{string})}
111representing an error returned by a library call.
112\var{string} represents the description of \var{error}, as returned
113by the \cfunction{gai_strerror()} C function.
114The \var{error} value will match one of the \constant{EAI_*} constants
115defined in this module.
116\end{excdesc}
117
118\begin{excdesc}{timeout}
119This exception is raised when a timeout occurs on a socket which has
120had timeouts enabled via a prior call to \method{settimeout()}.  The
121accompanying value is a string whose value is currently always ``timed
122out''.
123\versionadded{2.3}
124\end{excdesc}
125
126\begin{datadesc}{AF_UNIX}
127\dataline{AF_INET}
128\dataline{AF_INET6}
129These constants represent the address (and protocol) families,
130used for the first argument to \function{socket()}.  If the
131\constant{AF_UNIX} constant is not defined then this protocol is
132unsupported.
133\end{datadesc}
134
135\begin{datadesc}{SOCK_STREAM}
136\dataline{SOCK_DGRAM}
137\dataline{SOCK_RAW}
138\dataline{SOCK_RDM}
139\dataline{SOCK_SEQPACKET}
140These constants represent the socket types,
141used for the second argument to \function{socket()}.
142(Only \constant{SOCK_STREAM} and
143\constant{SOCK_DGRAM} appear to be generally useful.)
144\end{datadesc}
145
146\begin{datadesc}{SO_*}
147\dataline{SOMAXCONN}
148\dataline{MSG_*}
149\dataline{SOL_*}
150\dataline{IPPROTO_*}
151\dataline{IPPORT_*}
152\dataline{INADDR_*}
153\dataline{IP_*}
154\dataline{IPV6_*}
155\dataline{EAI_*}
156\dataline{AI_*}
157\dataline{NI_*}
158\dataline{TCP_*}
159Many constants of these forms, documented in the \UNIX{} documentation on
160sockets and/or the IP protocol, are also defined in the socket module.
161They are generally used in arguments to the \method{setsockopt()} and
162\method{getsockopt()} methods of socket objects.  In most cases, only
163those symbols that are defined in the \UNIX{} header files are defined;
164for a few symbols, default values are provided.
165\end{datadesc}
166
167\begin{datadesc}{has_ipv6}
168This constant contains a boolean value which indicates if IPv6 is
169supported on this platform.
170\versionadded{2.3}
171\end{datadesc}
172
173\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{,
174                              socktype\optional{, proto\optional{,
175                              flags}}}}}
176Resolves the \var{host}/\var{port} argument, into a sequence of
1775-tuples that contain all the necessary argument for the sockets
178manipulation. \var{host} is a domain name, a string representation of
179IPv4/v6 address or \code{None}.
180\var{port} is a string service name (like \code{'http'}), a numeric
181port number or \code{None}.
182
183The rest of the arguments are optional and must be numeric if
184specified.  For \var{host} and \var{port}, by passing either an empty
185string or \code{None}, you can pass \code{NULL} to the C API.  The
186\function{getaddrinfo()} function returns a list of 5-tuples with
187the following structure:
188
189\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
190      \var{sockaddr})}
191
192\var{family}, \var{socktype}, \var{proto} are all integer and are meant to
193be passed to the \function{socket()} function.
194\var{canonname} is a string representing the canonical name of the \var{host}.
195It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified
196for a numeric \var{host}.
197\var{sockaddr} is a tuple describing a socket address, as described above.
198See the source for the \refmodule{httplib} and other library modules
199for a typical usage of the function.
200\versionadded{2.2}
201\end{funcdesc}
202
203\begin{funcdesc}{getfqdn}{\optional{name}}
204Return a fully qualified domain name for \var{name}.
205If \var{name} is omitted or empty, it is interpreted as the local
206host.  To find the fully qualified name, the hostname returned by
207\function{gethostbyaddr()} is checked, then aliases for the host, if
208available.  The first name which includes a period is selected.  In
209case no fully qualified domain name is available, the hostname as
210returned by \function{gethostname()} is returned.
211\versionadded{2.0}
212\end{funcdesc}
213
214\begin{funcdesc}{gethostbyname}{hostname}
215Translate a host name to IPv4 address format.  The IPv4 address is
216returned as a string, such as  \code{'100.50.200.5'}.  If the host name
217is an IPv4 address itself it is returned unchanged.  See
218\function{gethostbyname_ex()} for a more complete interface.
219\function{gethostbyname()} does not support IPv6 name resolution, and
220\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
221\end{funcdesc}
222
223\begin{funcdesc}{gethostbyname_ex}{hostname}
224Translate a host name to IPv4 address format, extended interface.
225Return a triple \code{(\var{hostname}, \var{aliaslist},
226\var{ipaddrlist})} where
227\var{hostname} is the primary host name responding to the given
228\var{ip_address}, \var{aliaslist} is a (possibly empty) list of
229alternative host names for the same address, and \var{ipaddrlist} is
230a list of IPv4 addresses for the same interface on the same
231host (often but not always a single address).
232\function{gethostbyname_ex()} does not support IPv6 name resolution, and
233\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
234\end{funcdesc}
235
236\begin{funcdesc}{gethostname}{}
237Return a string containing the hostname of the machine where 
238the Python interpreter is currently executing.
239If you want to know the current machine's IP address, you may want to use
240\code{gethostbyname(gethostname())}.
241This operation assumes that there is a valid address-to-host mapping for
242the host, and the assumption does not always hold.
243Note: \function{gethostname()} doesn't always return the fully qualified
244domain name; use \code{getfqdn()}
245(see above).
246\end{funcdesc}
247
248\begin{funcdesc}{gethostbyaddr}{ip_address}
249Return a triple \code{(\var{hostname}, \var{aliaslist},
250\var{ipaddrlist})} where \var{hostname} is the primary host name
251responding to the given \var{ip_address}, \var{aliaslist} is a
252(possibly empty) list of alternative host names for the same address,
253and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface
254on the same host (most likely containing only a single address).
255To find the fully qualified domain name, use the function
256\function{getfqdn()}.
257\function{gethostbyaddr} supports both IPv4 and IPv6.
258\end{funcdesc}
259
260\begin{funcdesc}{getnameinfo}{sockaddr, flags}
261Translate a socket address \var{sockaddr} into a 2-tuple
262\code{(\var{host}, \var{port})}.
263Depending on the settings of \var{flags}, the result can contain a
264fully-qualified domain name or numeric address representation in
265\var{host}.  Similarly, \var{port} can contain a string port name or a
266numeric port number.
267\versionadded{2.2}
268\end{funcdesc}
269
270\begin{funcdesc}{getprotobyname}{protocolname}
271Translate an Internet protocol name (for example, \code{'icmp'}) to a constant
272suitable for passing as the (optional) third argument to the
273\function{socket()} function.  This is usually only needed for sockets
274opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
275modes, the correct protocol is chosen automatically if the protocol is
276omitted or zero.
277\end{funcdesc}
278
279\begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}}
280Translate an Internet service name and protocol name to a port number
281for that service.  The optional protocol name, if given, should be
282\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
283\end{funcdesc}
284
285\begin{funcdesc}{getservbyport}{port\optional{, protocolname}}
286Translate an Internet port number and protocol name to a service name
287for that service.  The optional protocol name, if given, should be
288\code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
289\end{funcdesc}
290
291\begin{funcdesc}{socket}{\optional{family\optional{,
292                         type\optional{, proto}}}}
293Create a new socket using the given address family, socket type and
294protocol number.  The address family should be \constant{AF_INET} (the
295default), \constant{AF_INET6} or \constant{AF_UNIX}.  The socket type
296should be \constant{SOCK_STREAM} (the default), \constant{SOCK_DGRAM}
297or perhaps one of the other \samp{SOCK_} constants.  The protocol
298number is usually zero and may be omitted in that case.
299\end{funcdesc}
300
301\begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}}
302Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is
303the name of a PEM formatted file that contains your private
304key. \var{certfile} is a PEM formatted certificate chain file. On
305success, a new \class{SSLObject} is returned.
306
307\warning{This does not do any certificate verification!}
308\end{funcdesc}
309
310\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}}
311Build a pair of connected socket objects using the given address
312family, socket type, and protocol number.  Address family, socket type,
313and protocol number are as for the \function{socket()} function above.
314The default family is \constant{AF_UNIX} if defined on the platform;
315otherwise, the default is \constant{AF_INET}.
316Availability: \UNIX.  \versionadded{2.4}
317\end{funcdesc}
318
319\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
320Duplicate the file descriptor \var{fd} (an integer as returned by a file
321object's \method{fileno()} method) and build a socket object from the
322result.  Address family, socket type and protocol number are as for the
323\function{socket()} function above.
324The file descriptor should refer to a socket, but this is not
325checked --- subsequent operations on the object may fail if the file
326descriptor is invalid.  This function is rarely needed, but can be
327used to get or set socket options on a socket passed to a program as
328standard input or output (such as a server started by the \UNIX{} inet
329daemon).  The socket is assumed to be in blocking mode.
330Availability: \UNIX.
331\end{funcdesc}
332
333\begin{funcdesc}{ntohl}{x}
334Convert 32-bit integers from network to host byte order.  On machines
335where the host byte order is the same as network byte order, this is a
336no-op; otherwise, it performs a 4-byte swap operation.
337\end{funcdesc}
338
339\begin{funcdesc}{ntohs}{x}
340Convert 16-bit integers from network to host byte order.  On machines
341where the host byte order is the same as network byte order, this is a
342no-op; otherwise, it performs a 2-byte swap operation.
343\end{funcdesc}
344
345\begin{funcdesc}{htonl}{x}
346Convert 32-bit integers from host to network byte order.  On machines
347where the host byte order is the same as network byte order, this is a
348no-op; otherwise, it performs a 4-byte swap operation.
349\end{funcdesc}
350
351\begin{funcdesc}{htons}{x}
352Convert 16-bit integers from host to network byte order.  On machines
353where the host byte order is the same as network byte order, this is a
354no-op; otherwise, it performs a 2-byte swap operation.
355\end{funcdesc}
356
357\begin{funcdesc}{inet_aton}{ip_string}
358Convert an IPv4 address from dotted-quad string format (for example,
359'123.45.67.89') to 32-bit packed binary format, as a string four
360characters in length.  This is useful when conversing with a program
361that uses the standard C library and needs objects of type
362\ctype{struct in_addr}, which is the C type for the 32-bit packed
363binary this function returns.
364
365If the IPv4 address string passed to this function is invalid,
366\exception{socket.error} will be raised. Note that exactly what is
367valid depends on the underlying C implementation of
368\cfunction{inet_aton()}.
369
370\function{inet_aton()} does not support IPv6, and
371\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
372support.
373\end{funcdesc}
374
375\begin{funcdesc}{inet_ntoa}{packed_ip}
376Convert a 32-bit packed IPv4 address (a string four characters in
377length) to its standard dotted-quad string representation (for
378example, '123.45.67.89').  This is useful when conversing with a
379program that uses the standard C library and needs objects of type
380\ctype{struct in_addr}, which is the C type for the 32-bit packed
381binary data this function takes as an argument.
382
383If the string passed to this function is not exactly 4 bytes in
384length, \exception{socket.error} will be raised.
385\function{inet_ntoa()} does not support IPv6, and
386\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
387support.
388\end{funcdesc}
389
390\begin{funcdesc}{inet_pton}{address_family, ip_string}
391Convert an IP address from its family-specific string format to a packed,
392binary format.
393\function{inet_pton()} is useful when a library or network protocol calls for
394an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
395or \ctype{struct in6_addr}.
396
397Supported values for \var{address_family} are currently
398\constant{AF_INET} and \constant{AF_INET6}.
399If the IP address string \var{ip_string} is invalid,
400\exception{socket.error} will be raised. Note that exactly what is valid
401depends on both the value of \var{address_family} and the underlying
402implementation of \cfunction{inet_pton()}.
403
404Availability: \UNIX{} (maybe not all platforms).
405\versionadded{2.3}
406\end{funcdesc}
407
408\begin{funcdesc}{inet_ntop}{address_family, packed_ip}
409Convert a packed IP address (a string of some number of characters) to
410its standard, family-specific string representation (for example,
411\code{'7.10.0.5'} or \code{'5aef:2b::8'})
412\function{inet_ntop()} is useful when a library or network protocol returns
413an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
414or \ctype{struct in6_addr}.
415
416Supported values for \var{address_family} are currently
417\constant{AF_INET} and \constant{AF_INET6}.
418If the string \var{packed_ip} is not the correct length for the
419specified address family, \exception{ValueError} will be raised.  A
420\exception{socket.error} is raised for errors from the call to
421\function{inet_ntop()}.
422
423Availability: \UNIX{} (maybe not all platforms).
424\versionadded{2.3}
425\end{funcdesc}
426
427\begin{funcdesc}{getdefaulttimeout}{}
428Return the default timeout in floating seconds for new socket objects.
429A value of \code{None} indicates that new socket objects have no timeout.
430When the socket module is first imported, the default is \code{None}.
431\versionadded{2.3}
432\end{funcdesc}
433
434\begin{funcdesc}{setdefaulttimeout}{timeout}
435Set the default timeout in floating seconds for new socket objects.
436A value of \code{None} indicates that new socket objects have no timeout.
437When the socket module is first imported, the default is \code{None}.
438\versionadded{2.3}
439\end{funcdesc}
440
441\begin{datadesc}{SocketType}
442This is a Python type object that represents the socket object type.
443It is the same as \code{type(socket(...))}.
444\end{datadesc}
445
446
447\begin{seealso}
448  \seemodule{SocketServer}{Classes that simplify writing network servers.}
449\end{seealso}
450
451
452\subsection{Socket Objects \label{socket-objects}}
453
454Socket objects have the following methods.  Except for
455\method{makefile()} these correspond to \UNIX{} system calls
456applicable to sockets.
457
458\begin{methoddesc}[socket]{accept}{}
459Accept a connection.
460The socket must be bound to an address and listening for connections.
461The return value is a pair \code{(\var{conn}, \var{address})}
462where \var{conn} is a \emph{new} socket object usable to send and
463receive data on the connection, and \var{address} is the address bound
464to the socket on the other end of the connection.
465\end{methoddesc}
466
467\begin{methoddesc}[socket]{bind}{address}
468Bind the socket to \var{address}.  The socket must not already be bound.
469(The format of \var{address} depends on the address family --- see
470above.)  \note{This method has historically accepted a pair
471of parameters for \constant{AF_INET} addresses instead of only a
472tuple.  This was never intentional and is no longer available in
473Python 2.0 and later.}
474\end{methoddesc}
475
476\begin{methoddesc}[socket]{close}{}
477Close the socket.  All future operations on the socket object will fail.
478The remote end will receive no more data (after queued data is flushed).
479Sockets are automatically closed when they are garbage-collected.
480\end{methoddesc}
481
482\begin{methoddesc}[socket]{connect}{address}
483Connect to a remote socket at \var{address}.
484(The format of \var{address} depends on the address family --- see
485above.)  \note{This method has historically accepted a pair
486of parameters for \constant{AF_INET} addresses instead of only a
487tuple.  This was never intentional and is no longer available in
488Python 2.0 and later.}
489\end{methoddesc}
490
491\begin{methoddesc}[socket]{connect_ex}{address}
492Like \code{connect(\var{address})}, but return an error indicator
493instead of raising an exception for errors returned by the C-level
494\cfunction{connect()} call (other problems, such as ``host not found,''
495can still raise exceptions).  The error indicator is \code{0} if the
496operation succeeded, otherwise the value of the \cdata{errno}
497variable.  This is useful to support, for example, asynchronous connects.
498\note{This method has historically accepted a pair of
499parameters for \constant{AF_INET} addresses instead of only a tuple.
500This was never intentional and is no longer available in Python
5012.0 and later.}
502\end{methoddesc}
503
504\begin{methoddesc}[socket]{fileno}{}
505Return the socket's file descriptor (a small integer).  This is useful
506with \function{select.select()}.
507
508Under Windows the small integer returned by this method cannot be used where
509a file descriptor can be used (such as \function{os.fdopen()}).  \UNIX{} does
510not have this limitation.
511\end{methoddesc}
512
513\begin{methoddesc}[socket]{getpeername}{}
514Return the remote address to which the socket is connected.  This is
515useful to find out the port number of a remote IPv4/v6 socket, for instance.
516(The format of the address returned depends on the address family ---
517see above.)  On some systems this function is not supported.
518\end{methoddesc}
519
520\begin{methoddesc}[socket]{getsockname}{}
521Return the socket's own address.  This is useful to find out the port
522number of an IPv4/v6 socket, for instance.
523(The format of the address returned depends on the address family ---
524see above.)
525\end{methoddesc}
526
527\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}}
528Return the value of the given socket option (see the \UNIX{} man page
529\manpage{getsockopt}{2}).  The needed symbolic constants
530(\constant{SO_*} etc.) are defined in this module.  If \var{buflen}
531is absent, an integer option is assumed and its integer value
532is returned by the function.  If \var{buflen} is present, it specifies
533the maximum length of the buffer used to receive the option in, and
534this buffer is returned as a string.  It is up to the caller to decode
535the contents of the buffer (see the optional built-in module
536\refmodule{struct} for a way to decode C structures encoded as strings).
537\end{methoddesc}
538
539\begin{methoddesc}[socket]{listen}{backlog}
540Listen for connections made to the socket.  The \var{backlog} argument
541specifies the maximum number of queued connections and should be at
542least 1; the maximum value is system-dependent (usually 5).
543\end{methoddesc}
544
545\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}}
546Return a \dfn{file object} associated with the socket.  (File objects
547are described in \ref{bltin-file-objects}, ``File Objects.'')
548The file object references a \cfunction{dup()}ped version of the
549socket file descriptor, so the file object and socket object may be
550closed or garbage-collected independently.
551The socket must be in blocking mode.
552\index{I/O control!buffering}The optional \var{mode}
553and \var{bufsize} arguments are interpreted the same way as by the
554built-in \function{file()} function; see ``Built-in Functions''
555(section \ref{built-in-funcs}) for more information.
556\end{methoddesc}
557
558\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
559Receive data from the socket.  The return value is a string representing
560the data received.  The maximum amount of data to be received
561at once is specified by \var{bufsize}.  See the \UNIX{} manual page
562\manpage{recv}{2} for the meaning of the optional argument
563\var{flags}; it defaults to zero.
564\note{For best match with hardware and network realities, the value of 
565\var{bufsize} should be a relatively small power of 2, for example, 4096.}
566\end{methoddesc}
567
568\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
569Receive data from the socket.  The return value is a pair
570\code{(\var{string}, \var{address})} where \var{string} is a string
571representing the data received and \var{address} is the address of the
572socket sending the data.  The optional \var{flags} argument has the
573same meaning as for \method{recv()} above.
574(The format of \var{address} depends on the address family --- see above.)
575\end{methoddesc}
576
577\begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}}
578Receive data from the socket, writing it into \var{buffer} instead of 
579creating a new string.  The return value is a pair
580\code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number
581of bytes received and \var{address} is the address of the socket
582sending the data.  See the \UNIX{} manual page
583\manpage{recv}{2} for the meaning of the optional argument
584\var{flags}; it defaults to zero.  (The format of \var{address}
585depends on the address family --- see above.)
586\versionadded{2.5}
587\end{methoddesc}
588
589\begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}}
590Receive up to \var{nbytes} bytes from the socket,
591storing the data into a buffer rather than creating a new string.    
592If \var{nbytes} is not specified (or 0), 
593receive up to the size available in the given buffer.
594See the \UNIX{} manual page \manpage{recv}{2} for the meaning of the
595optional argument \var{flags}; it defaults to zero.
596\versionadded{2.5}
597\end{methoddesc}
598
599\begin{methoddesc}[socket]{send}{string\optional{, flags}}
600Send data to the socket.  The socket must be connected to a remote
601socket.  The optional \var{flags} argument has the same meaning as for
602\method{recv()} above.  Returns the number of bytes sent.
603Applications are responsible for checking that all data has been sent;
604if only some of the data was transmitted, the application needs to
605attempt delivery of the remaining data.
606\end{methoddesc}
607
608\begin{methoddesc}[socket]{sendall}{string\optional{, flags}}
609Send data to the socket.  The socket must be connected to a remote
610socket.  The optional \var{flags} argument has the same meaning as for
611\method{recv()} above.  Unlike \method{send()}, this method continues
612to send data from \var{string} until either all data has been sent or
613an error occurs.  \code{None} is returned on success.  On error, an
614exception is raised, and there is no way to determine how much data,
615if any, was successfully sent.
616\end{methoddesc}
617
618\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address}
619Send data to the socket.  The socket should not be connected to a
620remote socket, since the destination socket is specified by
621\var{address}.  The optional \var{flags} argument has the same
622meaning as for \method{recv()} above.  Return the number of bytes sent.
623(The format of \var{address} depends on the address family --- see above.)
624\end{methoddesc}
625
626\begin{methoddesc}[socket]{setblocking}{flag}
627Set blocking or non-blocking mode of the socket: if \var{flag} is 0,
628the socket is set to non-blocking, else to blocking mode.  Initially
629all sockets are in blocking mode.  In non-blocking mode, if a
630\method{recv()} call doesn't find any data, or if a
631\method{send()} call can't immediately dispose of the data, a
632\exception{error} exception is raised; in blocking mode, the calls
633block until they can proceed.
634\code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)};
635\code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}.
636\end{methoddesc}
637
638\begin{methoddesc}[socket]{settimeout}{value}
639Set a timeout on blocking socket operations.  The \var{value} argument
640can be a nonnegative float expressing seconds, or \code{None}.
641If a float is
642given, subsequent socket operations will raise an \exception{timeout}
643exception if the timeout period \var{value} has elapsed before the
644operation has completed.  Setting a timeout of \code{None} disables
645timeouts on socket operations.
646\code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)};
647\code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}.
648\versionadded{2.3}
649\end{methoddesc}
650
651\begin{methoddesc}[socket]{gettimeout}{}
652Return the timeout in floating seconds associated with socket
653operations, or \code{None} if no timeout is set.  This reflects
654the last call to \method{setblocking()} or \method{settimeout()}.
655\versionadded{2.3}
656\end{methoddesc}
657
658Some notes on socket blocking and timeouts: A socket object can be in
659one of three modes: blocking, non-blocking, or timeout.  Sockets are
660always created in blocking mode.  In blocking mode, operations block
661until complete.  In non-blocking mode, operations fail (with an error
662that is unfortunately system-dependent) if they cannot be completed
663immediately.  In timeout mode, operations fail if they cannot be
664completed within the timeout specified for the socket.  The
665\method{setblocking()} method is simply a shorthand for certain
666\method{settimeout()} calls.
667
668Timeout mode internally sets the socket in non-blocking mode.  The
669blocking and timeout modes are shared between file descriptors and
670socket objects that refer to the same network endpoint.  A consequence
671of this is that file objects returned by the \method{makefile()}
672method must only be used when the socket is in blocking mode; in
673timeout or non-blocking mode file operations that cannot be completed
674immediately will fail.
675
676Note that the \method{connect()} operation is subject to the timeout
677setting, and in general it is recommended to call
678\method{settimeout()} before calling \method{connect()}.
679
680\begin{methoddesc}[socket]{setsockopt}{level, optname, value}
681Set the value of the given socket option (see the \UNIX{} manual page
682\manpage{setsockopt}{2}).  The needed symbolic constants are defined in
683the \module{socket} module (\constant{SO_*} etc.).  The value can be an
684integer or a string representing a buffer.  In the latter case it is
685up to the caller to ensure that the string contains the proper bits
686(see the optional built-in module
687\refmodule{struct}\refbimodindex{struct} for a way to encode C
688structures as strings). 
689\end{methoddesc}
690
691\begin{methoddesc}[socket]{shutdown}{how}
692Shut down one or both halves of the connection.  If \var{how} is
693\constant{SHUT_RD}, further receives are disallowed.  If \var{how} is \constant{SHUT_WR},
694further sends are disallowed.  If \var{how} is \constant{SHUT_RDWR}, further sends
695and receives are disallowed.
696\end{methoddesc}
697
698Note that there are no methods \method{read()} or \method{write()};
699use \method{recv()} and \method{send()} without \var{flags} argument
700instead.
701
702
703Socket objects also have these (read-only) attributes that correspond
704to the values given to the \class{socket} constructor.
705
706\begin{memberdesc}[socket]{family}
707The socket family.
708\versionadded{2.5}
709\end{memberdesc}
710
711\begin{memberdesc}[socket]{type}
712The socket type.
713\versionadded{2.5}
714\end{memberdesc}
715
716\begin{memberdesc}[socket]{proto}
717The socket protocol.
718\versionadded{2.5}
719\end{memberdesc}
720
721
722\subsection{SSL Objects \label{ssl-objects}}
723
724SSL objects have the following methods.
725
726\begin{methoddesc}{write}{s}
727Writes the string \var{s} to the on the object's SSL connection.
728The return value is the number of bytes written.
729\end{methoddesc}
730
731\begin{methoddesc}{read}{\optional{n}}
732If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise
733read until EOF. The return value is a string of the bytes read.
734\end{methoddesc}
735
736\begin{methoddesc}{server}{}
737Returns a string describing the server's certificate.
738Useful for debugging purposes; do not parse the content of this string
739because its format can't be parsed unambiguously.
740\end{methoddesc}
741
742\begin{methoddesc}{issuer}{}
743Returns a string describing the issuer of the server's certificate.
744Useful for debugging purposes; do not parse the content of this string
745because its format can't be parsed unambiguously.
746\end{methoddesc}
747
748\subsection{Example \label{socket-example}}
749
750Here are four minimal example programs using the TCP/IP protocol:\ a
751server that echoes all data that it receives back (servicing only one
752client), and a client using it.  Note that a server must perform the
753sequence \function{socket()}, \method{bind()}, \method{listen()},
754\method{accept()} (possibly repeating the \method{accept()} to service
755more than one client), while a client only needs the sequence
756\function{socket()}, \method{connect()}.  Also note that the server
757does not \method{send()}/\method{recv()} on the 
758socket it is listening on but on the new socket returned by
759\method{accept()}.
760
761The first two examples support IPv4 only.
762
763\begin{verbatim}
764# Echo server program
765import socket
766
767HOST = ''                 # Symbolic name meaning the local host
768PORT = 50007              # Arbitrary non-privileged port
769s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
770s.bind((HOST, PORT))
771s.listen(1)
772conn, addr = s.accept()
773print 'Connected by', addr
774while 1:
775    data = conn.recv(1024)
776    if not data: break
777    conn.send(data)
778conn.close()
779\end{verbatim}
780
781\begin{verbatim}
782# Echo client program
783import socket
784
785HOST = 'daring.cwi.nl'    # The remote host
786PORT = 50007              # The same port as used by the server
787s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
788s.connect((HOST, PORT))
789s.send('Hello, world')
790data = s.recv(1024)
791s.close()
792print 'Received', repr(data)
793\end{verbatim}
794
795The next two examples are identical to the above two, but support both
796IPv4 and IPv6.
797The server side will listen to the first address family available
798(it should listen to both instead).
799On most of IPv6-ready systems, IPv6 will take precedence
800and the server may not accept IPv4 traffic.
801The client side will try to connect to the all addresses returned as a result
802of the name resolution, and sends traffic to the first one connected
803successfully.
804
805\begin{verbatim}
806# Echo server program
807import socket
808import sys
809
810HOST = ''                 # Symbolic name meaning the local host
811PORT = 50007              # Arbitrary non-privileged port
812s = None
813for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
814    af, socktype, proto, canonname, sa = res
815    try:
816	s = socket.socket(af, socktype, proto)
817    except socket.error, msg:
818	s = None
819	continue
820    try:
821	s.bind(sa)
822	s.listen(1)
823    except socket.error, msg:
824	s.close()
825	s = None
826	continue
827    break
828if s is None:
829    print 'could not open socket'
830    sys.exit(1)
831conn, addr = s.accept()
832print 'Connected by', addr
833while 1:
834    data = conn.recv(1024)
835    if not data: break
836    conn.send(data)
837conn.close()
838\end{verbatim}
839
840\begin{verbatim}
841# Echo client program
842import socket
843import sys
844
845HOST = 'daring.cwi.nl'    # The remote host
846PORT = 50007              # The same port as used by the server
847s = None
848for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
849    af, socktype, proto, canonname, sa = res
850    try:
851	s = socket.socket(af, socktype, proto)
852    except socket.error, msg:
853	s = None
854	continue
855    try:
856	s.connect(sa)
857    except socket.error, msg:
858	s.close()
859	s = None
860	continue
861    break
862if s is None:
863    print 'could not open socket'
864    sys.exit(1)
865s.send('Hello, world')
866data = s.recv(1024)
867s.close()
868print 'Received', repr(data)
869\end{verbatim}
870
871This example connects to an SSL server, prints the 
872server and issuer's distinguished names, sends some bytes,
873and reads part of the response:
874
875\begin{verbatim}
876import socket
877
878s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
879s.connect(('www.verisign.com', 443))
880
881ssl_sock = socket.ssl(s)
882
883print repr(ssl_sock.server())
884print repr(ssl_sock.issuer())
885
886# Set a simple HTTP request -- use httplib in actual code.
887ssl_sock.write("""GET / HTTP/1.0\r
888Host: www.verisign.com\r\n\r\n""")
889
890# Read a chunk of data.  Will not necessarily
891# read all the data returned by the server.
892data = ssl_sock.read()
893
894# Note that you need to close the underlying socket, not the SSL object.
895del ssl_sock
896s.close()
897\end{verbatim}
898
899At this writing, this SSL example prints the following output (line
900breaks inserted for readability):
901
902\begin{verbatim}
903'/C=US/ST=California/L=Mountain View/
904 O=VeriSign, Inc./OU=Production Services/
905 OU=Terms of use at www.verisign.com/rpa (c)00/
906 CN=www.verisign.com'
907'/O=VeriSign Trust Network/OU=VeriSign, Inc./
908 OU=VeriSign International Server CA - Class 3/
909 OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign'
910\end{verbatim}