Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsocket.tex @ 8918:acfffe14628e legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New section header style. Fix up a few synopses.
author Fred Drake <fdrake@acm.org>
date Mon, 10 Aug 1998 19:42:37 +0000
parents a9eb265d2f57
children 299bf53e6861
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} ---
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8880
diff changeset
2 Low-level networking interface.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
3 \declaremodule{builtin}{socket}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4
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.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 It is available on \UNIX{} systems that support this interface.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 For an introduction to socket programming (in C), see the following
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 papers: \emph{An Introductory 4.3BSD Interprocess Communication
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 Communication Tutorial}, by Samuel J. Leffler et al, both in the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 \UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 and PS1:8). The \UNIX{} manual pages for the various socket-related
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
17 system calls are also a valuable source of information on the details of
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 socket semantics.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 The Python interface is a straightforward transliteration of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 \UNIX{} system call and library interface for sockets to Python's
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
22 object-oriented style: the \function{socket()} function returns a
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 \dfn{socket object} whose methods implement the various socket system
4882
8d17d552d0ec very minor typo
Barry Warsaw <barry@python.org>
parents: 4784
diff changeset
24 calls. Parameter types are somewhat higher-level than in the C
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
25 interface: as with \method{read()} and \method{write()} operations on
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
26 Python files, buffer allocation on receive operations is automatic,
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
27 and buffer length is implicit on send operations.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 Socket addresses are represented as a single string for the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
30 \constant{AF_UNIX} address family and as a pair
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
31 \code{(\var{host}, \var{port})} for the \constant{AF_INET} address
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
32 family, where \var{host} is a string representing
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 either a hostname in Internet domain notation like
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 \code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'},
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 and \var{port} is an integral port number. Other address families are
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 currently not supported. The address format required by a particular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 socket object is automatically selected based on the address family
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 specified when the socket object was created.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
5461
0ded63bcf5de Document "" and "<broadcast>".
Guido van Rossum <guido@python.org>
parents: 4929
diff changeset
40 For IP addresses, two special forms are accepted instead of a host
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
41 address: the empty string represents \constant{INADDR_ANY}, and the string
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
42 \code{"<broadcast>"} represents \constant{INADDR_BROADCAST}.
5461
0ded63bcf5de Document "" and "<broadcast>".
Guido van Rossum <guido@python.org>
parents: 4929
diff changeset
43
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 All errors raise exceptions. The normal exceptions for invalid
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 argument types and out-of-memory conditions can be raised; errors
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 related to socket or address semantics raise the error \code{socket.error}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
48 Non-blocking mode is supported through the \code{setblocking()}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
49 method.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
51 The module \module{socket} exports the following constants and functions:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
53
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 This exception is raised for socket- or address-related errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 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
57 pair \code{(\var{errno}, \var{string})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 representing an error returned by a system
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
59 call, similar to the value accompanying \code{os.error}.
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
60 See the module \module{errno}\refbimodindex{errno}, which contains
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
61 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
62 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \begin{datadesc}{AF_UNIX}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \dataline{AF_INET}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 These constants represent the address (and protocol) families,
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
67 used for the first argument to \function{socket()}. If the
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
68 \constant{AF_UNIX} constant is not defined then this protocol is
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
69 unsupported.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \begin{datadesc}{SOCK_STREAM}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 \dataline{SOCK_DGRAM}
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
74 \dataline{SOCK_RAW}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
75 \dataline{SOCK_RDM}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
76 \dataline{SOCK_SEQPACKET}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 These constants represent the socket types,
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
78 used for the second argument to \function{socket()}.
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
79 (Only \constant{SOCK_STREAM} and
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
80 \constant{SOCK_DGRAM} appear to be generally useful.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
2354
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
83 \begin{datadesc}{SO_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
84 \dataline{SOMAXCONN}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
85 \dataline{MSG_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
86 \dataline{SOL_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
87 \dataline{IPPROTO_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
88 \dataline{IPPORT_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
89 \dataline{INADDR_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
90 \dataline{IP_*}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
91 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
92 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
93 They are generally used in arguments to the \method{setsockopt()} and
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
94 \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
95 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
96 for a few symbols, default values are provided.
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
97 \end{datadesc}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
98
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 \begin{funcdesc}{gethostbyname}{hostname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 Translate a host name to IP address format. The IP address is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 returned as a string, e.g., \code{'100.50.200.5'}. If the host name
8880
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
102 is an IP address itself it is returned unchanged. See
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
103 \code{gethostbyname_ex} for a more complete interface.
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
104 \end{funcdesc}
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
105
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
106 \begin{funcdesc}{gethostbyname_ex}{hostname}
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
107 Translate a host name to IP address format, extended interface.
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
108 Return a triple \code{(hostname, aliaslist, ipaddrlist)} where
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
109 \code{hostname} is the primary host name responding to the given
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
110 \var{ip_address}, \code{aliaslist} is a (possibly empty) list of
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
111 alternative host names for the same address, and \code{ipaddrlist} is
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
112 a list of IP addresses for the same interface on the same
a9eb265d2f57 Document gethostbyname_ex().
Guido van Rossum <guido@python.org>
parents: 8716
diff changeset
113 host (often but not always a single address).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
116 \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
117 Return a string containing the hostname of the machine where
907605320a5f Lots of small corrections by Andrew Kuchling (plus all new rotor docs)
Guido van Rossum <guido@python.org>
parents: 1759
diff changeset
118 the Python interpreter is currently executing. If you want to know the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
119 current machine's IP address, use \code{gethostbyname(gethostname())}.
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
120 Note: \function{gethostname()} doesn't always return the fully qualified
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
121 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
122 (see below).
2064
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
123 \end{funcdesc}
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
124
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
125 \begin{funcdesc}{gethostbyaddr}{ip_address}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
126 Return a triple \code{(\var{hostname}, \var{aliaslist},
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
127 \var{ipaddrlist})} where \var{hostname} is the primary host name
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
128 responding to the given \var{ip_address}, \var{aliaslist} is a
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
129 (possibly empty) list of alternative host names for the same address,
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
130 and \var{ipaddrlist} is a list of IP addresses for the same interface
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
131 on the same host (most likely containing only a single address).
4929
5126d4b819e9 Added warning that gethostname() doesn't always return fqdn, and show
Guido van Rossum <guido@python.org>
parents: 4882
diff changeset
132 To find the fully qualified domain name, check \var{hostname} and the
5126d4b819e9 Added warning that gethostname() doesn't always return fqdn, and show
Guido van Rossum <guido@python.org>
parents: 4882
diff changeset
133 items of \var{aliaslist} for an entry containing at least one period.
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
134 \end{funcdesc}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
135
4784
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
136 \begin{funcdesc}{getprotobyname}{protocolname}
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
137 Translate an Internet protocol name (e.g. \code{'icmp'}) to a constant
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
138 suitable for passing as the (optional) third argument to the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
139 \function{socket()} function. This is usually only needed for sockets
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
140 opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
141 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
142 omitted or zero.
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
143 \end{funcdesc}
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
144
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
145 \begin{funcdesc}{getservbyname}{servicename, protocolname}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 Translate an Internet service name and protocol name to a port number
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 for that service. The protocol name should be \code{'tcp'} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 \code{'udp'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
150
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
151 \begin{funcdesc}{socket}{family, type\optional{, proto}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 Create a new socket using the given address family, socket type and
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
153 protocol number. The address family should be \constant{AF_INET} or
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
154 \constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM},
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
155 \constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 The protocol number is usually zero and may be omitted in that case.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
158
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
159 \begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
160 Build a socket object from an existing file descriptor (an integer as
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
161 returned by a file object's \method{fileno()} method). Address family,
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 socket type and protocol number are as for the \code{socket} function
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
163 above. The file descriptor should refer to a socket, but this is not
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 checked --- subsequent operations on the object may fail if the file
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
165 descriptor is invalid. This function is rarely needed, but can be
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 used to get or set socket options on a socket passed to a program as
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
167 standard input or output (e.g.\ a server started by the \UNIX{} inet
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 daemon).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
170
4576
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
171 \begin{funcdesc}{ntohl}{x}
6783
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
172 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
173 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
174 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
175 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
176
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
177 \begin{funcdesc}{ntohs}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
178 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
179 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
180 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
181 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
182
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
183 \begin{funcdesc}{htonl}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
184 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
185 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
186 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
187 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
188
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
189 \begin{funcdesc}{htons}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
190 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
191 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
192 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
193 \end{funcdesc}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
194
6482
d311b68754c1 socket_type ==> SocketType
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
195 \begin{datadesc}{SocketType}
5574
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
196 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
197 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
198 \end{datadesc}
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
199
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
200 \subsection{Socket Objects}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
201
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
202 Socket objects have the following methods. Except for
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
203 \method{makefile()} these correspond to \UNIX{} system calls
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
204 applicable to sockets.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
206 \begin{methoddesc}[socket]{accept}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 Accept a connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
208 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
209 The return value is a pair \code{(\var{conn}, \var{address})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 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
211 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
212 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
213 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
215 \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
216 Bind the socket to \var{address}. The socket must not already be bound.
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
217 (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
218 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
220 \begin{methoddesc}[socket]{close}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 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
222 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
223 Sockets are automatically closed when they are garbage-collected.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
224 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
226 \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
227 Connect to a remote socket at \var{address}.
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
228 (The format of \var{address} depends on the address family --- see
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
229 above.)
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
230 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
231
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
232 \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
233 Like \code{connect(\var{address})}, but return an error indicator
6587
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
234 instead of raising an exception. The error indicator is 0 if the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
235 operation succeeded, otherwise the value of the \cdata{errno}
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
236 variable. This is useful, e.g., for asynchronous connects.
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
237 \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
238
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
239 \begin{methoddesc}[socket]{fileno}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
240 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
241 with \function{select.select()}.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
242 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
243
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
244 \begin{methoddesc}[socket]{getpeername}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
245 Return the remote address to which the socket is connected. This is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
246 useful to find out the port number of a remote IP 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
247 (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
248 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
249 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
250
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
251 \begin{methoddesc}[socket]{getsockname}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
252 Return the socket's own address. This is useful to find out the port
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
253 number of an IP 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
254 (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
255 see above.)
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
256 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
257
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
258 \begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
259 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
260 \manpage{getsockopt}{2}). The needed symbolic constants
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
261 (\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
262 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
263 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
264 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
265 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
266 the contents of the buffer (see the optional built-in module
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
267 \module{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
268 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
269
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
270 \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
271 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
272 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
273 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
274 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
275
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
276 \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
277 Return a \dfn{file object} associated with the socket. (File objects
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
278 were described earlier in \ref{bltin-file-objects}, ``File Objects.'')
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
279 The file object references a \cfunction{dup()}ped version of the
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
280 socket file descriptor, so the file object and socket object may be
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
281 closed or garbage-collected independently. The optional \var{mode}
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
282 and \var{bufsize} arguments are interpreted the same way as by the
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
283 built-in \function{open()} function.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
284 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
285
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
286 \begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
287 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
288 the data received. The maximum amount of data to be received
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
289 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
290 \manpage{recv}{2} for the meaning of the optional argument
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
291 \var{flags}; it defaults to zero.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
292 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
294 \begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
295 Receive data from the socket. The return value is a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
296 \code{(\var{string}, \var{address})} where \var{string} is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
297 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
298 socket sending the data. The optional \var{flags} argument has the
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
299 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
300 (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
301 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
302
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
303 \begin{methoddesc}[socket]{send}{string\optional{, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
304 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
305 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
306 \method{recv()} above. Returns the number of bytes sent.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
307 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
308
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
309 \begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
310 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
311 remote socket, since the destination socket is specified by
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
312 \var{address}. The optional \var{flags} argument has the same
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
313 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
314 (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
315 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
316
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
317 \begin{methoddesc}[socket]{setblocking}{flag}
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
318 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
319 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
320 all sockets are in blocking mode. In non-blocking mode, if a
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
321 \method{recv()} call doesn't find any data, or if a \code{send} call can't
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
322 immediately dispose of the data, a \exception{error} exception is
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
323 raised; in blocking mode, the calls block until they can proceed.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
324 \end{methoddesc}
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
325
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
326 \begin{methoddesc}[socket]{setsockopt}{level, optname, value}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
327 Set 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
328 \manpage{setsockopt}{2}). The needed symbolic constants are defined in
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
329 the \module{socket} module (\code{SO_*} etc.). The value can be an
2447
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
330 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
331 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
332 (see the optional built-in module
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
333 \module{struct}\refbimodindex{struct} for a way to encode C structures
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
334 as strings).
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
335 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
336
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
337 \begin{methoddesc}[socket]{shutdown}{how}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
338 Shut down one or both halves of the connection. If \var{how} is
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
339 \code{0}, further receives are disallowed. If \var{how} is \code{1},
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
340 further sends are disallowed. If \var{how} is \code{2}, further sends
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
341 and receives are disallowed.
7823
0575d5a17218 Use {methoddesc} as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
342 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
343
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
344 Note that there are no methods \method{read()} or \method{write()};
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
345 use \method{recv()} and \method{send()} without \var{flags} argument
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
346 instead.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
347
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
348 \subsection{Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
349 \nodename{Socket Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
350
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
351 Here are two minimal example programs using the TCP/IP protocol:\ a
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
352 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
353 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
354 sequence \function{socket()}, \method{bind()}, \method{listen()},
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
355 \method{accept()} (possibly repeating the \method{accept()} to service
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
356 more than one client), while a client only needs the sequence
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
357 \function{socket()}, \method{connect()}. Also note that the server
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
358 does not \method{send()}/\method{recv()} on the
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
359 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
360 \method{accept()}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
361
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
362 \begin{verbatim}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
363 # Echo server program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
364 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
365 HOST = '' # Symbolic name meaning the local host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
366 PORT = 50007 # Arbitrary non-privileged server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
367 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
368 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
369 s.listen(1)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
370 conn, addr = s.accept()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
371 print 'Connected by', addr
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
372 while 1:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
373 data = conn.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
374 if not data: break
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
375 conn.send(data)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
376 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
377 \end{verbatim}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
378
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
379 \begin{verbatim}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
380 # Echo client program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
381 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
382 HOST = 'daring.cwi.nl' # The remote host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
383 PORT = 50007 # The same port as used by the server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
384 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
385 s.connect(HOST, PORT)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
386 s.send('Hello, world')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
387 data = s.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
388 s.close()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
389 print 'Received', `data`
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 7200
diff changeset
390 \end{verbatim}
7632
d22cf666fa2c Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
391
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
392 \begin{seealso}
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
393 \seemodule{SocketServer}{classes that simplify writing network servers}
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
394 \end{seealso}