Mercurial > cpython-lru_cache-weakref

annotate Doc/libsocket.tex @ 7135:efa22433e855 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Consistency: "{\it ...}" ==> "\emph{...}"
author Fred Drake <fdrake@acm.org>
date Tue, 20 Jan 1998 04:54:23 +0000
parents 5bb884527446
children 98a9da520f1d
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}
7096
5bb884527446 Consistency: "{\bf ...}" ==> "\strong{...}"
Fred Drake <fdrake@acm.org>
parents: 6804
diff changeset
5 This module provides access to the BSD \emph{socket} interface.
1471
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}
6783
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
156 Convert 32-bit integers from network to host byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
157 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
158 no-op; otherwise, it performs a 4-byte swap operation.
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
159 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
160
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
161 \begin{funcdesc}{ntohs}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
162 Convert 16-bit integers from network to host byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
163 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
164 no-op; otherwise, it performs a 2-byte swap operation.
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
165 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
166
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
167 \begin{funcdesc}{htonl}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
168 Convert 32-bit integers from host to network byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
169 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
170 no-op; otherwise, it performs a 4-byte swap operation.
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
171 \end{funcdesc}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
172
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
173 \begin{funcdesc}{htons}{x}
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
174 Convert 16-bit integers from host to network byte order. On machines
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
175 where the host byte order is the same as network byte order, this is a
c18501770895 Separated the definitions of ntohs(), ntohl(), htons(), htonl(). Separate
Fred Drake <fdrake@acm.org>
parents: 6587
diff changeset
176 no-op; otherwise, it performs a 2-byte swap operation.
4576
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
177 \end{funcdesc}
c3b0895c90fb Added [nh]to[hn][sl]().
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
178
6482
d311b68754c1 socket_type ==> SocketType
Fred Drake <fdrake@acm.org>
parents: 5818
diff changeset
179 \begin{datadesc}{SocketType}
5574
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
180 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
181 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
182 \end{datadesc}
84d7cc5e63cd Added description of socket_type.
Guido van Rossum <guido@python.org>
parents: 5461
diff changeset
183
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
184 \subsection{Socket Objects}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
185
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 Socket objects have the following methods. Except for
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 \code{makefile()} these correspond to \UNIX{} system calls applicable to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 sockets.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
190
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
191 \renewcommand{\indexsubitem}{(socket method)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
192 \begin{funcdesc}{accept}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 Accept a connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 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
195 The return value is a pair \code{(\var{conn}, \var{address})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 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
197 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
198 to the socket on the other end of the connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
200
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
201 \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
202 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
203 (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
204 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
206 \begin{funcdesc}{close}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 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
208 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
209 Sockets are automatically closed when they are garbage-collected.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212 \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
213 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
214 (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
215 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216
6587
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
217 \begin{funcdesc}{connect_ex}{address}
6804
e224c41bdac6 Fix a little mess (Likecode{...} -> Like \code{...}) in recently added text.
Guido van Rossum <guido@python.org>
parents: 6783
diff changeset
218 Like \code{connect(\var{address})}, but return an error indicator
6587
e0e667bbc971 Document s.connect_ex(), which does not raise an exception on error.
Guido van Rossum <guido@python.org>
parents: 6482
diff changeset
219 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
220 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
221 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
222 \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
223
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 \begin{funcdesc}{fileno}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 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
226 with \code{select}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
227 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
228
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229 \begin{funcdesc}{getpeername}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
230 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
231 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
232 (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
233 see above.) On some systems this function is not supported.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
234 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
235
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
236 \begin{funcdesc}{getsockname}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
237 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
238 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
239 (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
240 see above.)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
242
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
243 \begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
244 Return the value of the given socket option (see the \UNIX{} man page
7135
efa22433e855 Consistency: "{\it ...}" ==> "\emph{...}"
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
245 \emph{getsockopt}(2)). The needed symbolic constants (\code{SO_*} etc.)
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
246 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
247 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
248 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
249 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
250 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
251 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
252 \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
253 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
254
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
255 \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
256 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
257 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
258 least 1; the maximum value is system-dependent (usually 5).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
259 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
260
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
261 \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
262 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
263 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
264 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
265 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
266 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
267 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
268 \code{open()} function.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
269 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
270
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
271 \begin{funcdesc}{recv}{bufsize\optional{\, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
272 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
273 the data received. The maximum amount of data to be received
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
274 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
275 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
276 zero.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
277 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
278
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
279 \begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
280 Receive data from the socket. The return value is a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
281 \code{(\var{string}, \var{address})} where \var{string} is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
282 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
283 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
284 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
285 (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
286 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
287
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
288 \begin{funcdesc}{send}{string\optional{\, flags}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
289 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
290 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
291 \code{recv()} above. Return the number of bytes sent.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
292 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
293
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
294 \begin{funcdesc}{sendto}{string\optional{\, flags}\, address}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
295 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
296 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
297 \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
298 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
299 (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
300 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
301
1871
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
302 \begin{funcdesc}{setblocking}{flag}
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
303 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
304 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
305 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
306 \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
307 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
308 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
309 \end{funcdesc}
10a12473ee93 added Tommy Burnette's setblocking() method
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
310
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
311 \begin{funcdesc}{setsockopt}{level\, optname\, value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
312 Set the value of the given socket option (see the \UNIX{} man page
7135
efa22433e855 Consistency: "{\it ...}" ==> "\emph{...}"
Fred Drake <fdrake@acm.org>
parents: 7096
diff changeset
313 \emph{setsockopt}(2)). The needed symbolic constants are defined in
2447
73499a667e78 changes refs to SO_* symbols
Guido van Rossum <guido@python.org>
parents: 2354
diff changeset
314 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
315 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
316 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
317 (see the optional built-in module
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
318 \code{struct} for a way to encode C structures as strings).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
319 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
320
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
321 \begin{funcdesc}{shutdown}{how}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
322 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
323 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
324 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
325 disallowed.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
326 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
327
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
328 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
329 \code{recv()} and \code{send()} without \var{flags} argument instead.
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 \subsection{Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
332 \nodename{Socket Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
333
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2453
diff changeset
334 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
335 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
336 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
337 sequence \code{socket}, \code{bind}, \code{listen}, \code{accept}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
338 (possibly repeating the \code{accept} to service more than one client),
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
339 while a client only needs the sequence \code{socket}, \code{connect}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
340 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
341 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
342 \code{accept}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
343
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
344 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
345 # Echo server program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
346 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
347 HOST = '' # Symbolic name meaning the local host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
348 PORT = 50007 # Arbitrary non-privileged server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
349 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
350 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
351 s.listen(1)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
352 conn, addr = s.accept()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
353 print 'Connected by', addr
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
354 while 1:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
355 data = conn.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
356 if not data: break
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
357 conn.send(data)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
358 conn.close()
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 %
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
361 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
362 # Echo client program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
363 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
364 HOST = 'daring.cwi.nl' # The remote host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
365 PORT = 50007 # The same port as used by the server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
366 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
367 s.connect(HOST, PORT)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
368 s.send('Hello, world')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
369 data = s.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
370 s.close()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
371 print 'Received', `data`
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
372 \end{verbatim}\ecode
5818
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
373 %
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
374 \begin{seealso}
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
375 \seemodule{SocketServer}{classes that simplify writing network servers}
3468ea8645ca AMK's megapatch:
Guido van Rossum <guido@python.org>
parents: 5574
diff changeset
376 \end{seealso}