PageRenderTime 33ms CodeModel.GetById 3ms app.highlight 22ms RepoModel.GetById 1ms app.codeStats 0ms

/Doc/library/socket.rst

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