Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 1 | \section{Built-in Module \sectcode{socket}} |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame^] | 2 | \label{module-socket} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 3 | |
| 4 | \bimodindex{socket} |
| 5 | This module provides access to the BSD {\em socket} interface. |
| 6 | It is available on \UNIX{} systems that support this interface. |
| 7 | |
| 8 | For an introduction to socket programming (in C), see the following |
| 9 | papers: \emph{An Introductory 4.3BSD Interprocess Communication |
| 10 | Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess |
| 11 | Communication Tutorial}, by Samuel J. Leffler et al, both in the |
| 12 | \UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7 |
| 13 | and PS1:8). The \UNIX{} manual pages for the various socket-related |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 14 | system calls are also a valuable source of information on the details of |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 15 | socket semantics. |
| 16 | |
| 17 | The Python interface is a straightforward transliteration of the |
| 18 | \UNIX{} system call and library interface for sockets to Python's |
| 19 | object-oriented style: the \code{socket()} function returns a |
| 20 | \dfn{socket object} whose methods implement the various socket system |
Barry Warsaw | d44be3f | 1997-01-03 20:19:05 +0000 | [diff] [blame] | 21 | calls. Parameter types are somewhat higher-level than in the C |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 22 | interface: as with \code{read()} and \code{write()} operations on Python |
| 23 | files, buffer allocation on receive operations is automatic, and |
| 24 | buffer length is implicit on send operations. |
| 25 | |
| 26 | Socket addresses are represented as a single string for the |
| 27 | \code{AF_UNIX} address family and as a pair |
| 28 | \code{(\var{host}, \var{port})} for the \code{AF_INET} address family, |
| 29 | where \var{host} is a string representing |
| 30 | either a hostname in Internet domain notation like |
| 31 | \code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'}, |
| 32 | and \var{port} is an integral port number. Other address families are |
| 33 | currently not supported. The address format required by a particular |
| 34 | socket object is automatically selected based on the address family |
| 35 | specified when the socket object was created. |
| 36 | |
Guido van Rossum | e4f347e | 1997-05-09 02:21:51 +0000 | [diff] [blame] | 37 | For IP addresses, two special forms are accepted instead of a host |
| 38 | address: the empty string represents \code{INADDR_ANY}, and the string |
| 39 | \code{"<broadcast>"} represents \code{INADDR_BROADCAST}. |
| 40 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 41 | All errors raise exceptions. The normal exceptions for invalid |
| 42 | argument types and out-of-memory conditions can be raised; errors |
| 43 | related to socket or address semantics raise the error \code{socket.error}. |
| 44 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 45 | Non-blocking mode is supported through the \code{setblocking()} |
| 46 | method. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 47 | |
| 48 | The module \code{socket} exports the following constants and functions: |
| 49 | |
| 50 | \renewcommand{\indexsubitem}{(in module socket)} |
| 51 | \begin{excdesc}{error} |
| 52 | This exception is raised for socket- or address-related errors. |
| 53 | The accompanying value is either a string telling what went wrong or a |
| 54 | pair \code{(\var{errno}, \var{string})} |
| 55 | representing an error returned by a system |
| 56 | call, similar to the value accompanying \code{posix.error}. |
| 57 | \end{excdesc} |
| 58 | |
| 59 | \begin{datadesc}{AF_UNIX} |
| 60 | \dataline{AF_INET} |
| 61 | These constants represent the address (and protocol) families, |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 62 | used for the first argument to \code{socket()}. If the \code{AF_UNIX} |
| 63 | constant is not defined then this protocol is unsupported. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 64 | \end{datadesc} |
| 65 | |
| 66 | \begin{datadesc}{SOCK_STREAM} |
| 67 | \dataline{SOCK_DGRAM} |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 68 | \dataline{SOCK_RAW} |
| 69 | \dataline{SOCK_RDM} |
| 70 | \dataline{SOCK_SEQPACKET} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 71 | These constants represent the socket types, |
| 72 | used for the second argument to \code{socket()}. |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 73 | (Only \code{SOCK_STREAM} and |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 74 | \code{SOCK_DGRAM} appear to be generally useful.) |
| 75 | \end{datadesc} |
| 76 | |
Guido van Rossum | ed2bad8 | 1995-02-16 16:29:18 +0000 | [diff] [blame] | 77 | \begin{datadesc}{SO_*} |
| 78 | \dataline{SOMAXCONN} |
| 79 | \dataline{MSG_*} |
| 80 | \dataline{SOL_*} |
| 81 | \dataline{IPPROTO_*} |
| 82 | \dataline{IPPORT_*} |
| 83 | \dataline{INADDR_*} |
| 84 | \dataline{IP_*} |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 85 | Many constants of these forms, documented in the \UNIX{} documentation on |
Guido van Rossum | ed2bad8 | 1995-02-16 16:29:18 +0000 | [diff] [blame] | 86 | sockets and/or the IP protocol, are also defined in the socket module. |
| 87 | They are generally used in arguments to the \code{setsockopt} and |
| 88 | \code{getsockopt} methods of socket objects. In most cases, only |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 89 | those symbols that are defined in the \UNIX{} header files are defined; |
Guido van Rossum | ed2bad8 | 1995-02-16 16:29:18 +0000 | [diff] [blame] | 90 | for a few symbols, default values are provided. |
| 91 | \end{datadesc} |
| 92 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 93 | \begin{funcdesc}{gethostbyname}{hostname} |
| 94 | Translate a host name to IP address format. The IP address is |
| 95 | returned as a string, e.g., \code{'100.50.200.5'}. If the host name |
| 96 | is an IP address itself it is returned unchanged. |
| 97 | \end{funcdesc} |
| 98 | |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 99 | \begin{funcdesc}{gethostname}{} |
Guido van Rossum | 16d6e71 | 1994-08-08 12:30:22 +0000 | [diff] [blame] | 100 | Return a string containing the hostname of the machine where |
| 101 | the Python interpreter is currently executing. If you want to know the |
| 102 | current machine's IP address, use |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 103 | \code{socket.gethostbyname(socket.gethostname())}. |
Guido van Rossum | fe27a50 | 1997-01-11 17:04:56 +0000 | [diff] [blame] | 104 | Note: \code{gethostname()} doesn't always return the fully qualified |
| 105 | domain name; use \code{socket.gethostbyaddr(socket.gethostname())} |
| 106 | (see below). |
Guido van Rossum | 31cce97 | 1995-01-04 19:17:34 +0000 | [diff] [blame] | 107 | \end{funcdesc} |
| 108 | |
| 109 | \begin{funcdesc}{gethostbyaddr}{ip_address} |
| 110 | Return a triple \code{(hostname, aliaslist, ipaddrlist)} where |
| 111 | \code{hostname} is the primary host name responding to the given |
| 112 | \var{ip_address}, \code{aliaslist} is a (possibly empty) list of |
| 113 | alternative host names for the same address, and \code{ipaddrlist} is |
| 114 | a list of IP addresses for the same interface on the same |
| 115 | host (most likely containing only a single address). |
Guido van Rossum | fe27a50 | 1997-01-11 17:04:56 +0000 | [diff] [blame] | 116 | To find the fully qualified domain name, check \var{hostname} and the |
| 117 | items of \var{aliaslist} for an entry containing at least one period. |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 118 | \end{funcdesc} |
| 119 | |
Guido van Rossum | 62ac99e | 1996-12-19 16:43:25 +0000 | [diff] [blame] | 120 | \begin{funcdesc}{getprotobyname}{protocolname} |
| 121 | Translate an Internet protocol name (e.g. \code{'icmp'}) to a constant |
| 122 | suitable for passing as the (optional) third argument to the |
| 123 | \code{socket()} function. This is usually only needed for sockets |
| 124 | opened in ``raw'' mode (\code{SOCK_RAW}); for the normal socket modes, |
| 125 | the correct protocol is chosen automatically if the protocol is |
| 126 | omitted or zero. |
| 127 | \end{funcdesc} |
| 128 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 129 | \begin{funcdesc}{getservbyname}{servicename\, protocolname} |
| 130 | Translate an Internet service name and protocol name to a port number |
| 131 | for that service. The protocol name should be \code{'tcp'} or |
| 132 | \code{'udp'}. |
| 133 | \end{funcdesc} |
| 134 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 135 | \begin{funcdesc}{socket}{family\, type\optional{\, proto}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 136 | Create a new socket using the given address family, socket type and |
| 137 | protocol number. The address family should be \code{AF_INET} or |
| 138 | \code{AF_UNIX}. The socket type should be \code{SOCK_STREAM}, |
| 139 | \code{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants. |
| 140 | The protocol number is usually zero and may be omitted in that case. |
| 141 | \end{funcdesc} |
| 142 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 143 | \begin{funcdesc}{fromfd}{fd\, family\, type\optional{\, proto}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 144 | Build a socket object from an existing file descriptor (an integer as |
| 145 | returned by a file object's \code{fileno} method). Address family, |
| 146 | socket type and protocol number are as for the \code{socket} function |
| 147 | above. The file descriptor should refer to a socket, but this is not |
| 148 | checked --- subsequent operations on the object may fail if the file |
| 149 | descriptor is invalid. This function is rarely needed, but can be |
| 150 | used to get or set socket options on a socket passed to a program as |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 151 | standard input or output (e.g.\ a server started by the \UNIX{} inet |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 152 | daemon). |
| 153 | \end{funcdesc} |
| 154 | |
Guido van Rossum | bda7ca7 | 1996-12-02 17:24:10 +0000 | [diff] [blame] | 155 | \begin{funcdesc}{ntohl}{x} |
| 156 | \funcline{ntohs}{x} |
| 157 | \funcline{htonl}{x} |
| 158 | \funcline{htons}{x} |
| 159 | These functions convert 32-bit (`l' suffix) and 16-bit (`s' suffix) |
| 160 | integers between network and host byte order. On machines where the |
| 161 | host byte order is the same as the network byte order, they are no-ops |
| 162 | (assuming the values fit in the indicated size); otherwise, they |
| 163 | perform 2-byte or 4-byte swap operations. |
| 164 | \end{funcdesc} |
| 165 | |
Guido van Rossum | 2335c5e | 1997-05-21 14:41:42 +0000 | [diff] [blame] | 166 | \begin{datadesc}{socket_type} |
| 167 | This is a Python type object that represents the socket object type. |
| 168 | It is the same as \code{type(socket.socket(...))}. |
| 169 | \end{datadesc} |
| 170 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 171 | \subsection{Socket Objects} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 172 | |
| 173 | \noindent |
| 174 | Socket objects have the following methods. Except for |
| 175 | \code{makefile()} these correspond to \UNIX{} system calls applicable to |
| 176 | sockets. |
| 177 | |
| 178 | \renewcommand{\indexsubitem}{(socket method)} |
| 179 | \begin{funcdesc}{accept}{} |
| 180 | Accept a connection. |
| 181 | The socket must be bound to an address and listening for connections. |
| 182 | The return value is a pair \code{(\var{conn}, \var{address})} |
| 183 | where \var{conn} is a \emph{new} socket object usable to send and |
| 184 | receive data on the connection, and \var{address} is the address bound |
| 185 | to the socket on the other end of the connection. |
| 186 | \end{funcdesc} |
| 187 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 188 | \begin{funcdesc}{bind}{address} |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 189 | Bind the socket to \var{address}. The socket must not already be bound. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 190 | (The format of \var{address} depends on the address family --- see above.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 191 | \end{funcdesc} |
| 192 | |
| 193 | \begin{funcdesc}{close}{} |
| 194 | Close the socket. All future operations on the socket object will fail. |
| 195 | The remote end will receive no more data (after queued data is flushed). |
| 196 | Sockets are automatically closed when they are garbage-collected. |
| 197 | \end{funcdesc} |
| 198 | |
| 199 | \begin{funcdesc}{connect}{address} |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 200 | Connect to a remote socket at \var{address}. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 201 | (The format of \var{address} depends on the address family --- see above.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 202 | \end{funcdesc} |
| 203 | |
| 204 | \begin{funcdesc}{fileno}{} |
| 205 | Return the socket's file descriptor (a small integer). This is useful |
| 206 | with \code{select}. |
| 207 | \end{funcdesc} |
| 208 | |
| 209 | \begin{funcdesc}{getpeername}{} |
| 210 | Return the remote address to which the socket is connected. This is |
| 211 | useful to find out the port number of a remote IP socket, for instance. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 212 | (The format of the address returned depends on the address family --- |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 213 | see above.) On some systems this function is not supported. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 214 | \end{funcdesc} |
| 215 | |
| 216 | \begin{funcdesc}{getsockname}{} |
| 217 | Return the socket's own address. This is useful to find out the port |
| 218 | number of an IP socket, for instance. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 219 | (The format of the address returned depends on the address family --- |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 220 | see above.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 221 | \end{funcdesc} |
| 222 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 223 | \begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 224 | Return the value of the given socket option (see the \UNIX{} man page |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 225 | {\it getsockopt}(2)). The needed symbolic constants (\code{SO_*} etc.) |
| 226 | are defined in this module. If \var{buflen} |
| 227 | is absent, an integer option is assumed and its integer value |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 228 | is returned by the function. If \var{buflen} is present, it specifies |
| 229 | the maximum length of the buffer used to receive the option in, and |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 230 | this buffer is returned as a string. It is up to the caller to decode |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 231 | the contents of the buffer (see the optional built-in module |
| 232 | \code{struct} for a way to decode C structures encoded as strings). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 233 | \end{funcdesc} |
| 234 | |
| 235 | \begin{funcdesc}{listen}{backlog} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 236 | Listen for connections made to the socket. The \var{backlog} argument |
| 237 | specifies the maximum number of queued connections and should be at |
| 238 | least 1; the maximum value is system-dependent (usually 5). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 239 | \end{funcdesc} |
| 240 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 241 | \begin{funcdesc}{makefile}{\optional{mode\optional{\, bufsize}}} |
| 242 | Return a \dfn{file object} associated with the socket. (File objects |
| 243 | were described earlier under Built-in Types.) The file object |
| 244 | references a \code{dup()}ped version of the socket file descriptor, so |
| 245 | the file object and socket object may be closed or garbage-collected |
| 246 | independently. The optional \var{mode} and \var{bufsize} arguments |
| 247 | are interpreted the same way as by the built-in |
| 248 | \code{open()} function. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 249 | \end{funcdesc} |
| 250 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 251 | \begin{funcdesc}{recv}{bufsize\optional{\, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 252 | Receive data from the socket. The return value is a string representing |
| 253 | the data received. The maximum amount of data to be received |
| 254 | at once is specified by \var{bufsize}. See the \UNIX{} manual page |
| 255 | for the meaning of the optional argument \var{flags}; it defaults to |
| 256 | zero. |
| 257 | \end{funcdesc} |
| 258 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 259 | \begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 260 | Receive data from the socket. The return value is a pair |
| 261 | \code{(\var{string}, \var{address})} where \var{string} is a string |
| 262 | representing the data received and \var{address} is the address of the |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 263 | socket sending the data. The optional \var{flags} argument has the |
| 264 | same meaning as for \code{recv()} above. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 265 | (The format of \var{address} depends on the address family --- see above.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 266 | \end{funcdesc} |
| 267 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 268 | \begin{funcdesc}{send}{string\optional{\, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 269 | Send data to the socket. The socket must be connected to a remote |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 270 | socket. The optional \var{flags} argument has the same meaning as for |
| 271 | \code{recv()} above. Return the number of bytes sent. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 272 | \end{funcdesc} |
| 273 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 274 | \begin{funcdesc}{sendto}{string\optional{\, flags}\, address} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 275 | Send data to the socket. The socket should not be connected to a |
| 276 | remote socket, since the destination socket is specified by |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 277 | \code{address}. The optional \var{flags} argument has the same |
| 278 | meaning as for \code{recv()} above. Return the number of bytes sent. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 279 | (The format of \var{address} depends on the address family --- see above.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 280 | \end{funcdesc} |
| 281 | |
Guido van Rossum | 9195148 | 1994-09-07 14:39:14 +0000 | [diff] [blame] | 282 | \begin{funcdesc}{setblocking}{flag} |
| 283 | Set blocking or non-blocking mode of the socket: if \var{flag} is 0, |
| 284 | the socket is set to non-blocking, else to blocking mode. Initially |
| 285 | all sockets are in blocking mode. In non-blocking mode, if a |
| 286 | \code{recv} call doesn't find any data, or if a \code{send} call can't |
| 287 | immediately dispose of the data, a \code{socket.error} exception is |
| 288 | raised; in blocking mode, the calls block until they can proceed. |
| 289 | \end{funcdesc} |
| 290 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 291 | \begin{funcdesc}{setsockopt}{level\, optname\, value} |
| 292 | Set the value of the given socket option (see the \UNIX{} man page |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 293 | {\it setsockopt}(2)). The needed symbolic constants are defined in |
| 294 | the \code{socket} module (\code{SO_*} etc.). The value can be an |
| 295 | integer or a string representing a buffer. In the latter case it is |
| 296 | up to the caller to ensure that the string contains the proper bits |
| 297 | (see the optional built-in module |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 298 | \code{struct} for a way to encode C structures as strings). |
| 299 | \end{funcdesc} |
| 300 | |
| 301 | \begin{funcdesc}{shutdown}{how} |
| 302 | Shut down one or both halves of the connection. If \var{how} is \code{0}, |
| 303 | further receives are disallowed. If \var{how} is \code{1}, further sends are |
| 304 | disallowed. If \var{how} is \code{2}, further sends and receives are |
| 305 | disallowed. |
| 306 | \end{funcdesc} |
| 307 | |
| 308 | Note that there are no methods \code{read()} or \code{write()}; use |
| 309 | \code{recv()} and \code{send()} without \var{flags} argument instead. |
| 310 | |
| 311 | \subsection{Example} |
| 312 | \nodename{Socket Example} |
| 313 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 314 | Here are two minimal example programs using the TCP/IP protocol:\ a |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 315 | server that echoes all data that it receives back (servicing only one |
| 316 | client), and a client using it. Note that a server must perform the |
| 317 | sequence \code{socket}, \code{bind}, \code{listen}, \code{accept} |
| 318 | (possibly repeating the \code{accept} to service more than one client), |
| 319 | while a client only needs the sequence \code{socket}, \code{connect}. |
| 320 | Also note that the server does not \code{send}/\code{receive} on the |
| 321 | socket it is listening on but on the new socket returned by |
| 322 | \code{accept}. |
| 323 | |
| 324 | \bcode\begin{verbatim} |
| 325 | # Echo server program |
| 326 | from socket import * |
| 327 | HOST = '' # Symbolic name meaning the local host |
| 328 | PORT = 50007 # Arbitrary non-privileged server |
| 329 | s = socket(AF_INET, SOCK_STREAM) |
| 330 | s.bind(HOST, PORT) |
Guido van Rossum | 5da5755 | 1994-03-02 10:52:16 +0000 | [diff] [blame] | 331 | s.listen(1) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 332 | conn, addr = s.accept() |
| 333 | print 'Connected by', addr |
| 334 | while 1: |
| 335 | data = conn.recv(1024) |
| 336 | if not data: break |
| 337 | conn.send(data) |
| 338 | conn.close() |
| 339 | \end{verbatim}\ecode |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame^] | 340 | % |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 341 | \bcode\begin{verbatim} |
| 342 | # Echo client program |
| 343 | from socket import * |
| 344 | HOST = 'daring.cwi.nl' # The remote host |
| 345 | PORT = 50007 # The same port as used by the server |
| 346 | s = socket(AF_INET, SOCK_STREAM) |
| 347 | s.connect(HOST, PORT) |
| 348 | s.send('Hello, world') |
| 349 | data = s.recv(1024) |
| 350 | s.close() |
| 351 | print 'Received', `data` |
| 352 | \end{verbatim}\ecode |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame^] | 353 | % |
| 354 | \begin{seealso} |
| 355 | \seemodule{SocketServer}{classes that simplify writing network servers} |
| 356 | \end{seealso} |