Mercurial > cpython-lru_cache-weakref

annotate Doc/libsocket.tex @ 6719:faebc1940432 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Understand -Xlinker option.
author Guido van Rossum <guido@python.org>
date Tue, 02 Dec 1997 20:38:11 +0000
parents e0e667bbc971
children c18501770895
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}}
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
2 \label{module-socket}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 \bimodindex{socket}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 This module provides access to the BSD {\em socket} interface.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 It is available on \UNIX{} systems that support this interface.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 For an introduction to socket programming (in C), see the following
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 papers: \emph{An Introductory 4.3BSD Interprocess Communication
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 Communication Tutorial}, by Samuel J. Leffler et al, both in the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 \UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 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
14 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
15 socket semantics.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 The Python interface is a straightforward transliteration of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \UNIX{} system call and library interface for sockets to Python's
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 object-oriented style: the \code{socket()} function returns a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \dfn{socket object} whose methods implement the various socket system
4882
8d17d552d0ec very minor typo
Barry Warsaw <barry@python.org>
parents: 4784
diff changeset
21 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
22 interface: as with \code{read()} and \code{write()} operations on Python
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 files, buffer allocation on receive operations is automatic, and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 buffer length is implicit on send operations.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 Socket addresses are represented as a single string for the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \code{AF_UNIX} address family and as a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 \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
29 where \var{host} is a string representing
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 either a hostname in Internet domain notation like
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \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
32 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
33 currently not supported. The address format required by a particular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 socket object is automatically selected based on the address family
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 specified when the socket object was created.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
5461
0ded63bcf5de Document "" and "<broadcast>".
Guido van Rossum <guido@python.org>
parents: 4929
diff changeset
37 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
38 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
39 \code{"<broadcast>"} represents \code{INADDR_BROADCAST}.
0ded63bcf5de Document "" and "<broadcast>".
Guido van Rossum <guido@python.org>
parents: 4929
diff changeset
40
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 All errors raise exceptions. The normal exceptions for invalid
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 argument types and out-of-memory conditions can be raised; errors
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 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
44
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
45 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
46 method.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 The module \code{socket} exports the following constants and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
49
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 \renewcommand{\indexsubitem}{(in module socket)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 This exception is raised for socket- or address-related errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 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
54 pair \code{(\var{errno}, \var{string})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 representing an error returned by a system
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 call, similar to the value accompanying \code{posix.error}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59 \begin{datadesc}{AF_UNIX}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \dataline{AF_INET}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 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
62 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
63 constant is not defined then this protocol is unsupported.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \begin{datadesc}{SOCK_STREAM}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 \dataline{SOCK_DGRAM}
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
68 \dataline{SOCK_RAW}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
69 \dataline{SOCK_RDM}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
70 \dataline{SOCK_SEQPACKET}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
71 These constants represent the socket types,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 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
73 (Only \code{SOCK_STREAM} and
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 \code{SOCK_DGRAM} appear to be generally useful.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
76
2354
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
77 \begin{datadesc}{SO_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
78 \dataline{SOMAXCONN}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
79 \dataline{MSG_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
80 \dataline{SOL_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
81 \dataline{IPPROTO_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
82 \dataline{IPPORT_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
83 \dataline{INADDR_*}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
84 \dataline{IP_*}
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
85 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
86 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
87 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
88 \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
89 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
90 for a few symbols, default values are provided.
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
91 \end{datadesc}
fbaf54169711 added lots of constants
Guido van Rossum <guido@python.org>
parents: 2064
diff changeset
92
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 \begin{funcdesc}{gethostbyname}{hostname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 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
95 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
96 is an IP address itself it is returned unchanged.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
1759
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
99 \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
100 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
101 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
102 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
103 \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
104 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
105 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
106 (see below).
2064
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
107 \end{funcdesc}
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
108
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
109 \begin{funcdesc}{gethostbyaddr}{ip_address}
280f31e6c653 copyright.tex: Add 1995 to copyright message.
Guido van Rossum <guido@python.org>
parents: 1871
diff changeset
110 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
111 \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
112 \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
113 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
114 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
115 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
116 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
117 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
118 \end{funcdesc}
4d421f9e8373 * Doc/libsocket.tex (subsection{Socket Object Methods}):
Guido van Rossum <guido@python.org>
parents: 1750
diff changeset
119
4784
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
120 \begin{funcdesc}{getprotobyname}{protocolname}
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
121 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
122 suitable for passing as the (optional) third argument to the
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
123 \code{socket()} function. This is usually only needed for sockets
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
124 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
125 the correct protocol is chosen automatically if the protocol is
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
126 omitted or zero.
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
127 \end{funcdesc}
e43362910a5e Documented getprotobyname() interface.
Guido van Rossum <guido@python.org>
parents: 4576
diff changeset
128
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 \begin{funcdesc}{getservbyname}{servicename\, protocolname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 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
131 for that service. The protocol name should be \code{'tcp'} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 \code{'udp'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
135 \begin{funcdesc}{socket}{family\, type\optional{\, proto}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 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
137 protocol number. The address family should be \code{AF_INET} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 \code{AF_UNIX}. The socket type should be \code{SOCK_STREAM},
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \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
140 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
141 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
142
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
143 \begin{funcdesc}{fromfd}{fd\, family\, type\optional{\, proto}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 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
145 returned by a file object's \code{fileno} method). Address family,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 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
147 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
148 checked --- subsequent operations on the object may fail if the file
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 descriptor is invalid. This function is rarely needed, but can be
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 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
151 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
152 daemon).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
154
4576
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
155 \begin{funcdesc}{ntohl}{x}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
156 \funcline{ntohs}{x}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
157 \funcline{htonl}{x}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
158 \funcline{htons}{x}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
159 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
160 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
161 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
162 (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
163 perform 2-byte or 4-byte swap operations.
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
164 \end{funcdesc}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
165
6482
d311b68754c1 socket_type ==> SocketType
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
166 \begin{datadesc}{SocketType}
5574
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
167 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
168 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
169 \end{datadesc}
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
170
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
171 \subsection{Socket Objects}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
174 Socket objects have the following methods. Except for
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 \code{makefile()} these correspond to \UNIX{} system calls applicable to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176 sockets.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
177
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 \renewcommand{\indexsubitem}{(socket method)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
179 \begin{funcdesc}{accept}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 Accept a connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 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
182 The return value is a pair \code{(\var{conn}, \var{address})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 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
184 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
185 to the socket on the other end of the connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 \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
189 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
190 (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
191 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
192
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 \begin{funcdesc}{close}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 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
195 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
196 Sockets are automatically closed when they are garbage-collected.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
198
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 \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
200 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
201 (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
202 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
203
6587
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
204 \begin{funcdesc}{connect_ex}{address}
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
205 Likecode{connect(\var{address})}, but return an error indicator
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
206 instead of raising an exception. The error indicator is 0 if the
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
207 operation succeeded, otherwise the value of the \code{errno}
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
208 variable. This is useful e.g. for asynchronous connects.
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
209 \end{funcdesc}
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
210
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211 \begin{funcdesc}{fileno}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212 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
213 with \code{select}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
215
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 \begin{funcdesc}{getpeername}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
217 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
218 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
219 (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
220 see above.) On some systems this function is not supported.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
223 \begin{funcdesc}{getsockname}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 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
225 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
226 (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
227 see above.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
228 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
230 \begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
231 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
232 {\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
233 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
234 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
235 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
236 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
237 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
238 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
239 \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
240 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
241
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
242 \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
243 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
244 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
245 least 1; the maximum value is system-dependent (usually 5).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
246 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
247
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
248 \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
249 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
250 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
251 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
252 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
253 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
254 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
255 \code{open()} function.
1471
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
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
258 \begin{funcdesc}{recv}{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 string representing
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
260 the data received. The maximum amount of data to be received
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
261 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
262 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
263 zero.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
264 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
265
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
266 \begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
267 Receive data from the socket. The return value is a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
268 \code{(\var{string}, \var{address})} where \var{string} is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
269 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
270 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
271 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
272 (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
273 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
274
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
275 \begin{funcdesc}{send}{string\optional{\, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
276 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
277 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
278 \code{recv()} above. Return the number of bytes sent.
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
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
281 \begin{funcdesc}{sendto}{string\optional{\, flags}\, address}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
282 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
283 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
284 \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
285 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
286 (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
287 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
288
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
289 \begin{funcdesc}{setblocking}{flag}
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
290 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
291 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
292 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
293 \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
294 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
295 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
296 \end{funcdesc}
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
297
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
298 \begin{funcdesc}{setsockopt}{level\, optname\, value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
299 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
300 {\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
301 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
302 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
303 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
304 (see the optional built-in module
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
305 \code{struct} for a way to encode C structures as strings).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
306 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
307
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
308 \begin{funcdesc}{shutdown}{how}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
309 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
310 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
311 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
312 disallowed.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
313 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
314
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
315 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
316 \code{recv()} and \code{send()} without \var{flags} argument instead.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
317
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
318 \subsection{Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
319 \nodename{Socket Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
320
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
321 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
322 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
323 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
324 sequence \code{socket}, \code{bind}, \code{listen}, \code{accept}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
325 (possibly repeating the \code{accept} to service more than one client),
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
326 while a client only needs the sequence \code{socket}, \code{connect}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
327 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
328 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
329 \code{accept}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
330
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
331 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
332 # Echo server program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
333 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
334 HOST = '' # Symbolic name meaning the local host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
335 PORT = 50007 # Arbitrary non-privileged server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
336 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
337 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
338 s.listen(1)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
339 conn, addr = s.accept()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
340 print 'Connected by', addr
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
341 while 1:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
342 data = conn.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
343 if not data: break
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
344 conn.send(data)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
345 conn.close()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
346 \end{verbatim}\ecode
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
347 %
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
348 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
349 # Echo client program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
350 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
351 HOST = 'daring.cwi.nl' # The remote host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
352 PORT = 50007 # The same port as used by the server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
353 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
354 s.connect(HOST, PORT)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
355 s.send('Hello, world')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
356 data = s.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
357 s.close()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
358 print 'Received', `data`
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
359 \end{verbatim}\ecode
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
360 %
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
361 \begin{seealso}
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
362 \seemodule{SocketServer}{classes that simplify writing network servers}
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
363 \end{seealso}