Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[3.12] gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance (GH-126182) #126824

Merged
merged 1 commit into from
Nov 15, 2024
+32 −3
Merged

[3.12] gh-123832: Adjust socket.getaddrinfo docs for better POSIX compliance (GH-126182) #126824

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 32 additions & 3 deletions Doc/library/socket.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -915,7 +915,9 @@

.. versionadded:: 3.7

.. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
.. function:: getaddrinfo(host, port, family=AF_UNSPEC, type=0, proto=0, flags=0)

This function wraps the C function ``getaddrinfo`` of the underlying system.

Translate the *host*/*port* argument into a sequence of 5-tuples that contain
all the necessary arguments for creating a socket connected to that service.
Expand All @@ -925,9 +927,11 @@
and *port*, you can pass ``NULL`` to the underlying C API.

The *family*, *type* and *proto* arguments can be optionally specified
in order to narrow the list of addresses returned. Passing zero as a
value for each of these arguments selects the full range of results.
in order to provide options and limit the list of addresses returned.
Pass their default values (:data:`AF_UNSPEC`, 0, and 0, respectively)
to not limit the results. See the note below for details.

The *flags* argument can be one or several of the ``AI_*`` constants,

Check warning on line 934 in Doc/library/socket.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:const reference target not found: AI_NUMERICHOST [ref.const]
and will influence how results are computed and returned.
For example, :const:`AI_NUMERICHOST` will disable domain name resolution
and will raise an error if *host* is a domain name.
Expand All @@ -946,6 +950,29 @@
:const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
method.

.. note::

If you intend to use results from :func:`!getaddrinfo` to create a socket

Check warning on line 955 in Doc/library/socket.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:data reference target not found: IPPROTO_TCP [ref.data]

Check warning on line 955 in Doc/library/socket.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:data reference target not found: IPPROTO_UDP [ref.data]
(rather than, for example, retrieve *canonname*),
consider limiting the results by *type* (e.g. :data:`SOCK_STREAM` or
:data:`SOCK_DGRAM`) and/or *proto* (e.g. :data:`IPPROTO_TCP` or
:data:`IPPROTO_UDP`) that your application can handle.

The behavior with default values of *family*, *type*, *proto*
and *flags* is system-specific.

Many systems (for example, most Linux configurations) will return a sorted
list of all matching addresses.
These addresses should generally be tried in order until a connection succeeds
(possibly tried in parallel, for example, using a `Happy Eyeballs`_ algorithm).
In these cases, limiting the *type* and/or *proto* can help eliminate
unsuccessful or unusable connecton attempts.

Some systems will, however, only return a single address.
(For example, this was reported on Solaris and AIX configurations.)
On these systems, limiting the *type* and/or *proto* helps ensure that
this address is usable.

.. audit-event:: socket.getaddrinfo host,port,family,type,protocol socket.getaddrinfo

The following example fetches address information for a hypothetical TCP
Expand All @@ -965,6 +992,8 @@
for IPv6 multicast addresses, string representing an address will not
contain ``%scope_id`` part.

.. _Happy Eyeballs: https://en.wikipedia.org/wiki/Happy_Eyeballs

.. function:: getfqdn([name])

Return a fully qualified domain name for *name*. If *name* is omitted or empty,
Expand Down
Loading