[Python-checkins] python/dist/src/Doc/lib libsocket.tex,1.72,1.73
fdrake@users.sourceforge.net
fdrake@users.sourceforge.net
Fri, 25 Apr 2003 09:16:06 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv19504
Modified Files:
libsocket.tex
Log Message:
- add availability statements for some of the new APIs
- lots of general cleanup
Index: libsocket.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsocket.tex,v
retrieving revision 1.72
retrieving revision 1.73
diff -C2 -d -r1.72 -r1.73
*** libsocket.tex 25 Apr 2003 15:26:58 -0000 1.72
--- libsocket.tex 25 Apr 2003 16:16:02 -0000 1.73
***************
*** 157,167 ****
\end{datadesc}
! \begin{funcdesc}{getaddrinfo}{host, port\optional{, family, socktype, proto, 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
port number or \code{None}.
--- 157,168 ----
\end{datadesc}
! \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
port number or \code{None}.
***************
*** 172,184 ****
the following structure:
! \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
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
for a typical usage of the function.
\versionadded{2.2}
--- 173,186 ----
the following structure:
! \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 \constant{AI_CANONNAME} is specified
for a numeric \var{host}.
\var{sockaddr} is a tuple describing a socket address, as described above.
! See the source for the \refmodule{httplib} and other library modules
for a typical usage of the function.
\versionadded{2.2}
***************
*** 207,214 ****
\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
a list of IPv4 addresses for the same interface on the same
host (often but not always a single address).
--- 209,217 ----
\begin{funcdesc}{gethostbyname_ex}{hostname}
Translate a host name to IPv4 address format, extended interface.
! 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).
***************
*** 323,331 ****
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.
If the IPv4 address string passed to this function is invalid,
--- 326,333 ----
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. 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,
***************
*** 341,354 ****
\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.
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
--- 343,354 ----
\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'). 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
***************
*** 359,393 ****
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,
\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()}.
\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}.
!
\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
\function{inet_ntop()}.
\versionadded{2.3}
\end{funcdesc}
--- 359,393 ----
Convert an IP address from its family-specific string format to a packed,
binary format.
\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}.
! 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,
! \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}.
! 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}
***************
*** 617,621 ****
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
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
--- 617,621 ----
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 (\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