Mercurial > cpython-lru_cache-weakref

annotate Doc/libsocket.tex @ 1567:dddcba2038bc legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
adapt to min value of 1 for listen() backlog argument
author Guido van Rossum <guido@python.org>
date Wed, 02 Mar 1994 10:52:16 +0000
parents 550e2605958b
children 2bcddc905da0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \section{Built-in Module \sectcode{socket}}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \bimodindex{socket}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 This module provides access to the BSD {\em socket} interface.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 It is available on \UNIX{} systems that support this interface.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 For an introduction to socket programming (in C), see the following
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 papers: \emph{An Introductory 4.3BSD Interprocess Communication
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 Communication Tutorial}, by Samuel J. Leffler et al, both in the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 \UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 and PS1:8). The \UNIX{} manual pages for the various socket-related
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 system calls also a valuable source of information on the details of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 socket semantics.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 The Python interface is a straightforward transliteration of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \UNIX{} system call and library interface for sockets to Python's
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 object-oriented style: the \code{socket()} function returns a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \dfn{socket object} whose methods implement the various socket system
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 calls. Parameter types are somewhat higer-level than in the C
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 interface: as with \code{read()} and \code{write()} operations on Python
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 files, buffer allocation on receive operations is automatic, and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 buffer length is implicit on send operations.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 Socket addresses are represented as a single string for the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 \code{AF_UNIX} address family and as a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \code{(\var{host}, \var{port})} for the \code{AF_INET} address family,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 where \var{host} is a string representing
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 either a hostname in Internet domain notation like
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 \code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'},
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 and \var{port} is an integral port number. Other address families are
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 currently not supported. The address format required by a particular
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 socket object is automatically selected based on the address family
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 specified when the socket object was created.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 All errors raise exceptions. The normal exceptions for invalid
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 argument types and out-of-memory conditions can be raised; errors
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 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
39
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 Non-blocking and asynchronous mode are not supported; see module
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \code{select} for a way to do non-blocking socket I/O.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 The module \code{socket} exports the following constants and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 \renewcommand{\indexsubitem}{(in module socket)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 This exception is raised for socket- or address-related errors.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 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
49 pair \code{(\var{errno}, \var{string})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 representing an error returned by a system
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 call, similar to the value accompanying \code{posix.error}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 \begin{datadesc}{AF_UNIX}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
55 \dataline{AF_INET}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 These constants represent the address (and protocol) families,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 used for the first argument to \code{socket()}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 \begin{datadesc}{SOCK_STREAM}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \dataline{SOCK_DGRAM}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 These constants represent the socket types,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
63 used for the second argument to \code{socket()}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 (There are other types, but only \code{SOCK_STREAM} and
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \code{SOCK_DGRAM} appear to be generally useful.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \begin{funcdesc}{gethostbyname}{hostname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 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
70 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
71 is an IP address itself it is returned unchanged.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
73
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 \begin{funcdesc}{getservbyname}{servicename\, protocolname}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 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
76 for that service. The protocol name should be \code{'tcp'} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 \code{'udp'}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
79
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 \begin{funcdesc}{socket}{family\, type\, proto}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 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
82 protocol number. The address family should be \code{AF_INET} or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \code{AF_UNIX}. The socket type should be \code{SOCK_STREAM},
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 \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
85 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
86 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
87
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 \begin{funcdesc}{fromfd}{fd\, family\, type\, proto}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 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
90 returned by a file object's \code{fileno} method). Address family,
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 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
92 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
93 checked --- subsequent operations on the object may fail if the file
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 descriptor is invalid. This function is rarely needed, but can be
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 used to get or set socket options on a socket passed to a program as
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 standard input or output (e.g. a server started by the \UNIX{} inet
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 daemon).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
98 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
99
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 \subsection{Socket Object Methods}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 \noindent
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 Socket objects have the following methods. Except for
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 \code{makefile()} these correspond to \UNIX{} system calls applicable to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
105 sockets.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 \renewcommand{\indexsubitem}{(socket method)}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 \begin{funcdesc}{accept}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 Accept a connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 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
111 The return value is a pair \code{(\var{conn}, \var{address})}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 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
113 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
114 to the socket on the other end of the connection.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
116
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
117 \begin{funcdesc}{bind}{address}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 Bind the socket to an address. The socket must not already be bound.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
120
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 \begin{funcdesc}{close}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 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
123 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
124 Sockets are automatically closed when they are garbage-collected.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 \begin{funcdesc}{connect}{address}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 Connect to a remote socket.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
130
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
131 \begin{funcdesc}{fileno}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 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
133 with \code{select}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
135
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 \begin{funcdesc}{getpeername}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 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
138 useful to find out the port number of a remote IP socket, for instance.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
141 \begin{funcdesc}{getsockname}{}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
142 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
143 number of an IP socket, for instance.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
145
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 \begin{funcdesc}{getsockopt}{level\, optname\, buflen}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 Return the value of the given socket option (see the \UNIX{} man page
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 {\it getsockopt}(2)). The needed symbolic constants are defined in module
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 SOCKET. If the optional third argument is absent, an integer option
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 is assumed and its integer value is returned by the function. If
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
151 \var{buflen} is present, it specifies the maximum length of the buffer used
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 to receive the option in, and this buffer is returned as a string.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 It's up to the caller to decode the contents of the buffer (see the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
154 optional built-in module \code{struct} for a way to decode C structures
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
155 encoded as strings).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
156 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
157
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
158 \begin{funcdesc}{listen}{backlog}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
159 Listen for connections made to the socket.
1567
dddcba2038bc adapt to min value of 1 for listen() backlog argument
Guido van Rossum <guido@python.org>
parents: 1483
diff changeset
160 The argument specifies the maximum number of queued connections and
dddcba2038bc adapt to min value of 1 for listen() backlog argument
Guido van Rossum <guido@python.org>
parents: 1483
diff changeset
161 should be at least 1; the maximum value is system-dependent.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
163
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 \begin{funcdesc}{makefile}{mode}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
165 Return a \dfn{file object} associated with the socket.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 (File objects were described earlier under Built-in Types.)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
167 The file object references a \code{dup}ped version of the socket file
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 descriptor, so the file object and socket object may be closed or
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 garbage-collected independently.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
170 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
171
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 \begin{funcdesc}{recv}{bufsize\, flags}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 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
174 the data received. The maximum amount of data to be received
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 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
176 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
177 zero.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
179
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
180 \begin{funcdesc}{recvfrom}{bufsize}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 Receive data from the socket. The return value is a pair
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 \code{(\var{string}, \var{address})} where \var{string} is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 representing the data received and \var{address} is the address of the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 socket sending the data.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
185 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
186
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 \begin{funcdesc}{send}{string}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
188 Send data to the socket. The socket must be connected to a remote
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 socket.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
190 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
191
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
192 \begin{funcdesc}{sendto}{string\, address}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 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
194 remote socket, since the destination socket is specified by
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
195 \code{address}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
197
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
198 \begin{funcdesc}{setsockopt}{level\, optname\, value}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 Set the value of the given socket option (see the \UNIX{} man page
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
200 {\it setsockopt}(2)). The needed symbolic constants are defined in module
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
201 \code{SOCKET}. The value can be an integer or a string representing a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
202 buffer. In the latter case it is up to the caller to ensure that the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
203 string contains the proper bits (see the optional built-in module
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 \code{struct} for a way to encode C structures as strings).
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
206
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 \begin{funcdesc}{shutdown}{how}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
208 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
209 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
210 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
211 disallowed.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
213
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 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
215 \code{recv()} and \code{send()} without \var{flags} argument instead.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
217 \subsection{Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
218 \nodename{Socket Example}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
220 Here are two minimal example programs using the TCP/IP protocol: a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 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
222 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
223 sequence \code{socket}, \code{bind}, \code{listen}, \code{accept}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 (possibly repeating the \code{accept} to service more than one client),
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 while a client only needs the sequence \code{socket}, \code{connect}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
226 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
227 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
228 \code{accept}.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
229
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
230 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
231 # Echo server program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
233 HOST = '' # Symbolic name meaning the local host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
234 PORT = 50007 # Arbitrary non-privileged server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
235 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
236 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
237 s.listen(1)
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
238 conn, addr = s.accept()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
239 print 'Connected by', addr
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
240 while 1:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 data = conn.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
242 if not data: break
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
243 conn.send(data)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
244 conn.close()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
245 \end{verbatim}\ecode
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
246
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
247 \bcode\begin{verbatim}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
248 # Echo client program
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
249 from socket import *
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
250 HOST = 'daring.cwi.nl' # The remote host
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
251 PORT = 50007 # The same port as used by the server
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
252 s = socket(AF_INET, SOCK_STREAM)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
253 s.connect(HOST, PORT)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
254 s.send('Hello, world')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
255 data = s.recv(1024)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
256 s.close()
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
257 print 'Received', `data`
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
258 \end{verbatim}\ecode