Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libsocket.tex @ 5792:dffabc620e4e legacy-trunk

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