PageRenderTime 89ms CodeModel.GetById 83ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/library/diff/socket.rst.diff

https://bitbucket.org/pydocja/py26
diff | 409 lines | 312 code | 97 blank | 0 comment | 0 complexity | c7169594368367d7c2f55c20010ab937 MD5 | raw file
  1--- r262/library/socket.rst	2009-01-04 06:55:17.853888000 +0900
  2+++ r266/library/socket.rst	2010-06-12 18:50:02.725360000 +0900
  3@@ -1,13 +1,12 @@
  4-
  5 :mod:`socket` --- Low-level networking interface
  6 ================================================
  7 
  8 .. module:: socket
  9    :synopsis: Low-level networking interface.
 10 
 11 
 12 This module provides access to the BSD *socket* interface. It is available on
 13 all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional
 14 platforms.
 15 
 16 .. note::
 17@@ -64,44 +63,45 @@
 18 numeric address in *host* portion.
 19 
 20 .. versionadded:: 2.5
 21    AF_NETLINK sockets are represented as  pairs ``pid, groups``.
 22 
 23 .. versionadded:: 2.6
 24    Linux-only support for TIPC is also available using the :const:`AF_TIPC`
 25    address family. TIPC is an open, non-IP based networked protocol designed
 26    for use in clustered computer environments.  Addresses are represented by a
 27    tuple, and the fields depend on the address type. The general tuple form is
 28    ``(addr_type, v1, v2, v3 [, scope])``, where:
 29 
 30-     - *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
 31-       TIPC_ADDR_ID.
 32-     - *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
 33-       TIPC_NODE_SCOPE.
 34-     - If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
 35-       the port identifier, and *v3* should be 0.
 36+   - *addr_type* is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or
 37+     TIPC_ADDR_ID.
 38+   - *scope* is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and
 39+     TIPC_NODE_SCOPE.
 40+   - If *addr_type* is TIPC_ADDR_NAME, then *v1* is the server type, *v2* is
 41+     the port identifier, and *v3* should be 0.
 42 
 43-       If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
 44-       is the lower port number, and *v3* is the upper port number.
 45+     If *addr_type* is TIPC_ADDR_NAMESEQ, then *v1* is the server type, *v2*
 46+     is the lower port number, and *v3* is the upper port number.
 47 
 48-       If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
 49-       reference, and *v3* should be set to 0.
 50+     If *addr_type* is TIPC_ADDR_ID, then *v1* is the node, *v2* is the
 51+     reference, and *v3* should be set to 0.
 52 
 53 
 54 All errors raise exceptions.  The normal exceptions for invalid argument types
 55 and out-of-memory conditions can be raised; errors related to socket or address
 56 semantics raise the error :exc:`socket.error`.
 57 
 58-Non-blocking mode is supported through :meth:`setblocking`.  A generalization of
 59-this based on timeouts is supported through :meth:`settimeout`.
 60+Non-blocking mode is supported through :meth:`~socket.setblocking`.  A
 61+generalization of this based on timeouts is supported through
 62+:meth:`~socket.settimeout`.
 63 
 64 The module :mod:`socket` exports the following constants and functions:
 65 
 66 
 67 .. exception:: error
 68 
 69    .. index:: module: errno
 70 
 71    This exception is raised for socket-related errors. The accompanying value is
 72    either a string telling what went wrong or a pair ``(errno, string)``
 73    representing an error returned by a system call, similar to the value
 74    accompanying :exc:`os.error`. See the module :mod:`errno`, which contains names
 75@@ -207,44 +207,62 @@
 76 
 77 .. function:: create_connection(address[, timeout])
 78 
 79    Convenience function.  Connect to *address* (a 2-tuple ``(host, port)``),
 80    and return the socket object.  Passing the optional *timeout* parameter will
 81    set the timeout on the socket instance before attempting to connect.  If no
 82    *timeout* is supplied, the global default timeout setting returned by
 83    :func:`getdefaulttimeout` is used.
 84 
 85    .. versionadded:: 2.6
 86 
 87 
 88-.. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
 89+.. function:: getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0)
 90 
 91-   Resolves the *host*/*port* argument, into a sequence of 5-tuples that contain
 92-   all the necessary arguments for creating the corresponding socket. *host* is a domain
 93-   name, a string representation of an IPv4/v6 address or ``None``. *port* is a string
 94-   service name such as ``'http'``, a numeric port number or ``None``.
 95-   The rest of the arguments are optional and must be numeric if specified.
 96-   By passing ``None`` as the value of *host* and *port*, , you can pass ``NULL`` to the C API.
 97+   Translate the *host*/*port* argument into a sequence of 5-tuples that contain
 98+   all the necessary arguments for creating a socket connected to that service.
 99+   *host* is a domain name, a string representation of an IPv4/v6 address
