[Python-checkins] CVS: python/dist/src/Doc/lib libftplib.tex,1.32,1.33 libsocket.tex,1.51,1.52
Martin v. L?wis
loewis@users.sourceforge.net
2001年8月04日 15:22:47 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv25684
Modified Files:
libftplib.tex libsocket.tex
Log Message:
Document IPv6 changes. Contributed by itojun.
Index: libftplib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libftplib.tex,v
retrieving revision 1.32
retrieving revision 1.33
diff -C2 -d -r1.32 -r1.33
*** libftplib.tex 2001年07月06日 19:28:48 1.32
--- libftplib.tex 2001年08月04日 22:22:45 1.33
***************
*** 192,198 ****
\begin{methoddesc}{transfercmd}{cmd\optional{, rest}}
Initiate a transfer over the data connection. If the transfer is
! active, send a \samp{PORT} command and the transfer command specified
by \var{cmd}, and accept the connection. If the server is passive,
! send a \samp{PASV} command, connect to it, and start the transfer
command. Either way, return the socket for the connection.
--- 192,198 ----
\begin{methoddesc}{transfercmd}{cmd\optional{, rest}}
Initiate a transfer over the data connection. If the transfer is
! active, send a \samp{EPRT} or \samp{PORT} command and the transfer command specified
by \var{cmd}, and accept the connection. If the server is passive,
! send a \samp{EPSV} or \samp{PASV} command, connect to it, and start the transfer
command. Either way, return the socket for the connection.
Index: libsocket.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libsocket.tex,v
retrieving revision 1.51
retrieving revision 1.52
diff -C2 -d -r1.51 -r1.52
*** libsocket.tex 2001年01月10日 19:34:52 1.51
--- libsocket.tex 2001年08月04日 22:22:45 1.52
***************
*** 20,23 ****
--- 20,25 ----
to the manual pages; for Windows, see the WinSock (or Winsock 2)
specification.
+ For IPv6-ready APIs, readers may want to refer to RFC2553 titled
+ \cite{Basic Socket Interface Extensions for IPv6}.
The Python interface is a straightforward transliteration of the
***************
*** 31,48 ****
operations.
! Socket addresses are represented as a single string for the
! \constant{AF_UNIX} address family and as a pair
! \code{(\var{host}, \var{port})} for the \constant{AF_INET} address
! family, where \var{host} is a string representing
! either a hostname in Internet domain notation like
! \code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'},
! and \var{port} is an integral port number. Other address families are
! currently not supported. The address format required by a particular
! socket object is automatically selected based on the address family
! specified when the socket object was created.
! For IP addresses, two special forms are accepted instead of a host
address: the empty string represents \constant{INADDR_ANY}, and the string
\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
All errors raise exceptions. The normal exceptions for invalid
--- 33,70 ----
operations.
! Socket addresses are represented as follows:
! A single string is used for the \constant{AF_UNIX} address family.
! A pair \code{(\var{host}, \var{port})} is used for the
! \constant{AF_INET} address family, where \var{host} is a string
! representing either a hostname in Internet domain notation like
! \code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'},
! and \var{port} is an integral port number.
! For \constant{AF_INET6} address family, a four-tuple
! \code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is
! used, where \var{flowinfo} and \var{scopeid} represents
! \code{sin6_flowinfo} and \code{sin6_scope_id} member in
! \constant{struct sockaddr_in6} in C.
! For \module{socket} module methods, \var{flowinfo} and \var{scopeid}
! can be omitted just for backward compatibility. Note, however,
! omission of \var{scopeid} can cause problems in manipulating scoped
! IPv6 addresses. Other address families are currently not supported.
! The address format required by a particular socket object is
! automatically selected based on the address family specified when the
! socket object was created.
! For IPv4 addresses, two special forms are accepted instead of a host
address: the empty string represents \constant{INADDR_ANY}, and the string
\code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
+ The behavior is not available for IPv6 for backward compatibility,
+ therefore, you may want to avoid these if you intend to support IPv6 with
+ your Python programs.
+
+ If you use a hostname in the \var{host} portion of IPv4/v6 socket
+ address, the program may show a nondeterministic behavior, as Python
+ uses the first address returned from the DNS resolution. The socket
+ address will be resolved differently into an actual IPv4/v6 address,
+ depending on the results from DNS resolution and/or the host
+ configuration. For deterministic behavior use a numeric address in
+ \var{host} portion.
All errors raise exceptions. The normal exceptions for invalid
***************
*** 58,62 ****
\begin{excdesc}{error}
! This exception is raised for socket- or address-related errors.
The accompanying value is either a string telling what went wrong or a
pair \code{(\var{errno}, \var{string})}
--- 80,84 ----
\begin{excdesc}{error}
! This exception is raised for socket-related errors.
The accompanying value is either a string telling what went wrong or a
pair \code{(\var{errno}, \var{string})}
***************
*** 67,72 ****
--- 89,115 ----
\end{excdesc}
+ \begin{excdesc}{herror}
+ This exception is raised for address-related errors, i.e. for
+ functions that use \var{h_errno} in C API, including
+ \function{gethostbyname_ex} and \function{gethostbyaddr}.
+
+ The accompanying value is a pair \code{(\var{h_errno}, \var{string})}
+ representing an error returned by a library call. \var{string}
+ represents the description of \var{h_errno}, as returned by
+ \cfunction{hstrerror} C API.
+ \end{excdesc}
+
+ \begin{excdesc}{gaierror}
+ This exception is raised for address-related errors, for
+ \function{getaddrinfo} and \function{getnameinfo}.
+ The accompanying value is a pair \code{(\var{error}, \var{string})}
+ representing an error returned by a library call.
+ \var{string} represents the description of \var{error}, as returned
+ by \cfunction{gai_strerror} C API.
+ \end{excdesc}
+
\begin{datadesc}{AF_UNIX}
\dataline{AF_INET}
+ \dataline{AF_INET6}
These constants represent the address (and protocol) families,
used for the first argument to \function{socket()}. If the
***************
*** 94,97 ****
--- 137,144 ----
\dataline{INADDR_*}
\dataline{IP_*}
+ \dataline{IPV6_*}
+ \dataline{EAI_*}
+ \dataline{AI_*}
+ \dataline{NI_*}
Many constants of these forms, documented in the \UNIX{} documentation on
sockets and/or the IP protocol, are also defined in the socket module.
***************
*** 102,105 ****
--- 149,180 ----
\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}.
+
+ The rest of the arguments are optional and must be numeric if
+ specified. For \var{host} and \var{port}, by passing either an empty
+ string or \code{None}, you can pass \code{NULL} to the C API. The
+ \function{getaddrinfo()} function returns a list of 5-tuples with
+ 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}
+ \end{funcdesc}
+
\begin{funcdesc}{getfqdn}{\optional{name}}
Return a fully qualified domain name for \var{name}.
***************
*** 114,137 ****
\begin{funcdesc}{gethostbyname}{hostname}
! Translate a host name to IP address format. The IP address is
returned as a string, e.g., \code{'100.50.200.5'}. If the host name
! is an IP address itself it is returned unchanged. See
\function{gethostbyname_ex()} for a more complete interface.
\end{funcdesc}
\begin{funcdesc}{gethostbyname_ex}{hostname}
! Translate a host name to IP 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 IP addresses for the same interface on the same
host (often but not always a single address).
\end{funcdesc}
\begin{funcdesc}{gethostname}{}
Return a string containing the hostname of the machine where
! the Python interpreter is currently executing. If you want to know the
! current machine's IP address, use \code{gethostbyname(gethostname())}.
Note: \function{gethostname()} doesn't always return the fully qualified
domain name; use \code{gethostbyaddr(gethostname())}
--- 189,219 ----
\begin{funcdesc}{gethostbyname}{hostname}
! Translate a host name to IPv4 address format. The IPv4 address is
returned as a string, e.g., \code{'100.50.200.5'}. If the host name
! is an IPv4 address itself it is returned unchanged. See
\function{gethostbyname_ex()} for a more complete interface.
+ \function{gethostbyname()} does not support IPv6 name resolution, and
+ \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
\end{funcdesc}
\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).
+ \function{gethostbyname_ex()} does not support IPv6 name resolution, and
+ \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
\end{funcdesc}
\begin{funcdesc}{gethostname}{}
Return a string containing the hostname of the machine where
! the Python interpreter is currently executing.
! If you want to know the current machine's IP address, you may want to use
! \code{gethostbyname(gethostname())}.
! This operation assumes that there is a valid address-to-host mapping for
! the host, and the assumption does not always hold.
Note: \function{gethostname()} doesn't always return the fully qualified
domain name; use \code{gethostbyaddr(gethostname())}
***************
*** 144,153 ****
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 IP addresses for the same interface
on the same host (most likely containing only a single address).
To find the fully qualified domain name, use the function
\function{getfqdn()}.
\end{funcdesc}
\begin{funcdesc}{getprotobyname}{protocolname}
Translate an Internet protocol name (e.g.\ \code{'icmp'}) to a constant
--- 226,246 ----
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/v6 addresses for the same interface
on the same host (most likely containing only a single address).
To find the fully qualified domain name, use the function
\function{getfqdn()}.
+ \function{gethostbyaddr} supports both IPv4 and IPv6.
\end{funcdesc}
+ \begin{funcdesc}{getnameinfo}{sockaddr, flags}
+ Translate a socket address \var{sockaddr} into a 2-tuple
+ \code{(\var{host}, \var{port})}.
+ Depending on the settings of \var{flags}, the result can contain a
+ fully-qualified domain name or numeric address representation in
+ \var{host}. Similarly, \var{port} can contain a string port name or a
+ numeric port number.
+ \versionadded{2.2}
+ \end{funcdesc}
+
\begin{funcdesc}{getprotobyname}{protocolname}
Translate an Internet protocol name (e.g.\ \code{'icmp'}) to a constant
***************
*** 167,171 ****
\begin{funcdesc}{socket}{family, type\optional{, proto}}
Create a new socket using the given address family, socket type and
! protocol number. The address family should be \constant{AF_INET} or
\constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM},
\constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants.
--- 260,264 ----
\begin{funcdesc}{socket}{family, type\optional{, proto}}
Create a new socket using the given address family, socket type and
! protocol number. The address family should be \constant{AF_INET}, \constant{AF_INET6} or
\constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM},
\constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants.
***************
*** 210,214 ****
\begin{funcdesc}{inet_aton}{ip_string}
! Convert an IP address from dotted-quad string format
(e.g.\ '123.45.67.89') to 32-bit packed binary format, as a string four
characters in length.
--- 303,307 ----
\begin{funcdesc}{inet_aton}{ip_string}
! Convert an IPv4 address from dotted-quad string format
(e.g.\ '123.45.67.89') to 32-bit packed binary format, as a string four
characters in length.
***************
*** 218,229 ****
for the 32-bit packed binary this function returns.
! 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 the underlying C implementation of
\cfunction{inet_aton()}.
\end{funcdesc}
\begin{funcdesc}{inet_ntoa}{packed_ip}
! Convert a 32-bit packed IP address (a string four characters in
length) to its standard dotted-quad string representation
(e.g. '123.45.67.89').
--- 311,325 ----
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
valid depends on the underlying C implementation of
\cfunction{inet_aton()}.
+
+ \function{inet_aton} does not support IPv6, and
+ \function{getnameinfo()} should be used instead for IPv4/v6 dual stack support.
\end{funcdesc}
\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
(e.g. '123.45.67.89').
***************
*** 235,238 ****
--- 331,337 ----
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.
\end{funcdesc}
***************
*** 307,311 ****
\begin{methoddesc}[socket]{getpeername}{}
Return the remote address to which the socket is connected. This is
! useful to find out the port number of a remote IP socket, for instance.
(The format of the address returned depends on the address family ---
see above.) On some systems this function is not supported.
--- 406,410 ----
\begin{methoddesc}[socket]{getpeername}{}
Return the remote address to which the socket is connected. This is
! useful to find out the port number of a remote IPv4/v6 socket, for instance.
(The format of the address returned depends on the address family ---
see above.) On some systems this function is not supported.
***************
*** 314,318 ****
\begin{methoddesc}[socket]{getsockname}{}
Return the socket's own address. This is useful to find out the port
! number of an IP socket, for instance.
(The format of the address returned depends on the address family ---
see above.)
--- 413,417 ----
\begin{methoddesc}[socket]{getsockname}{}
Return the socket's own address. This is useful to find out the port
! number of an IPv4/v6 socket, for instance.
(The format of the address returned depends on the address family ---
see above.)
***************
*** 414,418 ****
\subsection{Example \label{socket-example}}
! Here are two minimal example programs using the TCP/IP protocol:\ a
server that echoes all data that it receives back (servicing only one
client), and a client using it. Note that a server must perform the
--- 513,517 ----
\subsection{Example \label{socket-example}}
! Here are four minimal example programs using the TCP/IP protocol:\ a
server that echoes all data that it receives back (servicing only one
client), and a client using it. Note that a server must perform the
***************
*** 425,428 ****
--- 524,529 ----
\method{accept()}.
+ The first two examples support IPv4 only.
+
\begin{verbatim}
# Echo server program
***************
*** 451,454 ****
--- 552,631 ----
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
+ s.send('Hello, world')
+ data = s.recv(1024)
+ s.close()
+ print 'Received', `data`
+ \end{verbatim}
+
+ The next two examples are identical to the above two, but support both
+ IPv4 and IPv6.
+ The server side will listen to the first address family available
+ (it should listen to both instead).
+ On most of IPv6-ready systems, IPv6 will take precedence
+ and the server may not accept IPv4 traffic.
+ The client side will try to connect to the all addresses returned as a result
+ of the name resolution, and sends traffic to the first one connected
+ successfully.
+
+ \begin{verbatim}
+ # Echo server program
+ import socket
+ import sys
+
+ HOST = '' # Symbolic name meaning the local host
+ PORT = 50007 # Arbitrary non-privileged port
+ s = None
+ for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
+ af, socktype, proto, canonname, sa = res
+ try:
+ s = socket.socket(af, socktype, proto)
+ except socket.error, msg:
+ s = None
+ continue
+ try:
+ s.bind(sa)
+ s.listen(1)
+ except socket.error, msg:
+ s.close()
+ s = None
+ continue
+ break
+ if s is None:
+ print 'could not open socket'
+ sys.exit(1)
+ conn, addr = s.accept()
+ print 'Connected by', addr
+ while 1:
+ data = conn.recv(1024)
+ if not data: break
+ conn.send(data)
+ conn.close()
+ \end{verbatim}
+
+ \begin{verbatim}
+ # Echo client program
+ import socket
+ import sys
+
+ HOST = 'daring.cwi.nl' # The remote host
+ PORT = 50007 # The same port as used by the server
+ s = None
+ for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
+ af, socktype, proto, canonname, sa = res
+ try:
+ s = socket.socket(af, socktype, proto)
+ except socket.error, msg:
+ s = None
+ continue
+ try:
+ s.connect(sa)
+ except socket.error, msg:
+ s.close()
+ s = None
+ continue
+ break
+ if s is None:
+ print 'could not open socket'
+ sys.exit(1)
s.send('Hello, world')
data = s.recv(1024)