PageRenderTime 8ms CodeModel.GetById 5ms app.highlight 6ms RepoModel.GetById 3ms app.codeStats 1ms

/html/_sources/library/socket.txt

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