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