Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

- add availability statements for some of the new APIs 

- lots of general cleanup
This commit is contained in:
Fred Drake 2003-04-25 16:16:02 +00:00
parent 5ba0054e69
commit d198f38505
1 changed files with 38 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
Doc/lib/libsocket.tex
View File

@ -156,13 +156,14 @@ supported on this platform.
\versionadded{2.3} \versionadded{2.3}
\end{datadesc} \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 Resolves the \var{host}/\var{port} argument, into a sequence of
5-tuples that contain all the necessary argument for the sockets 5-tuples that contain all the necessary argument for the sockets
manipulation. \var{host} is a domain name, a string representation of manipulation. \var{host} is a domain name, a string representation of
IPv4/v6 address or \code{None}. 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}. port number or \code{None}.
The rest of the arguments are optional and must be numeric if The rest of the arguments are optional and must be numeric if
@ -171,15 +172,16 @@ string or \code{None}, you can pass \code{NULL} to the C API. The
\function{getaddrinfo()} function returns a list of 5-tuples with \function{getaddrinfo()} function returns a list of 5-tuples with
the following structure: 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 \var{family}, \var{socktype}, \var{proto} are all integer and are meant to
be passed to the \function{socket()} function. be passed to the \function{socket()} function.
\var{canonname} is a string representing the canonical name of the \var{host}. \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}. for a numeric \var{host}.
\var{sockaddr} is a tuple describing a socket address, as described above. \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. for a typical usage of the function.
\versionadded{2.2} \versionadded{2.2}
\end{funcdesc} \end{funcdesc}
@ -206,10 +208,11 @@ is an IPv4 address itself it is returned unchanged. See
\begin{funcdesc}{gethostbyname_ex}{hostname} \begin{funcdesc}{gethostbyname_ex}{hostname}
Translate a host name to IPv4 address format, extended interface. Translate a host name to IPv4 address format, extended interface.
Return a triple \code{(hostname, aliaslist, ipaddrlist)} where Return a triple \code{(\var{hostname}, \var{aliaslist},
\code{hostname} is the primary host name responding to the given \var{ipaddrlist})} where
\var{ip_address}, \code{aliaslist} is a (possibly empty) list of \var{hostname} is the primary host name responding to the given
alternative host names for the same address, and \code{ipaddrlist} is \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 a list of IPv4 addresses for the same interface on the same
host (often but not always a single address). host (often but not always a single address).
\function{gethostbyname_ex()} does not support IPv6 name resolution, and \function{gethostbyname_ex()} does not support IPv6 name resolution, and
@ -322,11 +325,10 @@ no-op; otherwise, it performs a 2-byte swap operation.
\begin{funcdesc}{inet_aton}{ip_string} \begin{funcdesc}{inet_aton}{ip_string}
Convert an IPv4 address from dotted-quad string format (for example, 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 '123.45.67.89') to 32-bit packed binary format, as a string four
characters in length. characters in length. This is useful when conversing with a program
that uses the standard C library and needs objects of type
Useful when conversing with a program that uses the standard C library \ctype{struct in_addr}, which is the C type for the 32-bit packed
and needs objects of type \ctype{struct in_addr}, which is the C type binary this function returns.
for the 32-bit packed binary this function returns.
If the IPv4 address string passed to this function is invalid, If the IPv4 address string passed to this function is invalid,
\exception{socket.error} will be raised. Note that exactly what is \exception{socket.error} will be raised. Note that exactly what is
@ -340,16 +342,14 @@ support.
\begin{funcdesc}{inet_ntoa}{packed_ip} \begin{funcdesc}{inet_ntoa}{packed_ip}
Convert a 32-bit packed IPv4 address (a string four characters in Convert a 32-bit packed IPv4 address (a string four characters in
length) to its standard dotted-quad string representation length) to its standard dotted-quad string representation (for
(for example, '123.45.67.89'). example, '123.45.67.89'). This is useful when conversing with a
program that uses the standard C library and needs objects of type
Useful when conversing with a program that uses the standard C library \ctype{struct in_addr}, which is the C type for the 32-bit packed
and needs objects of type \ctype{struct in_addr}, which is the C type binary data this function takes as an argument.
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 If the string passed to this function is not exactly 4 bytes in
length, \exception{socket.error} will be raised. length, \exception{socket.error} will be raised.
\function{inet_ntoa()} does not support IPv6, and \function{inet_ntoa()} does not support IPv6, and
\function{getnameinfo()} should be used instead for IPv4/v6 dual stack \function{getnameinfo()} should be used instead for IPv4/v6 dual stack
support. support.
@ -358,37 +358,37 @@ support.
\begin{funcdesc}{inet_pton}{address_family, ip_string} \begin{funcdesc}{inet_pton}{address_family, ip_string}
Convert an IP address from its family-specific string format to a packed, Convert an IP address from its family-specific string format to a packed,
binary format. 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 \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()}) an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
or \ctype{struct in6_addr}. 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 \exception{socket.error} will be raised. Note that exactly what is valid
depends on both the value of \var{address_family} and the underlying depends on both the value of \var{address_family} and the underlying
implementation of \cfunction{inet_pton()}. implementation of \cfunction{inet_pton()}.
Availability: \UNIX{} (maybe not all platforms).
\versionadded{2.3} \versionadded{2.3}
\end{funcdesc} \end{funcdesc}
\begin{funcdesc}{inet_ntop}{address_family, packed_ip} \begin{funcdesc}{inet_ntop}{address_family, packed_ip}
Convert a packed IP address (a string of some number of characters) to its Convert a packed IP address (a string of some number of characters) to
standard, family-specific string representation (for example, '7.10.0.5' or its standard, family-specific string representation (for example,
'5aef:2b::8') \code{'7.10.0.5'} or \code{'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 \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()}) an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
or \ctype{struct in6_addr}. or \ctype{struct in6_addr}.
If the string passed to this function is not the correct length for the Supported values for \var{address_family} are currently
specified address family, \exception{ValueError} will be raised. \constant{AF_INET} and \constant{AF_INET6}.
A \exception{socket.error} is raised for errors from the call to 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()}. \function{inet_ntop()}.
Availability: \UNIX{} (maybe not all platforms).
\versionadded{2.3} \versionadded{2.3}
\end{funcdesc} \end{funcdesc}
@ -616,7 +616,7 @@ immediately will fail.
\begin{methoddesc}[socket]{setsockopt}{level, optname, value} \begin{methoddesc}[socket]{setsockopt}{level, optname, value}
Set the value of the given socket option (see the \UNIX{} manual page Set the value of the given socket option (see the \UNIX{} manual page
\manpage{setsockopt}{2}). The needed symbolic constants are defined in \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 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 up to the caller to ensure that the string contains the proper bits
(see the optional built-in module (see the optional built-in module