100+   or ``None``. *port* is a string service name such as ``'http'``, a numeric
101+   port number or ``None``.  By passing ``None`` as the value of *host*
102+   and *port*, you can pass ``NULL`` to the underlying C API.
103+
104+   The *family*, *socktype* and *proto* arguments can be optionally specified
105+   in order to narrow the list of addresses returned.  Passing zero as a
106+   value for each of these arguments selects the full range of results.
107+   The *flags* argument can be one or several of the ``AI_*`` constants,
108+   and will influence how results are computed and returned.
109+   For example, :const:`AI_NUMERICHOST` will disable domain name resolution
110+   and will raise an error if *host* is a domain name.
111 
112-   The :func:`getaddrinfo` function returns a list of 5-tuples with the following
113-   structure:
114+   The function returns a list of 5-tuples with the following structure:
115 
116    ``(family, socktype, proto, canonname, sockaddr)``
117 
118-   *family*, *socktype*, *proto* are all integers and are meant to be passed to the
119-   :func:`socket` function. *canonname* is a string representing the canonical name
120-   of the *host*. It can be a numeric IPv4/v6 address when :const:`AI_CANONNAME` is
121-   specified for a numeric *host*. *sockaddr* is a tuple describing a socket
122-   address, as described above. See the source for :mod:`socket` and other
123-   library modules for a typical usage of the function.
124+   In these tuples, *family*, *socktype*, *proto* are all integers and are
125+   meant to be passed to the :func:`socket` function.  *canonname* will be
126+   a string representing the canonical name of the *host* if
127+   :const:`AI_CANONNAME` is part of the *flags* argument; else *canonname*
128+   will be empty.  *sockaddr* is a tuple describing a socket address, whose
129+   format depends on the returned *family* (a ``(address, port)`` 2-tuple for
130+   :const:`AF_INET`, a ``(address, port, flow info, scope id)`` 4-tuple for
131+   :const:`AF_INET6`), and is meant to be passed to the :meth:`socket.connect`
132+   method.
133+
134+   The following example fetches address information for a hypothetical TCP
135+   connection to ``www.python.org`` on port 80 (results may differ on your
136+   system if IPv6 isn't enabled)::
137+
138+      >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP)
139+      [(2, 1, 6, '', ('82.94.164.162', 80)),
140+       (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
141 
142    .. versionadded:: 2.2
143 
144 
145 .. function:: getfqdn([name])
146 
147    Return a fully qualified domain name for *name*. If *name* is omitted or empty,
148    it is interpreted as the local host.  To find the fully qualified name, the
149    hostname returned by :func:`gethostbyaddr` is checked, followed by aliases for the
150    host, if available.  The first name which includes a period is selected.  In
151    case no fully qualified domain name is available, the hostname as returned by
152    :func:`gethostname` is returned.
153@@ -392,43 +410,46 @@
154    where the host byte order is the same as network byte order, this is a no-op;
155    otherwise, it performs a 2-byte swap operation.
156 
157 
158 .. function:: inet_aton(ip_string)
159 
160    Convert an IPv4 address from dotted-quad string format (for example,
161    '123.45.67.89') to 32-bit packed binary format, as a string four characters in
162    length.  This is useful when conversing with a program that uses the standard C
163    library and needs objects of type :ctype:`struct in_addr`, which is the C type
164    for the 32-bit packed binary this function returns.
165 
166+   :func:`inet_aton` also accepts strings with less than three dots; see the
167+   Unix manual page :manpage:`inet(3)` for details.
168+
169    If the IPv4 address string passed to this function is invalid,
170    :exc:`socket.error` will be raised. Note that exactly what is valid depends on
171    the underlying C implementation of :cfunc:`inet_aton`.
172 
173-   :func:`inet_aton` does not support IPv6, and :func:`getnameinfo` should be used
174+   :func:`inet_aton` does not support IPv6, and :func:`inet_pton` should be used
175    instead for IPv4/v6 dual stack support.
176 
177 
178 .. function:: inet_ntoa(packed_ip)
179 
180    Convert a 32-bit packed IPv4 address (a string four characters in length) to its
181    standard dotted-quad string representation (for example, '123.45.67.89').  This
182    is useful when conversing with a program that uses the standard C library and
183    needs objects of type :ctype:`struct in_addr`, which is the C type for the
184    32-bit packed binary data this function takes as an argument.
185 
186    If the string passed to this function is not exactly 4 bytes in length,
187    :exc:`socket.error` will be raised. :func:`inet_ntoa` does not support IPv6, and
188-   :func:`getnameinfo` should be used instead for IPv4/v6 dual stack support.
189+   :func:`inet_ntop` should be used instead for IPv4/v6 dual stack support.
190 
191 
192 .. function:: inet_pton(address_family, ip_string)
193 
194    Convert an IP address from its family-specific string format to a packed, binary
195    format. :func:`inet_pton` is useful when a library or network protocol calls for
196    an object of type :ctype:`struct in_addr` (similar to :func:`inet_aton`) or
197    :ctype:`struct in6_addr`.
198 
199    Supported values for *address_family* are currently :const:`AF_INET` and
200    :const:`AF_INET6`. If the IP address string *ip_string* is invalid,
201    :exc:`socket.error` will be raised. Note that exactly what is valid depends on
202@@ -585,25 +606,30 @@
203    and its integer value is returned by the function.  If *buflen* is present, it
204    specifies the maximum length of the buffer used to receive the option in, and
205    this buffer is returned as a string.  It is up to the caller to decode the
206    contents of the buffer (see the optional built-in module :mod:`struct` for a way
207    to decode C structures encoded as strings).
208 
209 
210 .. method:: socket.ioctl(control, option)
211 
212    :platform: Windows
213 
214    The :meth:`ioctl` method is a limited interface to the WSAIoctl system
215-   interface. Please refer to the MSDN documentation for more information.
216+   interface.  Please refer to the `Win32 documentation
217+   <http://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx>`_ for more
218+   information.
219+
220+   On other platforms, the generic :func:`fcntl.fcntl` and :func:`fcntl.ioctl`
221+   functions may be used; they accept a socket object as their first argument.
222 
223    .. versionadded:: 2.6
224 
225 
226 .. method:: socket.listen(backlog)
227 
228    Listen for connections made to the socket.  The *backlog* argument specifies the
229    maximum number of queued connections and should be at least 1; the maximum value
230    is system-dependent (usually 5).
231 
232 
233 .. method:: socket.makefile([mode[, bufsize]])
234@@ -647,28 +673,28 @@
235    new string.  The return value is a pair ``(nbytes, address)`` where *nbytes* is
236    the number of bytes received and *address* is the address of the socket sending
237    the data.  See the Unix manual page :manpage:`recv(2)` for the meaning of the
238    optional argument *flags*; it defaults to zero.  (The format of *address*
239    depends on the address family --- see above.)
240 
241    .. versionadded:: 2.5
242 
243 
244 .. method:: socket.recv_into(buffer[, nbytes[, flags]])
245 
246    Receive up to *nbytes* bytes from the socket, storing the data into a buffer
247-   rather than creating a new string.     If *nbytes* is not specified (or 0),
248-   receive up to the size available in the given buffer. See the Unix manual page
249-   :manpage:`recv(2)` for the meaning of the optional argument *flags*; it defaults
250-   to zero.
251+   rather than creating a new string.  If *nbytes* is not specified (or 0),
252+   receive up to the size available in the given buffer.  Returns the number of
253+   bytes received.  See the Unix manual page :manpage:`recv(2)` for the meaning
254+   of the optional argument *flags*; it defaults to zero.
255 
256    .. versionadded:: 2.5
257 
258 
259 .. method:: socket.send(string[, flags])
260 
261    Send data to the socket.  The socket must be connected to a remote socket.  The
262    optional *flags* argument has the same meaning as for :meth:`recv` above.
263    Returns the number of bytes sent. Applications are responsible for checking that
264    all data has been sent; if only some of the data was transmitted, the
265    application needs to attempt delivery of the remaining data.
266 
267@@ -690,25 +716,25 @@
268    argument has the same meaning as for :meth:`recv` above.  Return the number of
269    bytes sent. (The format of *address* depends on the address family --- see
270    above.)
271 
272 
273 .. method:: socket.setblocking(flag)
274 
275    Set blocking or non-blocking mode of the socket: if *flag* is 0, the socket is
276    set to non-blocking, else to blocking mode.  Initially all sockets are in
277    blocking mode.  In non-blocking mode, if a :meth:`recv` call doesn't find any
278    data, or if a :meth:`send` call can't immediately dispose of the data, a
279    :exc:`error` exception is raised; in blocking mode, the calls block until they
280-   can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0)``;
281+   can proceed. ``s.setblocking(0)`` is equivalent to ``s.settimeout(0.0)``;
282    ``s.setblocking(1)`` is equivalent to ``s.settimeout(None)``.
283 
284 
285 .. method:: socket.settimeout(value)
286 
287    Set a timeout on blocking socket operations.  The *value* argument can be a
288    nonnegative float expressing seconds, or ``None``. If a float is given,
289    subsequent socket operations will raise an :exc:`timeout` exception if the
290    timeout period *value* has elapsed before the operation has completed.  Setting
291    a timeout of ``None`` disables timeouts on socket operations.
292    ``s.settimeout(0.0)`` is equivalent to ``s.setblocking(0)``;
293    ``s.settimeout(None)`` is equivalent to ``s.setblocking(1)``.
294@@ -717,64 +743,67 @@
295 
296 
297 .. method:: socket.gettimeout()
298 
299    Return the timeout in floating seconds associated with socket operations, or
300    ``None`` if no timeout is set.  This reflects the last call to
301    :meth:`setblocking` or :meth:`settimeout`.
302 
303    .. versionadded:: 2.3
304 
305 Some notes on socket blocking and timeouts: A socket object can be in one of
306 three modes: blocking, non-blocking, or timeout.  Sockets are always created in
307-blocking mode.  In blocking mode, operations block until complete.  In
308+blocking mode.  In blocking mode, operations block until complete or
309+the system returns an error (such as connection timed out).  In
310 non-blocking mode, operations fail (with an error that is unfortunately
311 system-dependent) if they cannot be completed immediately.  In timeout mode,
312 operations fail if they cannot be completed within the timeout specified for the
313-socket.  The :meth:`setblocking` method is simply a shorthand for certain
314-:meth:`settimeout` calls.
315+socket or if the system returns an error.  The :meth:`~socket.setblocking`
316+method is simply a shorthand for certain :meth:`~socket.settimeout` calls.
317 
318 Timeout mode internally sets the socket in non-blocking mode.  The blocking and
319 timeout modes are shared between file descriptors and socket objects that refer
320 to the same network endpoint.  A consequence of this is that file objects
321-returned by the :meth:`makefile` method must only be used when the socket is in
322-blocking mode; in timeout or non-blocking mode file operations that cannot be
323-completed immediately will fail.
324-
325-Note that the :meth:`connect` operation is subject to the timeout setting, and
326-in general it is recommended to call :meth:`settimeout` before calling
327-:meth:`connect`.
328+returned by the :meth:`~socket.makefile` method must only be used when the
329+socket is in blocking mode; in timeout or non-blocking mode file operations
330+that cannot be completed immediately will fail.
331+
332+Note that the :meth:`~socket.connect` operation is subject to the timeout
333+setting, and in general it is recommended to call :meth:`~socket.settimeout`
334+before calling :meth:`~socket.connect` or pass a timeout parameter to
335+:meth:`create_connection`.  The system network stack may return a connection
336+timeout error of its own regardless of any Python socket timeout setting.
337 
338 
339 .. method:: socket.setsockopt(level, optname, value)
340 
341    .. index:: module: struct
342 
343    Set the value of the given socket option (see the Unix manual page
344    :manpage:`setsockopt(2)`).  The needed symbolic constants are defined in the
345    :mod:`socket` module (:const:`SO_\*` etc.).  The value can be an integer or a
346    string representing a buffer.  In the latter case it is up to the caller to
347    ensure that the string contains the proper bits (see the optional built-in
348    module :mod:`struct` for a way to encode C structures as strings).
349 
350 
351 .. method:: socket.shutdown(how)
352 
353    Shut down one or both halves of the connection.  If *how* is :const:`SHUT_RD`,
354    further receives are disallowed.  If *how* is :const:`SHUT_WR`, further sends
355    are disallowed.  If *how* is :const:`SHUT_RDWR`, further sends and receives are
356    disallowed.
357 
358-Note that there are no methods :meth:`read` or :meth:`write`; use :meth:`recv`
359-and :meth:`send` without *flags* argument instead.
360+Note that there are no methods :meth:`read` or :meth:`write`; use
361+:meth:`~socket.recv` and :meth:`~socket.send` without *flags* argument instead.
362 
363 Socket objects also have these (read-only) attributes that correspond to the
364 values given to the :class:`socket` constructor.
365 
366 
367 .. attribute:: socket.family
368 
369    The socket family.
370 
371    .. versionadded:: 2.5
372 
373 
374@@ -791,29 +820,30 @@
375 
376    .. versionadded:: 2.5
377 
378 
379 .. _socket-example:
380 
381 Example
382 -------
383 
384 Here are four minimal example programs using the TCP/IP protocol: a server that
385 echoes all data that it receives back (servicing only one client), and a client
386 using it.  Note that a server must perform the sequence :func:`socket`,
387-:meth:`bind`, :meth:`listen`, :meth:`accept` (possibly repeating the
388-:meth:`accept` to service more than one client), while a client only needs the
389-sequence :func:`socket`, :meth:`connect`.  Also note that the server does not
390-:meth:`send`/:meth:`recv` on the  socket it is listening on but on the new
391-socket returned by :meth:`accept`.
392+:meth:`~socket.bind`, :meth:`~socket.listen`, :meth:`~socket.accept` (possibly
393+repeating the :meth:`~socket.accept` to service more than one client), while a
394+client only needs the sequence :func:`socket`, :meth:`~socket.connect`.  Also
395+note that the server does not :meth:`~socket.send`/:meth:`~socket.recv` on the
396+socket it is listening on but on the new socket returned by
397+:meth:`~socket.accept`.
398 
399 The first two examples support IPv4 only. ::
400 
401    # Echo server program
402    import socket
403 
404    HOST = ''                 # Symbolic name meaning all available interfaces
405    PORT = 50007              # Arbitrary non-privileged port
406    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
407    s.bind((HOST, PORT))
408    s.listen(1)
409    conn, addr = s.accept()