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} |
Fred Drake | af8a015 | 1998-01-14 14:51:31 +0000 | [diff] [blame] | 5 | This module provides access to the BSD \emph{socket} interface. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 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} |
Fred Drake | c5aec05 | 1997-12-08 21:25:41 +0000 | [diff] [blame] | 156 | Convert 32-bit integers from network to host byte order. On machines |
| 157 | where the host byte order is the same as network byte order, this is a |
| 158 | no-op; otherwise, it performs a 4-byte swap operation. |
| 159 | \end{funcdesc} |
| 160 | |
| 161 | \begin{funcdesc}{ntohs}{x} |
| 162 | Convert 16-bit integers from network to host byte order. On machines |
| 163 | where the host byte order is the same as network byte order, this is a |
| 164 | no-op; otherwise, it performs a 2-byte swap operation. |
| 165 | \end{funcdesc} |
| 166 | |
| 167 | \begin{funcdesc}{htonl}{x} |
| 168 | Convert 32-bit integers from host to network byte order. On machines |
| 169 | where the host byte order is the same as network byte order, this is a |
| 170 | no-op; otherwise, it performs a 4-byte swap operation. |
| 171 | \end{funcdesc} |
| 172 | |
| 173 | \begin{funcdesc}{htons}{x} |
| 174 | Convert 16-bit integers from host to network byte order. On machines |
| 175 | where the host byte order is the same as network byte order, this is a |
| 176 | no-op; otherwise, it performs a 2-byte swap operation. |
Guido van Rossum | bda7ca7 | 1996-12-02 17:24:10 +0000 | [diff] [blame] | 177 | \end{funcdesc} |
| 178 | |
Fred Drake | 5451d67 | 1997-10-13 21:31:02 +0000 | [diff] [blame] | 179 | \begin{datadesc}{SocketType} |
Guido van Rossum | 2335c5e | 1997-05-21 14:41:42 +0000 | [diff] [blame] | 180 | This is a Python type object that represents the socket object type. |
| 181 | It is the same as \code{type(socket.socket(...))}. |
| 182 | \end{datadesc} |
| 183 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 184 | \subsection{Socket Objects} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 185 | |
| 186 | \noindent |
| 187 | Socket objects have the following methods. Except for |
| 188 | \code{makefile()} these correspond to \UNIX{} system calls applicable to |
| 189 | sockets. |
| 190 | |
| 191 | \renewcommand{\indexsubitem}{(socket method)} |
| 192 | \begin{funcdesc}{accept}{} |
| 193 | Accept a connection. |
| 194 | The socket must be bound to an address and listening for connections. |
| 195 | The return value is a pair \code{(\var{conn}, \var{address})} |
| 196 | where \var{conn} is a \emph{new} socket object usable to send and |
| 197 | receive data on the connection, and \var{address} is the address bound |
| 198 | to the socket on the other end of the connection. |
| 199 | \end{funcdesc} |
| 200 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 201 | \begin{funcdesc}{bind}{address} |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 202 | 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] | 203 | (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] | 204 | \end{funcdesc} |
| 205 | |
| 206 | \begin{funcdesc}{close}{} |
| 207 | Close the socket. All future operations on the socket object will fail. |
| 208 | The remote end will receive no more data (after queued data is flushed). |
| 209 | Sockets are automatically closed when they are garbage-collected. |
| 210 | \end{funcdesc} |
| 211 | |
| 212 | \begin{funcdesc}{connect}{address} |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 213 | Connect to a remote socket at \var{address}. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 214 | (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] | 215 | \end{funcdesc} |
| 216 | |
Guido van Rossum | f7790c6 | 1997-11-18 15:29:20 +0000 | [diff] [blame] | 217 | \begin{funcdesc}{connect_ex}{address} |
Guido van Rossum | eefcba6 | 1997-12-09 19:47:24 +0000 | [diff] [blame] | 218 | Like \code{connect(\var{address})}, but return an error indicator |
Guido van Rossum | f7790c6 | 1997-11-18 15:29:20 +0000 | [diff] [blame] | 219 | instead of raising an exception. The error indicator is 0 if the |
| 220 | operation succeeded, otherwise the value of the \code{errno} |
| 221 | variable. This is useful e.g. for asynchronous connects. |
| 222 | \end{funcdesc} |
| 223 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 224 | \begin{funcdesc}{fileno}{} |
| 225 | Return the socket's file descriptor (a small integer). This is useful |
| 226 | with \code{select}. |
| 227 | \end{funcdesc} |
| 228 | |
| 229 | \begin{funcdesc}{getpeername}{} |
| 230 | Return the remote address to which the socket is connected. This is |
| 231 | 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] | 232 | (The format of the address returned depends on the address family --- |
Guido van Rossum | 781db5d | 1994-08-05 13:37:36 +0000 | [diff] [blame] | 233 | see above.) On some systems this function is not supported. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 234 | \end{funcdesc} |
| 235 | |
| 236 | \begin{funcdesc}{getsockname}{} |
| 237 | Return the socket's own address. This is useful to find out the port |
| 238 | number of an IP socket, for instance. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 239 | (The format of the address returned depends on the address family --- |
Guido van Rossum | a84ec51 | 1994-06-23 12:13:52 +0000 | [diff] [blame] | 240 | see above.) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 241 | \end{funcdesc} |
| 242 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 243 | \begin{funcdesc}{getsockopt}{level\, optname\optional{\, buflen}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 244 | Return the value of the given socket option (see the \UNIX{} man page |
Fred Drake | 9eb5e50 | 1998-01-20 04:54:23 +0000 | [diff] [blame^] | 245 | \emph{getsockopt}(2)). The needed symbolic constants (\code{SO_*} etc.) |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 246 | are defined in this module. If \var{buflen} |
| 247 | is absent, an integer option is assumed and its integer value |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 248 | is returned by the function. If \var{buflen} is present, it specifies |
| 249 | 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] | 250 | 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] | 251 | the contents of the buffer (see the optional built-in module |
| 252 | \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] | 253 | \end{funcdesc} |
| 254 | |
| 255 | \begin{funcdesc}{listen}{backlog} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 256 | Listen for connections made to the socket. The \var{backlog} argument |
| 257 | specifies the maximum number of queued connections and should be at |
| 258 | least 1; the maximum value is system-dependent (usually 5). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 259 | \end{funcdesc} |
| 260 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 261 | \begin{funcdesc}{makefile}{\optional{mode\optional{\, bufsize}}} |
| 262 | Return a \dfn{file object} associated with the socket. (File objects |
| 263 | were described earlier under Built-in Types.) The file object |
| 264 | references a \code{dup()}ped version of the socket file descriptor, so |
| 265 | the file object and socket object may be closed or garbage-collected |
| 266 | independently. The optional \var{mode} and \var{bufsize} arguments |
| 267 | are interpreted the same way as by the built-in |
| 268 | \code{open()} function. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 269 | \end{funcdesc} |
| 270 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 271 | \begin{funcdesc}{recv}{bufsize\optional{\, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 272 | Receive data from the socket. The return value is a string representing |
| 273 | the data received. The maximum amount of data to be received |
| 274 | at once is specified by \var{bufsize}. See the \UNIX{} manual page |
| 275 | for the meaning of the optional argument \var{flags}; it defaults to |
| 276 | zero. |
| 277 | \end{funcdesc} |
| 278 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 279 | \begin{funcdesc}{recvfrom}{bufsize\optional{\, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 280 | Receive data from the socket. The return value is a pair |
| 281 | \code{(\var{string}, \var{address})} where \var{string} is a string |
| 282 | 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] | 283 | socket sending the data. The optional \var{flags} argument has the |
| 284 | same meaning as for \code{recv()} above. |
Guido van Rossum | 8675115 | 1995-02-28 17:14:32 +0000 | [diff] [blame] | 285 | (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] | 286 | \end{funcdesc} |
| 287 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 288 | \begin{funcdesc}{send}{string\optional{\, flags}} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 289 | 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] | 290 | socket. The optional \var{flags} argument has the same meaning as for |
| 291 | \code{recv()} above. Return the number of bytes sent. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 292 | \end{funcdesc} |
| 293 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 294 | \begin{funcdesc}{sendto}{string\optional{\, flags}\, address} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 295 | Send data to the socket. The socket should not be connected to a |
| 296 | remote socket, since the destination socket is specified by |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 297 | \code{address}. The optional \var{flags} argument has the same |
| 298 | 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] | 299 | (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] | 300 | \end{funcdesc} |
| 301 | |
Guido van Rossum | 9195148 | 1994-09-07 14:39:14 +0000 | [diff] [blame] | 302 | \begin{funcdesc}{setblocking}{flag} |
| 303 | Set blocking or non-blocking mode of the socket: if \var{flag} is 0, |
| 304 | the socket is set to non-blocking, else to blocking mode. Initially |
| 305 | all sockets are in blocking mode. In non-blocking mode, if a |
| 306 | \code{recv} call doesn't find any data, or if a \code{send} call can't |
| 307 | immediately dispose of the data, a \code{socket.error} exception is |
| 308 | raised; in blocking mode, the calls block until they can proceed. |
| 309 | \end{funcdesc} |
| 310 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 311 | \begin{funcdesc}{setsockopt}{level\, optname\, value} |
| 312 | Set the value of the given socket option (see the \UNIX{} man page |
Fred Drake | 9eb5e50 | 1998-01-20 04:54:23 +0000 | [diff] [blame^] | 313 | \emph{setsockopt}(2)). The needed symbolic constants are defined in |
Guido van Rossum | 8df3637 | 1995-02-27 17:52:15 +0000 | [diff] [blame] | 314 | the \code{socket} module (\code{SO_*} etc.). The value can be an |
| 315 | integer or a string representing a buffer. In the latter case it is |
| 316 | up to the caller to ensure that the string contains the proper bits |
| 317 | (see the optional built-in module |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 318 | \code{struct} for a way to encode C structures as strings). |
| 319 | \end{funcdesc} |
| 320 | |
| 321 | \begin{funcdesc}{shutdown}{how} |
| 322 | Shut down one or both halves of the connection. If \var{how} is \code{0}, |
| 323 | further receives are disallowed. If \var{how} is \code{1}, further sends are |
| 324 | disallowed. If \var{how} is \code{2}, further sends and receives are |
| 325 | disallowed. |
| 326 | \end{funcdesc} |
| 327 | |
| 328 | Note that there are no methods \code{read()} or \code{write()}; use |
| 329 | \code{recv()} and \code{send()} without \var{flags} argument instead. |
| 330 | |
| 331 | \subsection{Example} |
| 332 | \nodename{Socket Example} |
| 333 | |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 334 | 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] | 335 | server that echoes all data that it receives back (servicing only one |
| 336 | client), and a client using it. Note that a server must perform the |
| 337 | sequence \code{socket}, \code{bind}, \code{listen}, \code{accept} |
| 338 | (possibly repeating the \code{accept} to service more than one client), |
| 339 | while a client only needs the sequence \code{socket}, \code{connect}. |
| 340 | Also note that the server does not \code{send}/\code{receive} on the |
| 341 | socket it is listening on but on the new socket returned by |
| 342 | \code{accept}. |
| 343 | |
| 344 | \bcode\begin{verbatim} |
| 345 | # Echo server program |
| 346 | from socket import * |
| 347 | HOST = '' # Symbolic name meaning the local host |
| 348 | PORT = 50007 # Arbitrary non-privileged server |
| 349 | s = socket(AF_INET, SOCK_STREAM) |
| 350 | s.bind(HOST, PORT) |
Guido van Rossum | 5da5755 | 1994-03-02 10:52:16 +0000 | [diff] [blame] | 351 | s.listen(1) |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 352 | conn, addr = s.accept() |
| 353 | print 'Connected by', addr |
| 354 | while 1: |
| 355 | data = conn.recv(1024) |
| 356 | if not data: break |
| 357 | conn.send(data) |
| 358 | conn.close() |
| 359 | \end{verbatim}\ecode |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 360 | % |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 361 | \bcode\begin{verbatim} |
| 362 | # Echo client program |
| 363 | from socket import * |
| 364 | HOST = 'daring.cwi.nl' # The remote host |
| 365 | PORT = 50007 # The same port as used by the server |
| 366 | s = socket(AF_INET, SOCK_STREAM) |
| 367 | s.connect(HOST, PORT) |
| 368 | s.send('Hello, world') |
| 369 | data = s.recv(1024) |
| 370 | s.close() |
| 371 | print 'Received', `data` |
| 372 | \end{verbatim}\ecode |
Guido van Rossum | e47da0a | 1997-07-17 16:34:52 +0000 | [diff] [blame] | 373 | % |
| 374 | \begin{seealso} |
| 375 | \seemodule{SocketServer}{classes that simplify writing network servers} |
| 376 | \end{seealso} |