- add availability statements for some of the new APIs
- lots of general cleanup
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex
index 05e3c88..6de839a 100644
--- a/Doc/lib/libsocket.tex
+++ b/Doc/lib/libsocket.tex
@@ -156,13 +156,14 @@
\versionadded{2.3}
\end{datadesc}
-\begin{funcdesc}{getaddrinfo}{host, port\optional{, family, socktype, proto, flags}}
-
+\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{,
+ socktype\optional{, proto\optional{,
+ flags}}}}}
Resolves the \var{host}/\var{port} argument, into a sequence of
5-tuples that contain all the necessary argument for the sockets
manipulation. \var{host} is a domain name, a string representation of
IPv4/v6 address or \code{None}.
-\var{port} is a string service name (like \code{``http''}), a numeric
+\var{port} is a string service name (like \code{'http'}), a numeric
port number or \code{None}.
The rest of the arguments are optional and must be numeric if
@@ -171,15 +172,16 @@
\function{getaddrinfo()} function returns a list of 5-tuples with
the following structure:
-\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, \var{sockaddr})}.
+\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
+ \var{sockaddr})}
\var{family}, \var{socktype}, \var{proto} are all integer and are meant to
be passed to the \function{socket()} function.
\var{canonname} is a string representing the canonical name of the \var{host}.
-It can be a numeric IPv4/v6 address when \code{AI_CANONNAME} is specified
+It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified
for a numeric \var{host}.
\var{sockaddr} is a tuple describing a socket address, as described above.
-See \code{Lib/httplib.py} and other library files
+See the source for the \refmodule{httplib} and other library modules
for a typical usage of the function.
\versionadded{2.2}
\end{funcdesc}
@@ -206,10 +208,11 @@
\begin{funcdesc}{gethostbyname_ex}{hostname}
Translate a host name to IPv4 address format, extended interface.
-Return a triple \code{(hostname, aliaslist, ipaddrlist)} where
-\code{hostname} is the primary host name responding to the given
-\var{ip_address}, \code{aliaslist} is a (possibly empty) list of
-alternative host names for the same address, and \code{ipaddrlist} is
+Return a triple \code{(\var{hostname}, \var{aliaslist},
+\var{ipaddrlist})} where
+\var{hostname} is the primary host name responding to the given
+\var{ip_address}, \var{aliaslist} is a (possibly empty) list of
+alternative host names for the same address, and \var{ipaddrlist} is
a list of IPv4 addresses for the same interface on the same
host (often but not always a single address).
\function{gethostbyname_ex()} does not support IPv6 name resolution, and
@@ -322,11 +325,10 @@
\begin{funcdesc}{inet_aton}{ip_string}
Convert an IPv4 address from dotted-quad string format (for example,
'123.45.67.89') to 32-bit packed binary format, as a string four
-characters in length.
-
-Useful when conversing with a program that uses the standard C library
-and needs objects of type \ctype{struct in_addr}, which is the C type
-for the 32-bit packed binary this function returns.
+characters in length. This is useful when conversing with a program
+that uses the standard C library and needs objects of type
+\ctype{struct in_addr}, which is the C type for the 32-bit packed
+binary this function returns.
If the IPv4 address string passed to this function is invalid,
\exception{socket.error} will be raised. Note that exactly what is
@@ -340,16 +342,14 @@
\begin{funcdesc}{inet_ntoa}{packed_ip}
Convert a 32-bit packed IPv4 address (a string four characters in
-length) to its standard dotted-quad string representation
-(for example, '123.45.67.89').
-
-Useful when conversing with a program that uses the standard C library
-and needs objects of type \ctype{struct in_addr}, which is the C type
-for the 32-bit packed binary this function takes as an argument.
+length) to its standard dotted-quad string representation (for
+example, '123.45.67.89'). This is useful when conversing with a
+program that uses the standard C library and needs objects of type
+\ctype{struct in_addr}, which is the C type for the 32-bit packed
+binary data this function takes as an argument.
If the string passed to this function is not exactly 4 bytes in
length, \exception{socket.error} will be raised.
-
\function{inet_ntoa()} does not support IPv6, and
\function{getnameinfo()} should be used instead for IPv4/v6 dual stack
support.
@@ -358,37 +358,37 @@
\begin{funcdesc}{inet_pton}{address_family, ip_string}
Convert an IP address from its family-specific string format to a packed,
binary format.
-
-Supported values for address_family are currently \constant{AF_INET}
-and \constant{AF_INET6}.
-
\function{inet_pton()} is useful when a library or network protocol calls for
an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
or \ctype{struct in6_addr}.
-If the IP address string passed to this function is invalid,
+Supported values for \var{address_family} are currently
+\constant{AF_INET} and \constant{AF_INET6}.
+If the IP address string \var{ip_string} is invalid,
\exception{socket.error} will be raised. Note that exactly what is valid
depends on both the value of \var{address_family} and the underlying
implementation of \cfunction{inet_pton()}.
+
+Availability: \UNIX{} (maybe not all platforms).
\versionadded{2.3}
\end{funcdesc}
\begin{funcdesc}{inet_ntop}{address_family, packed_ip}
-Convert a packed IP address (a string of some number of characters) to its
-standard, family-specific string representation (for example, '7.10.0.5' or
-'5aef:2b::8')
-
-Supported values for address_family are currently \constant{AF_INET}
-and \constant{AF_INET6}.
-
+Convert a packed IP address (a string of some number of characters) to
+its standard, family-specific string representation (for example,
+\code{'7.10.0.5'} or \code{'5aef:2b::8'})
\function{inet_ntop()} is useful when a library or network protocol returns
an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
or \ctype{struct in6_addr}.
-If the string passed to this function is not the correct length for the
-specified address family, \exception{ValueError} will be raised.
-A \exception{socket.error} is raised for errors from the call to
+Supported values for \var{address_family} are currently
+\constant{AF_INET} and \constant{AF_INET6}.
+If the string \var{packed_ip} is not the correct length for the
+specified address family, \exception{ValueError} will be raised. A
+\exception{socket.error} is raised for errors from the call to
\function{inet_ntop()}.
+
+Availability: \UNIX{} (maybe not all platforms).
\versionadded{2.3}
\end{funcdesc}
@@ -616,7 +616,7 @@
\begin{methoddesc}[socket]{setsockopt}{level, optname, value}
Set the value of the given socket option (see the \UNIX{} manual page
\manpage{setsockopt}{2}). The needed symbolic constants are defined in
-the \module{socket} module (\code{SO_*} etc.). The value can be an
+the \module{socket} module (\constant{SO_*} etc.). The value can be an
integer or a string representing a buffer. In the latter case it is
up to the caller to ensure that the string contains the proper bits
(see the optional built-in module