204
205
:func:`getdefaulttimeout` is used.
207
.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
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.
216
The :func:`getaddrinfo` function returns a list of 5-tuples with the following
208
.. function:: getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0)
210
Translate the *host*/*port* argument into a sequence of 5-tuples that contain
211
all the necessary arguments for creating a socket connected to that service.
212
*host* is a domain name, a string representation of an IPv4/v6 address
213
or ``None``. *port* is a string service name such as ``'http'``, a numeric
214
port number or ``None``. By passing ``None`` as the value of *host*
215
and *port*, you can pass ``NULL`` to the underlying C API.
217
The *family*, *socktype* and *proto* arguments can be optionally specified
218
in order to narrow the list of addresses returned. Passing zero as a
219
value for each of these arguments selects the full range of results.
220
The *flags* argument can be one or several of the ``AI_*`` constants,
221
and will influence how results are computed and returned.
222
For example, :const:`AI_NUMERICHOST` will disable domain name resolution
223
and will raise an error if *host* is a domain name.
225
The function returns a list of 5-tuples with the following structure:
219
227
``(family, socktype, proto, canonname, sockaddr)``
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.
229
In these tuples, *family*, *socktype*, *proto* are all integers and are
230
meant to be passed to the :func:`socket` function. *canonname* will be
231
a string representing the canonical name of the *host* if
232
:const:`AI_CANONNAME` is part of the *flags* argument; else *canonname*
233
will be empty. *sockaddr* is a tuple describing a socket address, whose
234
format depends on the returned *family* (a ``(address, port)`` 2-tuple for
235
:const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
236
:const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
239
The following example fetches address information for a hypothetical TCP
240
connection to ``www.python.org`` on port 80 (results may differ on your
241
system if IPv6 isn't enabled)::
243
>>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP)
244
[(2, 1, 6, '', ('82.94.164.162', 80)),
245
(10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
229
247
.. function:: getfqdn([name])
685
705
non-blocking mode, operations fail (with an error that is unfortunately
686
706
system-dependent) if they cannot be completed immediately. In timeout mode,
687
707
operations fail if they cannot be completed within the timeout specified for the
688
socket or if the system returns an error. The :meth:`setblocking` method is simply
689
a shorthand for certain :meth:`settimeout` calls.
708
socket or if the system returns an error. The :meth:`~socket.setblocking`
709
method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
691
711
Timeout mode internally sets the socket in non-blocking mode. The blocking and
692
712
timeout modes are shared between file descriptors and socket objects that refer
693
713
to the same network endpoint. A consequence of this is that file objects
694
returned by the :meth:`makefile` method must only be used when the socket is in
695
blocking mode; in timeout or non-blocking mode file operations that cannot be
696
completed immediately will fail.
714
returned by the :meth:`~socket.makefile` method must only be used when the
715
socket is in blocking mode; in timeout or non-blocking mode file operations
716
that cannot be completed immediately will fail.
698
Note that the :meth:`connect` operation is subject to the timeout setting, and
699
in general it is recommended to call :meth:`settimeout` before calling
700
:meth:`connect` or pass a timeout parameter to :meth:`create_connection`.
701
The system network stack may return a connection timeout error
702
of its own regardless of any Python socket timeout setting.
718
Note that the :meth:`~socket.connect` operation is subject to the timeout
719
setting, and in general it is recommended to call :meth:`~socket.settimeout`
720
before calling :meth:`~socket.connect` or pass a timeout parameter to
721
:meth:`create_connection`. The system network stack may return a connection
722
timeout error of its own regardless of any Python socket timeout setting.
705
725
.. method:: socket.setsockopt(level, optname, value)
751
771
Here are four minimal example programs using the TCP/IP protocol: a server that
752
772
echoes all data that it receives back (servicing only one client), and a client
753
773
using it. Note that a server must perform the sequence :func:`socket`,
754
:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
755
:meth:`accept` to service more than one client), while a client only needs the
756
sequence :func:`socket`, :meth:`connect`. Also note that the server does not
757
:meth:`send`/:meth:`recv` on the socket it is listening on but on the new
758
socket returned by :meth:`accept`.
774
:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
775
repeating the :meth:`~socket.accept` to service more than one client), while a
776
client only needs the sequence :func:`socket`, :meth:`~socket.connect`. Also
777
note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the
778
socket it is listening on but on the new socket returned by
779
:meth:`~socket.accept`.
760
781
The first two examples support IPv4 only. ::
added
removed
Doc/library/socket.rst
