Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsocket.tex @ 39042:c02fa187e0f4 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Part of SF patch #1484695. This removes dead code. The chksum was already verified in .frombuf() on the lines above. If there was a problem an exception is raised, so there was no way this condition could have been true.
author Neal Norwitz <nnorwitz@gmail.com>
date Mon, 10 Jul 2006 00:23:17 +0000
parents 464265c1d08b
children 6ff72ad93ad2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8880
diff changeset
1 \section{\module{socket} ---
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
2 Low-level networking interface}
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{builtin}{socket}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
5 \modulesynopsis{Low-level networking interface.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6804
diff changeset
8 This module provides access to the BSD \emph{socket} interface.
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
9 It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS,
35671
5d5236eae8bd SF Bug #1308042, platform dependent behaviour (Windoze of course) in UDP sockets. Will backport
Neal Norwitz <nnorwitz@gmail.com>
parents: 34739
diff changeset
10 OS/2, and probably additional platforms. \note{Some behavior may be
5d5236eae8bd SF Bug #1308042, platform dependent behaviour (Windoze of course) in UDP sockets. Will backport
Neal Norwitz <nnorwitz@gmail.com>
parents: 34739
diff changeset
11 platform dependent, since calls are made to the operating system socket APIs.}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 For an introduction to socket programming (in C), see the following
11463
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11291
diff changeset
14 papers: \citetitle{An Introductory 4.3BSD Interprocess Communication
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11291
diff changeset
15 Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11291
diff changeset
16 Interprocess Communication Tutorial}, by Samuel J. Leffler et al,
17e12305973e Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11291
diff changeset
17 both in the \citetitle{\UNIX{} Programmer's Manual, Supplementary Documents 1}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
18 (sections PS1:7 and PS1:8). The platform-specific reference material
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
19 for the various socket-related system calls are also a valuable source
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
20 of information on the details of socket semantics. For \UNIX, refer
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
21 to the manual pages; for Windows, see the WinSock (or Winsock 2)
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11463
diff changeset
22 specification.
20127
697206e74763 Fix some markup errors.
Fred Drake <fdrake@acm.org>
parents: 20082
diff changeset
23 For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled
697206e74763 Fix some markup errors.
Fred Drake <fdrake@acm.org>
parents: 20082
diff changeset
24 \citetitle{Basic Socket Interface Extensions for IPv6}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 The Python interface is a straightforward transliteration of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \UNIX{} system call and library interface for sockets to Python's
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
28 object-oriented style: the \function{socket()} function returns a
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
29 \dfn{socket object}\obindex{socket} whose methods implement the
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
30 various socket system calls. Parameter types are somewhat
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
31 higher-level than in the C interface: as with \method{read()} and
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
32 \method{write()} operations on Python files, buffer allocation on
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
33 receive operations is automatic, and buffer length is implicit on send
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
34 operations.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
36 Socket addresses are represented as follows:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
37 A single string is used for the \constant{AF_UNIX} address family.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
38 A pair \code{(\var{host}, \var{port})} is used for the
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
39 \constant{AF_INET} address family, where \var{host} is a string
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
40 representing either a hostname in Internet domain notation like
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
41 \code{'daring.cwi.nl'} or an IPv4 address like \code{'100.50.200.5'},
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
42 and \var{port} is an integral port number.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
43 For \constant{AF_INET6} address family, a four-tuple
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
44 \code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
45 used, where \var{flowinfo} and \var{scopeid} represents
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
46 \code{sin6_flowinfo} and \code{sin6_scope_id} member in
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
47 \constant{struct sockaddr_in6} in C.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
48 For \module{socket} module methods, \var{flowinfo} and \var{scopeid}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
49 can be omitted just for backward compatibility. Note, however,
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
50 omission of \var{scopeid} can cause problems in manipulating scoped
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
51 IPv6 addresses. Other address families are currently not supported.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
52 The address format required by a particular socket object is
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
53 automatically selected based on the address family specified when the
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
54 socket object was created.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
56 For IPv4 addresses, two special forms are accepted instead of a host
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
57 address: the empty string represents \constant{INADDR_ANY}, and the string
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
58 \code{'<broadcast>'} represents \constant{INADDR_BROADCAST}.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
59 The behavior is not available for IPv6 for backward compatibility,
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
60 therefore, you may want to avoid these if you intend to support IPv6 with
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
61 your Python programs.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
62
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
63 If you use a hostname in the \var{host} portion of IPv4/v6 socket
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
64 address, the program may show a nondeterministic behavior, as Python
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
65 uses the first address returned from the DNS resolution. The socket
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
66 address will be resolved differently into an actual IPv4/v6 address,
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
67 depending on the results from DNS resolution and/or the host
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
68 configuration. For deterministic behavior use a numeric address in
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
69 \var{host} portion.
5461
0ded63bcf5de Document "" and "<broadcast>".
Guido van Rossum <guido@python.org>
parents: 4929
diff changeset
70
36290
b94ee92a6d6b Remove dots in \version{changed,added} argument and
Georg Brandl <georg@python.org>
parents: 36288
diff changeset
71 \versionadded[AF_NETLINK sockets are represented as
b94ee92a6d6b Remove dots in \version{changed,added} argument and
Georg Brandl <georg@python.org>
parents: 36288
diff changeset
72 pairs \code{\var{pid}, \var{groups}}]{2.5}
36286
ae4480935016 Patch #1103116: AF_NETLINK sockets basic support.
Martin v. Löwis <martin@v.loewis.de>
parents: 36126
diff changeset
73
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 All errors raise exceptions. The normal exceptions for invalid
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 argument types and out-of-memory conditions can be raised; errors
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
76 related to socket or address semantics raise the error
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
77 \exception{socket.error}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
79 Non-blocking mode is supported through
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
80 \method{setblocking()}. A generalization of this based on timeouts
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
81 is supported through \method{settimeout()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
83 The module \module{socket} exports the following constants and functions:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
85
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
86 \begin{excdesc}{error}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
87 This exception is raised for socket-related errors.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 The accompanying value is either a string telling what went wrong or a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 pair \code{(\var{errno}, \var{string})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 representing an error returned by a system
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
91 call, similar to the value accompanying \exception{os.error}.
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
92 See the module \refmodule{errno}\refbimodindex{errno}, which contains
7200
98a9da520f1d Add ref to errno module, and change ref to posix.error to os.error.
Guido van Rossum <guido@python.org>
parents: 7135
diff changeset
93 names for the error codes defined by the underlying operating system.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
96 \begin{excdesc}{herror}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
97 This exception is raised for address-related errors, i.e. for
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
98 functions that use \var{h_errno} in the C API, including
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
99 \function{gethostbyname_ex()} and \function{gethostbyaddr()}.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
100
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
101 The accompanying value is a pair \code{(\var{h_errno}, \var{string})}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
102 representing an error returned by a library call. \var{string}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
103 represents the description of \var{h_errno}, as returned by
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
104 the \cfunction{hstrerror()} C function.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
105 \end{excdesc}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
106
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
107 \begin{excdesc}{gaierror}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
108 This exception is raised for address-related errors, for
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
109 \function{getaddrinfo()} and \function{getnameinfo()}.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
110 The accompanying value is a pair \code{(\var{error}, \var{string})}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
111 representing an error returned by a library call.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
112 \var{string} represents the description of \var{error}, as returned
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
113 by the \cfunction{gai_strerror()} C function.
31976
c5a552578344 note that the error code for socket.gaierror will be one of the EAI_*
Fred Drake <fdrake@acm.org>
parents: 31862
diff changeset
114 The \var{error} value will match one of the \constant{EAI_*} constants
c5a552578344 note that the error code for socket.gaierror will be one of the EAI_*
Fred Drake <fdrake@acm.org>
parents: 31862
diff changeset
115 defined in this module.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
116 \end{excdesc}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
117
29665
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
118 \begin{excdesc}{timeout}
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
119 This exception is raised when a timeout occurs on a socket which has
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
120 had timeouts enabled via a prior call to \method{settimeout()}. The
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
121 accompanying value is a string whose value is currently always ``timed
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
122 out''.
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
123 \versionadded{2.3}
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
124 \end{excdesc}
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
125
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126 \begin{datadesc}{AF_UNIX}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 \dataline{AF_INET}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
128 \dataline{AF_INET6}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 These constants represent the address (and protocol) families,
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
130 used for the first argument to \function{socket()}. If the
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
131 \constant{AF_UNIX} constant is not defined then this protocol is
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
132 unsupported.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 \begin{datadesc}{SOCK_STREAM}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 \dataline{SOCK_DGRAM}
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
137 \dataline{SOCK_RAW}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
138 \dataline{SOCK_RDM}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
139 \dataline{SOCK_SEQPACKET}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 These constants represent the socket types,
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
141 used for the second argument to \function{socket()}.
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
142 (Only \constant{SOCK_STREAM} and
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
143 \constant{SOCK_DGRAM} appear to be generally useful.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145
2354
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
146 \begin{datadesc}{SO_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
147 \dataline{SOMAXCONN}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
148 \dataline{MSG_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
149 \dataline{SOL_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
150 \dataline{IPPROTO_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
151 \dataline{IPPORT_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
152 \dataline{INADDR_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
153 \dataline{IP_*}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
154 \dataline{IPV6_*}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
155 \dataline{EAI_*}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
156 \dataline{AI_*}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
157 \dataline{NI_*}
21528
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
158 \dataline{TCP_*}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
159 Many constants of these forms, documented in the \UNIX{} documentation on
2354
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
160 sockets and/or the IP protocol, are also defined in the socket module.
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
161 They are generally used in arguments to the \method{setsockopt()} and
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
162 \method{getsockopt()} methods of socket objects. In most cases, only
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
163 those symbols that are defined in the \UNIX{} header files are defined;
2354
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
164 for a few symbols, default values are provided.
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
165 \end{datadesc}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
166
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
167 \begin{datadesc}{has_ipv6}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
168 This constant contains a boolean value which indicates if IPv6 is
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
169 supported on this platform.
28831
7012ca64bc74 Add versionadded for has_ipv6 attribute
Neal Norwitz <nnorwitz@gmail.com>
parents: 28818
diff changeset
170 \versionadded{2.3}
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
171 \end{datadesc}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
172
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
173 \begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{,
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
174 socktype\optional{, proto\optional{,
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
175 flags}}}}}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
176 Resolves the \var{host}/\var{port} argument, into a sequence of
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
177 5-tuples that contain all the necessary argument for the sockets
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
178 manipulation. \var{host} is a domain name, a string representation of
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
179 IPv4/v6 address or \code{None}.
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
180 \var{port} is a string service name (like \code{'http'}), a numeric
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
181 port number or \code{None}.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
182
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
183 The rest of the arguments are optional and must be numeric if
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
184 specified. For \var{host} and \var{port}, by passing either an empty
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
185 string or \code{None}, you can pass \code{NULL} to the C API. The
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
186 \function{getaddrinfo()} function returns a list of 5-tuples with
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
187 the following structure:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
188
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
189 \code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
190 \var{sockaddr})}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
191
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
192 \var{family}, \var{socktype}, \var{proto} are all integer and are meant to
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
193 be passed to the \function{socket()} function.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
194 \var{canonname} is a string representing the canonical name of the \var{host}.
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
195 It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
196 for a numeric \var{host}.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
197 \var{sockaddr} is a tuple describing a socket address, as described above.
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
198 See the source for the \refmodule{httplib} and other library modules
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
199 for a typical usage of the function.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
200 \versionadded{2.2}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
201 \end{funcdesc}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
202
14010
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
203 \begin{funcdesc}{getfqdn}{\optional{name}}
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
204 Return a fully qualified domain name for \var{name}.
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
205 If \var{name} is omitted or empty, it is interpreted as the local
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
206 host. To find the fully qualified name, the hostname returned by
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
207 \function{gethostbyaddr()} is checked, then aliases for the host, if
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
208 available. The first name which includes a period is selected. In
34739
0c82a7ef9554 Fix test_socket's test for socket.getfqdn() to also accept the result from
Brett Cannon <bcannon@gmail.com>
parents: 33280
diff changeset
209 case no fully qualified domain name is available, the hostname as
0c82a7ef9554 Fix test_socket's test for socket.getfqdn() to also accept the result from
Brett Cannon <bcannon@gmail.com>
parents: 33280
diff changeset
210 returned by \function{gethostname()} is returned.
14437
e348ed946d1f Added a \versionadded statement to the getfqdn() description.
Fred Drake <fdrake@acm.org>
parents: 14010
diff changeset
211 \versionadded{2.0}
14010
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
212 \end{funcdesc}
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
213
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 \begin{funcdesc}{gethostbyname}{hostname}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
215 Translate a host name to IPv4 address format. The IPv4 address is
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
216 returned as a string, such as \code{'100.50.200.5'}. If the host name
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
217 is an IPv4 address itself it is returned unchanged. See
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
218 \function{gethostbyname_ex()} for a more complete interface.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
219 \function{gethostbyname()} does not support IPv6 name resolution, and
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
220 \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
8880
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
221 \end{funcdesc}
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
222
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
223 \begin{funcdesc}{gethostbyname_ex}{hostname}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
224 Translate a host name to IPv4 address format, extended interface.
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
225 Return a triple \code{(\var{hostname}, \var{aliaslist},
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
226 \var{ipaddrlist})} where
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
227 \var{hostname} is the primary host name responding to the given
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
228 \var{ip_address}, \var{aliaslist} is a (possibly empty) list of
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
229 alternative host names for the same address, and \var{ipaddrlist} is
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
230 a list of IPv4 addresses for the same interface on the same
8880
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
231 host (often but not always a single address).
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
232 \function{gethostbyname_ex()} does not support IPv6 name resolution, and
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
233 \function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
234 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
235
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
236 \begin{funcdesc}{gethostname}{}
1767
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1759
diff changeset
237 Return a string containing the hostname of the machine where
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
238 the Python interpreter is currently executing.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
239 If you want to know the current machine's IP address, you may want to use
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
240 \code{gethostbyname(gethostname())}.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
241 This operation assumes that there is a valid address-to-host mapping for
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
242 the host, and the assumption does not always hold.
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
243 Note: \function{gethostname()} doesn't always return the fully qualified
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
244 domain name; use \code{gethostbyaddr(gethostname())}
4929
5126d4b819e9 Added warning that gethostname() doesn't always return fqdn, and show
Guido van Rossum <guido@python.org>
parents: 4882
diff changeset
245 (see below).
2064
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
246 \end{funcdesc}
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
247
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
248 \begin{funcdesc}{gethostbyaddr}{ip_address}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
249 Return a triple \code{(\var{hostname}, \var{aliaslist},
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
250 \var{ipaddrlist})} where \var{hostname} is the primary host name
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
251 responding to the given \var{ip_address}, \var{aliaslist} is a
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
252 (possibly empty) list of alternative host names for the same address,
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
253 and \var{ipaddrlist} is a list of IPv4/v6 addresses for the same interface
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
254 on the same host (most likely containing only a single address).
14010
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
255 To find the fully qualified domain name, use the function
49c7a4dd9f61 Document socket.getfqdn().
Fred Drake <fdrake@acm.org>
parents: 14002
diff changeset
256 \function{getfqdn()}.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
257 \function{gethostbyaddr} supports both IPv4 and IPv6.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
258 \end{funcdesc}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
259
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
260 \begin{funcdesc}{getnameinfo}{sockaddr, flags}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
261 Translate a socket address \var{sockaddr} into a 2-tuple
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
262 \code{(\var{host}, \var{port})}.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
263 Depending on the settings of \var{flags}, the result can contain a
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
264 fully-qualified domain name or numeric address representation in
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
265 \var{host}. Similarly, \var{port} can contain a string port name or a
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
266 numeric port number.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
267 \versionadded{2.2}
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
268 \end{funcdesc}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
269
4784
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
270 \begin{funcdesc}{getprotobyname}{protocolname}
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
271 Translate an Internet protocol name (for example, \code{'icmp'}) to a constant
4784
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
272 suitable for passing as the (optional) third argument to the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
273 \function{socket()} function. This is usually only needed for sockets
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
274 opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
275 modes, the correct protocol is chosen automatically if the protocol is
4784
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
276 omitted or zero.
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
277 \end{funcdesc}
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
278
32429
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
279 \begin{funcdesc}{getservbyname}{servicename\optional{, protocolname}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
280 Translate an Internet service name and protocol name to a port number
32429
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
281 for that service. The optional protocol name, if given, should be
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
282 \code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
283 \end{funcdesc}
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
284
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
285 \begin{funcdesc}{getservbyport}{port\optional{, protocolname}}
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
286 Translate an Internet port number and protocol name to a service name
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
287 for that service. The optional protocol name, if given, should be
d8abf582f893 Added socket.getservbyport(), and make its second argument and that of
Barry Warsaw <barry@python.org>
parents: 32231
diff changeset
288 \code{'tcp'} or \code{'udp'}, otherwise any protocol will match.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
289 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
290
31432
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
291 \begin{funcdesc}{socket}{\optional{family\optional{,
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
292 type\optional{, proto}}}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293 Create a new socket using the given address family, socket type and
31432
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
294 protocol number. The address family should be \constant{AF_INET} (the
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
295 default), \constant{AF_INET6} or \constant{AF_UNIX}. The socket type
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
296 should be \constant{SOCK_STREAM} (the default), \constant{SOCK_DGRAM}
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
297 or perhaps one of the other \samp{SOCK_} constants. The protocol
8f8bba0a75b4 update signature of the socket constructor
Fred Drake <fdrake@acm.org>
parents: 31181
diff changeset
298 number is usually zero and may be omitted in that case.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
299 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
300
20375
3ab3b535daf2 Document that keyfile and certfile are now optional.
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 20127
diff changeset
301 \begin{funcdesc}{ssl}{sock\optional{, keyfile, certfile}}
20082
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
302 Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
303 the name of a PEM formatted file that contains your private
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
304 key. \var{certfile} is a PEM formatted certificate chain file. On
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
305 success, a new \class{SSLObject} is returned.
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
306
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20574
diff changeset
307 \warning{This does not do any certificate verification!}
20082
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
308 \end{funcdesc}
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
309
33063
90da70986407 Patch #1003700: Add socketpair function to socket module.
Dave Cole <djc@object-craft.com.au>
parents: 32429
diff changeset
310 \begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}}
90da70986407 Patch #1003700: Add socketpair function to socket module.
Dave Cole <djc@object-craft.com.au>
parents: 32429
diff changeset
311 Build a pair of connected socket objects using the given address
33280
826ad896a7a5 Patch #1015012. Improve markup and punctuation in libsocket.tex
Dave Cole <djc@object-craft.com.au>
parents: 33239
diff changeset
312 family, socket type, and protocol number. Address family, socket type,
33063
90da70986407 Patch #1003700: Add socketpair function to socket module.
Dave Cole <djc@object-craft.com.au>
parents: 32429
diff changeset
313 and protocol number are as for the \function{socket()} function above.
33280
826ad896a7a5 Patch #1015012. Improve markup and punctuation in libsocket.tex
Dave Cole <djc@object-craft.com.au>
parents: 33239
diff changeset
314 The default family is \constant{AF_UNIX} if defined on the platform;
826ad896a7a5 Patch #1015012. Improve markup and punctuation in libsocket.tex
Dave Cole <djc@object-craft.com.au>
parents: 33239
diff changeset
315 otherwise, the default is \constant{AF_INET}.
33239
fb9869044bba Updated the socketpair() docstring and documentation to explain that the
Dave Cole <djc@object-craft.com.au>
parents: 33064
diff changeset
316 Availability: \UNIX. \versionadded{2.4}
33063
90da70986407 Patch #1003700: Add socketpair function to socket module.
Dave Cole <djc@object-craft.com.au>
parents: 32429
diff changeset
317 \end{funcdesc}
90da70986407 Patch #1003700: Add socketpair function to socket module.
Dave Cole <djc@object-craft.com.au>
parents: 32429
diff changeset
318
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
319 \begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
37371
492044034a87 Bug #1460564: document that socket.fromfd() duplicates the given
Georg Brandl <georg@python.org>
parents: 37123
diff changeset
320 Duplicate the file descriptor \var{fd} (an integer as returned by a file
492044034a87 Bug #1460564: document that socket.fromfd() duplicates the given
Georg Brandl <georg@python.org>
parents: 37123
diff changeset
321 object's \method{fileno()} method) and build a socket object from the
492044034a87 Bug #1460564: document that socket.fromfd() duplicates the given
Georg Brandl <georg@python.org>
parents: 37123
diff changeset
322 result. Address family, socket type and protocol number are as for the
492044034a87 Bug #1460564: document that socket.fromfd() duplicates the given
Georg Brandl <georg@python.org>
parents: 37123
diff changeset
323 \function{socket()} function above.
492044034a87 Bug #1460564: document that socket.fromfd() duplicates the given
Georg Brandl <georg@python.org>
parents: 37123
diff changeset
324 The file descriptor should refer to a socket, but this is not
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
325 checked --- subsequent operations on the object may fail if the file
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
326 descriptor is invalid. This function is rarely needed, but can be
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
327 used to get or set socket options on a socket passed to a program as
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
328 standard input or output (such as a server started by the \UNIX{} inet
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
329 daemon). The socket is assumed to be in blocking mode.
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
330 Availability: \UNIX.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
331 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
332
4576
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
333 \begin{funcdesc}{ntohl}{x}
6783
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
334 Convert 32-bit integers from network to host byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
335 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
336 no-op; otherwise, it performs a 4-byte swap operation.
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
337 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
338
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
339 \begin{funcdesc}{ntohs}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
340 Convert 16-bit integers from network to host byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
341 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
342 no-op; otherwise, it performs a 2-byte swap operation.
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
343 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
344
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
345 \begin{funcdesc}{htonl}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
346 Convert 32-bit integers from host to network byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
347 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
348 no-op; otherwise, it performs a 4-byte swap operation.
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
349 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
350
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
351 \begin{funcdesc}{htons}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
352 Convert 16-bit integers from host to network byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
353 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
354 no-op; otherwise, it performs a 2-byte swap operation.
4576
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
355 \end{funcdesc}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
356
11291
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
357 \begin{funcdesc}{inet_aton}{ip_string}
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
358 Convert an IPv4 address from dotted-quad string format (for example,
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
359 '123.45.67.89') to 32-bit packed binary format, as a string four
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
360 characters in length. This is useful when conversing with a program
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
361 that uses the standard C library and needs objects of type
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
362 \ctype{struct in_addr}, which is the C type for the 32-bit packed
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
363 binary this function returns.
11291
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
364
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
365 If the IPv4 address string passed to this function is invalid,
11291
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
366 \exception{socket.error} will be raised. Note that exactly what is
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
367 valid depends on the underlying C implementation of
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
368 \cfunction{inet_aton()}.
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
369
21528
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
370 \function{inet_aton()} does not support IPv6, and
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
371 \function{getnameinfo()} should be used instead for IPv4/v6 dual stack
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
372 support.
11291
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
373 \end{funcdesc}
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
374
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
375 \begin{funcdesc}{inet_ntoa}{packed_ip}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
376 Convert a 32-bit packed IPv4 address (a string four characters in
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
377 length) to its standard dotted-quad string representation (for
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
378 example, '123.45.67.89'). This is useful when conversing with a
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
379 program that uses the standard C library and needs objects of type
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
380 \ctype{struct in_addr}, which is the C type for the 32-bit packed
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
381 binary data this function takes as an argument.
11291
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
382
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
383 If the string passed to this function is not exactly 4 bytes in
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
384 length, \exception{socket.error} will be raised.
21528
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
385 \function{inet_ntoa()} does not support IPv6, and
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
386 \function{getnameinfo()} should be used instead for IPv4/v6 dual stack
ac3ce1faec68 Fix the erroneous availability annotation for s.makefile() from the last
Fred Drake <fdrake@acm.org>
parents: 21521
diff changeset
387 support.
11291
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
388 \end{funcdesc}
d970af0cece9 Added documentation for inet_aton() and inet_ntoa(), from Ben
Fred Drake <fdrake@acm.org>
parents: 11178
diff changeset
389
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
390 \begin{funcdesc}{inet_pton}{address_family, ip_string}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
391 Convert an IP address from its family-specific string format to a packed,
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
392 binary format.
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
393 \function{inet_pton()} is useful when a library or network protocol calls for
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
394 an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
395 or \ctype{struct in6_addr}.
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
396
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
397 Supported values for \var{address_family} are currently
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
398 \constant{AF_INET} and \constant{AF_INET6}.
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
399 If the IP address string \var{ip_string} is invalid,
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
400 \exception{socket.error} will be raised. Note that exactly what is valid
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
401 depends on both the value of \var{address_family} and the underlying
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
402 implementation of \cfunction{inet_pton()}.
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
403
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
404 Availability: \UNIX{} (maybe not all platforms).
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
405 \versionadded{2.3}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
406 \end{funcdesc}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
407
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
408 \begin{funcdesc}{inet_ntop}{address_family, packed_ip}
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
409 Convert a packed IP address (a string of some number of characters) to
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
410 its standard, family-specific string representation (for example,
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
411 \code{'7.10.0.5'} or \code{'5aef:2b::8'})
28837
c2a05e0785f1 Fix a copy-paste error: the paragraph about inet_ntop's use was copied
Guido van Rossum <guido@python.org>
parents: 28831
diff changeset
412 \function{inet_ntop()} is useful when a library or network protocol returns
c2a05e0785f1 Fix a copy-paste error: the paragraph about inet_ntop's use was copied
Guido van Rossum <guido@python.org>
parents: 28831
diff changeset
413 an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
414 or \ctype{struct in6_addr}.
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
415
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
416 Supported values for \var{address_family} are currently
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
417 \constant{AF_INET} and \constant{AF_INET6}.
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
418 If the string \var{packed_ip} is not the correct length for the
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
419 specified address family, \exception{ValueError} will be raised. A
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
420 \exception{socket.error} is raised for errors from the call to
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
421 \function{inet_ntop()}.
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
422
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
423 Availability: \UNIX{} (maybe not all platforms).
28818
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
424 \versionadded{2.3}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
425 \end{funcdesc}
57e61588571b Patch by Jp Calderone:
Guido van Rossum <guido@python.org>
parents: 28330
diff changeset
426
28330
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
427 \begin{funcdesc}{getdefaulttimeout}{}
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
428 Return the default timeout in floating seconds for new socket objects.
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
429 A value of \code{None} indicates that new socket objects have no timeout.
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
430 When the socket module is first imported, the default is \code{None}.
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
431 \versionadded{2.3}
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
432 \end{funcdesc}
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
433
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
434 \begin{funcdesc}{setdefaulttimeout}{timeout}
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
435 Set the default timeout in floating seconds for new socket objects.
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
436 A value of \code{None} indicates that new socket objects have no timeout.
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
437 When the socket module is first imported, the default is \code{None}.
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
438 \versionadded{2.3}
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
439 \end{funcdesc}
02ce22830ab9 add descriptions of {get,set}defaulttimeout.
Skip Montanaro <skip@pobox.com>
parents: 23815
diff changeset
440
6482
d311b68754c1 socket_type ==> SocketType
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
441 \begin{datadesc}{SocketType}
5574
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
442 This is a Python type object that represents the socket object type.
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
443 It is the same as \code{type(socket(...))}.
5574
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
444 \end{datadesc}
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
445
13386
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
446
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
447 \begin{seealso}
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
448 \seemodule{SocketServer}{Classes that simplify writing network servers.}
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
449 \end{seealso}
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
450
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
451
11178
245d2b605036 Add index entry "I/O control, buffering" for makefile().
Fred Drake <fdrake@acm.org>
parents: 10836
diff changeset
452 \subsection{Socket Objects \label{socket-objects}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
453
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
454 Socket objects have the following methods. Except for
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
455 \method{makefile()} these correspond to \UNIX{} system calls
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
456 applicable to sockets.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
457
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
458 \begin{methoddesc}[socket]{accept}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
459 Accept a connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
460 The socket must be bound to an address and listening for connections.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
461 The return value is a pair \code{(\var{conn}, \var{address})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
462 where \var{conn} is a \emph{new} socket object usable to send and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
463 receive data on the connection, and \var{address} is the address bound
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
464 to the socket on the other end of the connection.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
465 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
466
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
467 \begin{methoddesc}[socket]{bind}{address}
1682
2bcddc905da0 clarify the meaning of address for those methods that or return addresses
Guido van Rossum <guido@python.org>
parents: 1567
diff changeset
468 Bind the socket to \var{address}. The socket must not already be bound.
12230
7bf8b10ce2ab Added notes about the eventual disappearance of two-parameter bind(),
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
469 (The format of \var{address} depends on the address family --- see
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20574
diff changeset
470 above.) \note{This method has historically accepted a pair
12230
7bf8b10ce2ab Added notes about the eventual disappearance of two-parameter bind(),
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
471 of parameters for \constant{AF_INET} addresses instead of only a
31862
dbd3fc214b66 #928751, fix typos in socket doc
Neal Norwitz <nnorwitz@gmail.com>
parents: 31432
diff changeset
472 tuple. This was never intentional and is no longer available in
dbd3fc214b66 #928751, fix typos in socket doc
Neal Norwitz <nnorwitz@gmail.com>
parents: 31432
diff changeset
473 Python 2.0 and later.}
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
474 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
475
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
476 \begin{methoddesc}[socket]{close}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
477 Close the socket. All future operations on the socket object will fail.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
478 The remote end will receive no more data (after queued data is flushed).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
479 Sockets are automatically closed when they are garbage-collected.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
480 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
481
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
482 \begin{methoddesc}[socket]{connect}{address}
1682
2bcddc905da0 clarify the meaning of address for those methods that or return addresses
Guido van Rossum <guido@python.org>
parents: 1567
diff changeset
483 Connect to a remote socket at \var{address}.
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
484 (The format of \var{address} depends on the address family --- see
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20574
diff changeset
485 above.) \note{This method has historically accepted a pair
12230
7bf8b10ce2ab Added notes about the eventual disappearance of two-parameter bind(),
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
486 of parameters for \constant{AF_INET} addresses instead of only a
15800
3a260274bcc6 SourceForge patch #103140, checked in at fdrake's invitation. Minor fixes and
Eric S. Raymond <esr@thyrsus.com>
parents: 15146
diff changeset
487 tuple. This was never intentional and is no longer available in
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20574
diff changeset
488 Python 2.0 and later.}
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
489 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
490
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
491 \begin{methoddesc}[socket]{connect_ex}{address}
6804
e224c41bdac6 Fix a little mess (Likecode{...} -> Like \code{...}) in recently added text.
Guido van Rossum <guido@python.org>
parents: 6783
diff changeset
492 Like \code{connect(\var{address})}, but return an error indicator
10836
efd1573a4b03 Updated connect_ex() documentation based on comments in the newgroup
Fred Drake <fdrake@acm.org>
parents: 10655
diff changeset
493 instead of raising an exception for errors returned by the C-level
efd1573a4b03 Updated connect_ex() documentation based on comments in the newgroup
Fred Drake <fdrake@acm.org>
parents: 10655
diff changeset
494 \cfunction{connect()} call (other problems, such as ``host not found,''
efd1573a4b03 Updated connect_ex() documentation based on comments in the newgroup
Fred Drake <fdrake@acm.org>
parents: 10655
diff changeset
495 can still raise exceptions). The error indicator is \code{0} if the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
496 operation succeeded, otherwise the value of the \cdata{errno}
21521
e0a5d16a9cb9 Add notes that fromfd() and s.makefile() are Unix-specific.
Fred Drake <fdrake@acm.org>
parents: 21213
diff changeset
497 variable. This is useful to support, for example, asynchronous connects.
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20574
diff changeset
498 \note{This method has historically accepted a pair of
12230
7bf8b10ce2ab Added notes about the eventual disappearance of two-parameter bind(),
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
499 parameters for \constant{AF_INET} addresses instead of only a tuple.
31862
dbd3fc214b66 #928751, fix typos in socket doc
Neal Norwitz <nnorwitz@gmail.com>
parents: 31432
diff changeset
500 This was never intentional and is no longer available in Python
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 20574
diff changeset
501 2.0 and later.}
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
502 \end{methoddesc}
6587
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
503
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
504 \begin{methoddesc}[socket]{fileno}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
505 Return the socket's file descriptor (a small integer). This is useful
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
506 with \function{select.select()}.
30048
2cfaca62a990 Add note about fileno not being usable as a normal file descriptor in Windows.
Brett Cannon <bcannon@gmail.com>
parents: 29949
diff changeset
507
2cfaca62a990 Add note about fileno not being usable as a normal file descriptor in Windows.
Brett Cannon <bcannon@gmail.com>
parents: 29949
diff changeset
508 Under Windows the small integer returned by this method cannot be used where
2cfaca62a990 Add note about fileno not being usable as a normal file descriptor in Windows.
Brett Cannon <bcannon@gmail.com>
parents: 29949
diff changeset
509 a file descriptor can be used (such as \function{os.fdopen()}). \UNIX{} does
2cfaca62a990 Add note about fileno not being usable as a normal file descriptor in Windows.
Brett Cannon <bcannon@gmail.com>
parents: 29949
diff changeset
510 not have this limitation.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
511 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
512
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
513 \begin{methoddesc}[socket]{getpeername}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
514 Return the remote address to which the socket is connected. This is
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
515 useful to find out the port number of a remote IPv4/v6 socket, for instance.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2447
diff changeset
516 (The format of the address returned depends on the address family ---
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
517 see above.) On some systems this function is not supported.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
518 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
519
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
520 \begin{methoddesc}[socket]{getsockname}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
521 Return the socket's own address. This is useful to find out the port
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
522 number of an IPv4/v6 socket, for instance.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2447
diff changeset
523 (The format of the address returned depends on the address family ---
1682
2bcddc905da0 clarify the meaning of address for those methods that or return addresses
Guido van Rossum <guido@python.org>
parents: 1567
diff changeset
524 see above.)
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
525 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
526
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
527 \begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
528 Return the value of the given socket option (see the \UNIX{} man page
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
529 \manpage{getsockopt}{2}). The needed symbolic constants
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
530 (\constant{SO_*} etc.) are defined in this module. If \var{buflen}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
531 is absent, an integer option is assumed and its integer value
2447
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
532 is returned by the function. If \var{buflen} is present, it specifies
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
533 the maximum length of the buffer used to receive the option in, and
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
534 this buffer is returned as a string. It is up to the caller to decode
2447
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
535 the contents of the buffer (see the optional built-in module
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
536 \refmodule{struct} for a way to decode C structures encoded as strings).
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
537 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
538
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
539 \begin{methoddesc}[socket]{listen}{backlog}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
540 Listen for connections made to the socket. The \var{backlog} argument
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
541 specifies the maximum number of queued connections and should be at
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
542 least 1; the maximum value is system-dependent (usually 5).
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
543 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
544
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
545 \begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
546 Return a \dfn{file object} associated with the socket. (File objects
11178
245d2b605036 Add index entry "I/O control, buffering" for makefile().
Fred Drake <fdrake@acm.org>
parents: 10836
diff changeset
547 are described in \ref{bltin-file-objects}, ``File Objects.'')
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
548 The file object references a \cfunction{dup()}ped version of the
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
549 socket file descriptor, so the file object and socket object may be
11178
245d2b605036 Add index entry "I/O control, buffering" for makefile().
Fred Drake <fdrake@acm.org>
parents: 10836
diff changeset
550 closed or garbage-collected independently.
38553
464265c1d08b [Bug #1475554] Strengthen text to say 'must' instead of 'should'
Andrew M. Kuchling <amk@amk.ca>
parents: 37371
diff changeset
551 The socket must be in blocking mode.
11178
245d2b605036 Add index entry "I/O control, buffering" for makefile().
Fred Drake <fdrake@acm.org>
parents: 10836
diff changeset
552 \index{I/O control!buffering}The optional \var{mode}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
553 and \var{bufsize} arguments are interpreted the same way as by the
20574
5af6c89c8cb7 When stating that some parameters to makefile() are similar to the open()
Fred Drake <fdrake@acm.org>
parents: 20375
diff changeset
554 built-in \function{file()} function; see ``Built-in Functions''
5af6c89c8cb7 When stating that some parameters to makefile() are similar to the open()
Fred Drake <fdrake@acm.org>
parents: 20375
diff changeset
555 (section \ref{built-in-funcs}) for more information.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
556 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
557
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
558 \begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
559 Receive data from the socket. The return value is a string representing
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
560 the data received. The maximum amount of data to be received
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
561 at once is specified by \var{bufsize}. See the \UNIX{} manual page
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
562 \manpage{recv}{2} for the meaning of the optional argument
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
563 \var{flags}; it defaults to zero.
36126
23eb8677bdad Bug #756104: document that bufsize in socket.recv() should be small
Georg Brandl <georg@python.org>
parents: 35671
diff changeset
564 \note{For best match with hardware and network realities, the value of
23eb8677bdad Bug #756104: document that bufsize in socket.recv() should be small
Georg Brandl <georg@python.org>
parents: 35671
diff changeset
565 \var{bufsize} should be a relatively small power of 2, for example, 4096.}
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
566 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
567
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
568 \begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
569 Receive data from the socket. The return value is a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
570 \code{(\var{string}, \var{address})} where \var{string} is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
571 representing the data received and \var{address} is the address of the
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
572 socket sending the data. The optional \var{flags} argument has the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
573 same meaning as for \method{recv()} above.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2447
diff changeset
574 (The format of \var{address} depends on the address family --- see above.)
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
575 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
576
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
577 \begin{methoddesc}[socket]{send}{string\optional{, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
578 Send data to the socket. The socket must be connected to a remote
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
579 socket. The optional \var{flags} argument has the same meaning as for
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
580 \method{recv()} above. Returns the number of bytes sent.
21213
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
581 Applications are responsible for checking that all data has been sent;
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
582 if only some of the data was transmitted, the application needs to
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
583 attempt delivery of the remaining data.
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
584 \end{methoddesc}
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
585
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
586 \begin{methoddesc}[socket]{sendall}{string\optional{, flags}}
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
587 Send data to the socket. The socket must be connected to a remote
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
588 socket. The optional \var{flags} argument has the same meaning as for
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
589 \method{recv()} above. Unlike \method{send()}, this method continues
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
590 to send data from \var{string} until either all data has been sent or
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
591 an error occurs. \code{None} is returned on success. On error, an
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
592 exception is raised, and there is no way to determine how much data,
3b09ea723ece Added documentation of the sendall() method, and a note to the send() method
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
593 if any, was successfully sent.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
594 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
595
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
596 \begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
597 Send data to the socket. The socket should not be connected to a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
598 remote socket, since the destination socket is specified by
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
599 \var{address}. The optional \var{flags} argument has the same
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
600 meaning as for \method{recv()} above. Return the number of bytes sent.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2447
diff changeset
601 (The format of \var{address} depends on the address family --- see above.)
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
602 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
603
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
604 \begin{methoddesc}[socket]{setblocking}{flag}
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
605 Set blocking or non-blocking mode of the socket: if \var{flag} is 0,
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
606 the socket is set to non-blocking, else to blocking mode. Initially
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
607 all sockets are in blocking mode. In non-blocking mode, if a
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
608 \method{recv()} call doesn't find any data, or if a
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
609 \method{send()} call can't immediately dispose of the data, a
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
610 \exception{error} exception is raised; in blocking mode, the calls
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
611 block until they can proceed.
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
612 \code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)};
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
613 \code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
614 \end{methoddesc}
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
615
23717
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
616 \begin{methoddesc}[socket]{settimeout}{value}
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
617 Set a timeout on blocking socket operations. The \var{value} argument
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
618 can be a nonnegative float expressing seconds, or \code{None}.
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
619 If a float is
29665
d7626b80de95 SF patch #760257: add socket.timeout exception
Raymond Hettinger <python@rcn.com>
parents: 29560
diff changeset
620 given, subsequent socket operations will raise an \exception{timeout}
23728
5562a499fb7f Clarify the interaction between blocking and timeouts. Explain that
Guido van Rossum <guido@python.org>
parents: 23720
diff changeset
621 exception if the timeout period \var{value} has elapsed before the
5562a499fb7f Clarify the interaction between blocking and timeouts. Explain that
Guido van Rossum <guido@python.org>
parents: 23720
diff changeset
622 operation has completed. Setting a timeout of \code{None} disables
5562a499fb7f Clarify the interaction between blocking and timeouts. Explain that
Guido van Rossum <guido@python.org>
parents: 23720
diff changeset
623 timeouts on socket operations.
29560
a296214d2ebb SF #757229, fix libsocket.tex typo
Neal Norwitz <nnorwitz@gmail.com>
parents: 28844
diff changeset
624 \code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)};
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
625 \code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}.
23720
b062085c1ff2 Add version info, and fix another typo and wording spotted by /F. I think this is what he meant. :-)
Neal Norwitz <nnorwitz@gmail.com>
parents: 23719
diff changeset
626 \versionadded{2.3}
23717
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
627 \end{methoddesc}
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
628
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
629 \begin{methoddesc}[socket]{gettimeout}{}
37069
dd49847a60d3 RFE #567972: Socket objects' family, type and proto properties are
Georg Brandl <georg@python.org>
parents: 36290
diff changeset
630 Return the timeout in floating seconds associated with socket
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
631 operations, or \code{None} if no timeout is set. This reflects
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
632 the last call to \method{setblocking()} or \method{settimeout()}.
23720
b062085c1ff2 Add version info, and fix another typo and wording spotted by /F. I think this is what he meant. :-)
Neal Norwitz <nnorwitz@gmail.com>
parents: 23719
diff changeset
633 \versionadded{2.3}
23717
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
634 \end{methoddesc}
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
635
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
636 Some notes on socket blocking and timeouts: A socket object can be in
29949
ad09687aaaa0 SF bug #774411: Typo in socket documentation
Raymond Hettinger <python@rcn.com>
parents: 29665
diff changeset
637 one of three modes: blocking, non-blocking, or timeout. Sockets are
23815
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
638 always created in blocking mode. In blocking mode, operations block
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
639 until complete. In non-blocking mode, operations fail (with an error
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
640 that is unfortunately system-dependent) if they cannot be completed
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
641 immediately. In timeout mode, operations fail if they cannot be
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
642 completed within the timeout specified for the socket. The
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
643 \method{setblocking()} method is simply a shorthand for certain
203d1412a7e8 Major overhaul of timeout sockets:
Guido van Rossum <guido@python.org>
parents: 23730
diff changeset
644 \method{settimeout()} calls.
23717
77154cef29d1 SF patch 555085 (timeout socket implementation) by Michael Gilfix.
Guido van Rossum <guido@python.org>
parents: 21528
diff changeset
645
23730
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
646 Timeout mode internally sets the socket in non-blocking mode. The
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
647 blocking and timeout modes are shared between file descriptors and
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
648 socket objects that refer to the same network endpoint. A consequence
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
649 of this is that file objects returned by the \method{makefile()}
38553
464265c1d08b [Bug #1475554] Strengthen text to say 'must' instead of 'should'
Andrew M. Kuchling <amk@amk.ca>
parents: 37371
diff changeset
650 method must only be used when the socket is in blocking mode; in
23730
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
651 timeout or non-blocking mode file operations that cannot be completed
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
652 immediately will fail.
af8d40e4c377 Clarify the interaction between timeout/non-blocking mode, makefile
Guido van Rossum <guido@python.org>
parents: 23729
diff changeset
653
31181
e5d97ab710a2 After hearing from someone who gave up on timeout sockets due to a
Guido van Rossum <guido@python.org>
parents: 31027
diff changeset
654 Note that the \method{connect()} operation is subject to the timeout
e5d97ab710a2 After hearing from someone who gave up on timeout sockets due to a
Guido van Rossum <guido@python.org>
parents: 31027
diff changeset
655 setting, and in general it is recommended to call
e5d97ab710a2 After hearing from someone who gave up on timeout sockets due to a
Guido van Rossum <guido@python.org>
parents: 31027
diff changeset
656 \method{settimeout()} before calling \method{connect()}.
e5d97ab710a2 After hearing from someone who gave up on timeout sockets due to a
Guido van Rossum <guido@python.org>
parents: 31027
diff changeset
657
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
658 \begin{methoddesc}[socket]{setsockopt}{level, optname, value}
13178
d37374552a15 Say "manual page", not "man page", when referring to the Unix manual.
Fred Drake <fdrake@acm.org>
parents: 12571
diff changeset
659 Set the value of the given socket option (see the \UNIX{} manual page
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
660 \manpage{setsockopt}{2}). The needed symbolic constants are defined in
28844
cd82253f20b7 - add availability statements for some of the new APIs
Fred Drake <fdrake@acm.org>
parents: 28837
diff changeset
661 the \module{socket} module (\constant{SO_*} etc.). The value can be an
2447
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
662 integer or a string representing a buffer. In the latter case it is
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
663 up to the caller to ensure that the string contains the proper bits
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
664 (see the optional built-in module
10655
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
665 \refmodule{struct}\refbimodindex{struct} for a way to encode C
299bf53e6861 Logical markup nits.
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
666 structures as strings).
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
667 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
668
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
669 \begin{methoddesc}[socket]{shutdown}{how}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
670 Shut down one or both halves of the connection. If \var{how} is
31027
bf038986cb8f Patch #849595: Add socket.shutdown() constants.
Martin v. Löwis <martin@v.loewis.de>
parents: 30048
diff changeset
671 \constant{SHUT_RD}, further receives are disallowed. If \var{how} is \constant{SHUT_WR},
bf038986cb8f Patch #849595: Add socket.shutdown() constants.
Martin v. Löwis <martin@v.loewis.de>
parents: 30048
diff changeset
672 further sends are disallowed. If \var{how} is \constant{SHUT_RDWR}, further sends
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
673 and receives are disallowed.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
674 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
675
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
676 Note that there are no methods \method{read()} or \method{write()};
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
677 use \method{recv()} and \method{send()} without \var{flags} argument
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
678 instead.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
679
13386
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
680
37123
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
681 Socket objects also have these (read-only) attributes that correspond
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
682 to the values given to the \class{socket} constructor.
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
683
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
684 \begin{memberdesc}[socket]{family}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
685 The socket family.
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
686 \versionadded{2.5}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
687 \end{memberdesc}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
688
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
689 \begin{memberdesc}[socket]{type}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
690 The socket type.
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
691 \versionadded{2.5}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
692 \end{memberdesc}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
693
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
694 \begin{memberdesc}[socket]{proto}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
695 The socket protocol.
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
696 \versionadded{2.5}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
697 \end{memberdesc}
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
698
251ecec04f1b Correct API design mistake from rev. 43126: make socket attributes readonly properties.
Georg Brandl <georg@python.org>
parents: 37069
diff changeset
699
20082
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
700 \subsection{SSL Objects \label{ssl-objects}}
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
701
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
702 SSL objects have the following methods.
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
703
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
704 \begin{methoddesc}{write}{s}
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
705 Writes the string \var{s} to the on the object's SSL connection.
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
706 The return value is the number of bytes written.
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
707 \end{methoddesc}
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
708
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
709 \begin{methoddesc}{read}{\optional{n}}
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
710 If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
711 read until EOF. The return value is a string of the bytes read.
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
712 \end{methoddesc}
18df32f6cea1 Added documentation for the SSL interface, contributed by Gerhard Häring.
Fred Drake <fdrake@acm.org>
parents: 18995
diff changeset
713
13386
3f08bedc1c26 Clean up markup to be more like recommended practice; only small changes
Fred Drake <fdrake@acm.org>
parents: 13178
diff changeset
714 \subsection{Example \label{socket-example}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
715
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
716 Here are four minimal example programs using the TCP/IP protocol:\ a
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
717 server that echoes all data that it receives back (servicing only one
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
718 client), and a client using it. Note that a server must perform the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
719 sequence \function{socket()}, \method{bind()}, \method{listen()},
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
720 \method{accept()} (possibly repeating the \method{accept()} to service
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
721 more than one client), while a client only needs the sequence
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
722 \function{socket()}, \method{connect()}. Also note that the server
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
723 does not \method{send()}/\method{recv()} on the
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
724 socket it is listening on but on the new socket returned by
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
725 \method{accept()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
726
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
727 The first two examples support IPv4 only.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
728
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
729 \begin{verbatim}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
730 # Echo server program
15146
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
731 import socket
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
732
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
733 HOST = '' # Symbolic name meaning the local host
15146
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
734 PORT = 50007 # Arbitrary non-privileged port
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
735 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
12571
8bcd14313c11 Someone found the examples of poor practice on socket addresses!
Fred Drake <fdrake@acm.org>
parents: 12230
diff changeset
736 s.bind((HOST, PORT))
1567
dddcba2038bc adapt to min value of 1 for listen() backlog argument
Guido van Rossum <guido@python.org>
parents: 1483
diff changeset
737 s.listen(1)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
738 conn, addr = s.accept()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
739 print 'Connected by', addr
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
740 while 1:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
741 data = conn.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
742 if not data: break
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
743 conn.send(data)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
744 conn.close()
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
745 \end{verbatim}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
746
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
747 \begin{verbatim}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
748 # Echo client program
15146
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
749 import socket
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
750
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
751 HOST = 'daring.cwi.nl' # The remote host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
752 PORT = 50007 # The same port as used by the server
15146
5cf0a02a574b Revise the examples not to use the "from socket import *", and adjust
Fred Drake <fdrake@acm.org>
parents: 14437
diff changeset
753 s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
12571
8bcd14313c11 Someone found the examples of poor practice on socket addresses!
Fred Drake <fdrake@acm.org>
parents: 12230
diff changeset
754 s.connect((HOST, PORT))
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
755 s.send('Hello, world')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
756 data = s.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
757 s.close()
32231
525abc66bcc2 avoid backticks in examples; use repr() instead
Fred Drake <fdrake@acm.org>
parents: 31976
diff changeset
758 print 'Received', repr(data)
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
759 \end{verbatim}
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
760
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
761 The next two examples are identical to the above two, but support both
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
762 IPv4 and IPv6.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
763 The server side will listen to the first address family available
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
764 (it should listen to both instead).
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
765 On most of IPv6-ready systems, IPv6 will take precedence
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
766 and the server may not accept IPv4 traffic.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
767 The client side will try to connect to the all addresses returned as a result
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
768 of the name resolution, and sends traffic to the first one connected
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
769 successfully.
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
770
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
771 \begin{verbatim}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
772 # Echo server program
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
773 import socket
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
774 import sys
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
775
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
776 HOST = '' # Symbolic name meaning the local host
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
777 PORT = 50007 # Arbitrary non-privileged port
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
778 s = None
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
779 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
780 af, socktype, proto, canonname, sa = res
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
781 try:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
782 s = socket.socket(af, socktype, proto)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
783 except socket.error, msg:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
784 s = None
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
785 continue
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
786 try:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
787 s.bind(sa)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
788 s.listen(1)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
789 except socket.error, msg:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
790 s.close()
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
791 s = None
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
792 continue
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
793 break
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
794 if s is None:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
795 print 'could not open socket'
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
796 sys.exit(1)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
797 conn, addr = s.accept()
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
798 print 'Connected by', addr
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
799 while 1:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
800 data = conn.recv(1024)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
801 if not data: break
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
802 conn.send(data)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
803 conn.close()
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
804 \end{verbatim}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
805
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
806 \begin{verbatim}
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
807 # Echo client program
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
808 import socket
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
809 import sys
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
810
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
811 HOST = 'daring.cwi.nl' # The remote host
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
812 PORT = 50007 # The same port as used by the server
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
813 s = None
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
814 for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
815 af, socktype, proto, canonname, sa = res
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
816 try:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
817 s = socket.socket(af, socktype, proto)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
818 except socket.error, msg:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
819 s = None
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
820 continue
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
821 try:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
822 s.connect(sa)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
823 except socket.error, msg:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
824 s.close()
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
825 s = None
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
826 continue
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
827 break
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
828 if s is None:
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
829 print 'could not open socket'
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
830 sys.exit(1)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
831 s.send('Hello, world')
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
832 data = s.recv(1024)
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
833 s.close()
32231
525abc66bcc2 avoid backticks in examples; use repr() instead
Fred Drake <fdrake@acm.org>
parents: 31976
diff changeset
834 print 'Received', repr(data)
18995
805090ce328a Document IPv6 changes. Contributed by itojun.
Martin v. Löwis <martin@v.loewis.de>
parents: 15800
diff changeset
835 \end{verbatim}