diff options
Diffstat (limited to 'Doc/libsocket.tex')
| -rw-r--r-- | Doc/libsocket.tex | 380 |
1 files changed, 0 insertions, 380 deletions
diff --git a/Doc/libsocket.tex b/Doc/libsocket.tex deleted file mode 100644 index 76d2b1a..0000000 --- a/Doc/libsocket.tex +++ /dev/null @@ -1,380 +0,0 @@ -\section{Built-in Module \module{socket}} -\label{module-socket} -\bimodindex{socket} - -This module provides access to the BSD \emph{socket} interface. -It is available on \UNIX{} systems that support this interface. - -For an introduction to socket programming (in C), see the following -papers: \emph{An Introductory 4.3BSD Interprocess Communication -Tutorial}, by Stuart Sechrest and \emph{An Advanced 4.3BSD Interprocess -Communication Tutorial}, by Samuel J. Leffler et al, both in the -\UNIX{} Programmer's Manual, Supplementary Documents 1 (sections PS1:7 -and PS1:8). The \UNIX{} manual pages for the various socket-related -system calls are also a valuable source of information on the details of -socket semantics. - -The Python interface is a straightforward transliteration of the -\UNIX{} system call and library interface for sockets to Python's -object-oriented style: the \function{socket()} function returns a -\dfn{socket object} whose methods implement the various socket system -calls. Parameter types are somewhat higher-level than in the C -interface: as with \method{read()} and \method{write()} operations on -Python files, buffer allocation on receive operations is automatic, -and buffer length is implicit on send operations. - -Socket addresses are represented as a single string for the -\constant{AF_UNIX} address family and as a pair -\code{(\var{host}, \var{port})} for the \constant{AF_INET} address -family, where \var{host} is a string representing -either a hostname in Internet domain notation like -\code{'daring.cwi.nl'} or an IP address like \code{'100.50.200.5'}, -and \var{port} is an integral port number. Other address families are -currently not supported. The address format required by a particular -socket object is automatically selected based on the address family -specified when the socket object was created. - -For IP addresses, two special forms are accepted instead of a host -address: the empty string represents \constant{INADDR_ANY}, and the string -\code{"<broadcast>"} represents \constant{INADDR_BROADCAST}. - -All errors raise exceptions. The normal exceptions for invalid -argument types and out-of-memory conditions can be raised; errors -related to socket or address semantics raise the error \code{socket.error}. - -Non-blocking mode is supported through the \code{setblocking()} -method. - -The module \module{socket} exports the following constants and functions: - - -\begin{excdesc}{error} -This exception is raised for socket- or address-related errors. -The accompanying value is either a string telling what went wrong or a -pair \code{(\var{errno}, \var{string})} -representing an error returned by a system -call, similar to the value accompanying \code{os.error}. -See the module \module{errno}\refbimodindex{errno}, which contains -names for the error codes defined by the underlying operating system. -\end{excdesc} - -\begin{datadesc}{AF_UNIX} -\dataline{AF_INET} -These constants represent the address (and protocol) families, -used for the first argument to \function{socket()}. If the -\constant{AF_UNIX} constant is not defined then this protocol is -unsupported. -\end{datadesc} - -\begin{datadesc}{SOCK_STREAM} -\dataline{SOCK_DGRAM} -\dataline{SOCK_RAW} -\dataline{SOCK_RDM} -\dataline{SOCK_SEQPACKET} -These constants represent the socket types, -used for the second argument to \function{socket()}. -(Only \constant{SOCK_STREAM} and -\constant{SOCK_DGRAM} appear to be generally useful.) -\end{datadesc} - -\begin{datadesc}{SO_*} -\dataline{SOMAXCONN} -\dataline{MSG_*} -\dataline{SOL_*} -\dataline{IPPROTO_*} -\dataline{IPPORT_*} -\dataline{INADDR_*} -\dataline{IP_*} -Many constants of these forms, documented in the \UNIX{} documentation on -sockets and/or the IP protocol, are also defined in the socket module. -They are generally used in arguments to the \method{setsockopt()} and -\method{getsockopt()} methods of socket objects. In most cases, only -those symbols that are defined in the \UNIX{} header files are defined; -for a few symbols, default values are provided. -\end{datadesc} - -\begin{funcdesc}{gethostbyname}{hostname} -Translate a host name to IP address format. The IP address is -returned as a string, e.g., \code{'100.50.200.5'}. If the host name -is an IP address itself it is returned unchanged. -\end{funcdesc} - -\begin{funcdesc}{gethostname}{} -Return a string containing the hostname of the machine where -the Python interpreter is currently executing. If you want to know the -current machine's IP address, use \code{gethostbyname(gethostname())}. -Note: \function{gethostname()} doesn't always return the fully qualified -domain name; use \code{gethostbyaddr(gethostname())} -(see below). -\end{funcdesc} - -\begin{funcdesc}{gethostbyaddr}{ip_address} -Return a triple \code{(\var{hostname}, \var{aliaslist}, -\var{ipaddrlist})} where \var{hostname} is the primary host name -responding to the given \var{ip_address}, \var{aliaslist} is a -(possibly empty) list of alternative host names for the same address, -and \var{ipaddrlist} is a list of IP addresses for the same interface -on the same host (most likely containing only a single address). -To find the fully qualified domain name, check \var{hostname} and the -items of \var{aliaslist} for an entry containing at least one period. -\end{funcdesc} - -\begin{funcdesc}{getprotobyname}{protocolname} -Translate an Internet protocol name (e.g. \code{'icmp'}) to a constant -suitable for passing as the (optional) third argument to the -\function{socket()} function. This is usually only needed for sockets -opened in ``raw'' mode (\constant{SOCK_RAW}); for the normal socket -modes, the correct protocol is chosen automatically if the protocol is -omitted or zero. -\end{funcdesc} - -\begin{funcdesc}{getservbyname}{servicename, protocolname} -Translate an Internet service name and protocol name to a port number -for that service. The protocol name should be \code{'tcp'} or -\code{'udp'}. -\end{funcdesc} - -\begin{funcdesc}{socket}{family, type\optional{, proto}} -Create a new socket using the given address family, socket type and -protocol number. The address family should be \constant{AF_INET} or -\constant{AF_UNIX}. The socket type should be \constant{SOCK_STREAM}, -\constant{SOCK_DGRAM} or perhaps one of the other \samp{SOCK_} constants. -The protocol number is usually zero and may be omitted in that case. -\end{funcdesc} - -\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}} -Build a socket object from an existing file descriptor (an integer as -returned by a file object's \method{fileno()} method). Address family, -socket type and protocol number are as for the \code{socket} function -above. The file descriptor should refer to a socket, but this is not -checked --- subsequent operations on the object may fail if the file -descriptor is invalid. This function is rarely needed, but can be -used to get or set socket options on a socket passed to a program as -standard input or output (e.g.\ a server started by the \UNIX{} inet -daemon). -\end{funcdesc} - -\begin{funcdesc}{ntohl}{x} -Convert 32-bit integers from network to host byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 4-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{ntohs}{x} -Convert 16-bit integers from network to host byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 2-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{htonl}{x} -Convert 32-bit integers from host to network byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 4-byte swap operation. -\end{funcdesc} - -\begin{funcdesc}{htons}{x} -Convert 16-bit integers from host to network byte order. On machines -where the host byte order is the same as network byte order, this is a -no-op; otherwise, it performs a 2-byte swap operation. -\end{funcdesc} - -\begin{datadesc}{SocketType} -This is a Python type object that represents the socket object type. -It is the same as \code{type(socket(...))}. -\end{datadesc} - -\subsection{Socket Objects} - -Socket objects have the following methods. Except for -\method{makefile()} these correspond to \UNIX{} system calls -applicable to sockets. - -\begin{methoddesc}[socket]{accept}{} -Accept a connection. -The socket must be bound to an address and listening for connections. -The return value is a pair \code{(\var{conn}, \var{address})} -where \var{conn} is a \emph{new} socket object usable to send and -receive data on the connection, and \var{address} is the address bound -to the socket on the other end of the connection. -\end{methoddesc} - -\begin{methoddesc}[socket]{bind}{address} -Bind the socket to \var{address}. The socket must not already be bound. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{close}{} -Close the socket. All future operations on the socket object will fail. -The remote end will receive no more data (after queued data is flushed). -Sockets are automatically closed when they are garbage-collected. -\end{methoddesc} - -\begin{methoddesc}[socket]{connect}{address} -Connect to a remote socket at \var{address}. -(The format of \var{address} depends on the address family --- see -above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{connect_ex}{address} -Like \code{connect(\var{address})}, but return an error indicator -instead of raising an exception. The error indicator is 0 if the -operation succeeded, otherwise the value of the \cdata{errno} -variable. This is useful, e.g., for asynchronous connects. -\end{methoddesc} - -\begin{methoddesc}[socket]{fileno}{} -Return the socket's file descriptor (a small integer). This is useful -with \function{select.select()}. -\end{methoddesc} - -\begin{methoddesc}[socket]{getpeername}{} -Return the remote address to which the socket is connected. This is -useful to find out the port number of a remote IP socket, for instance. -(The format of the address returned depends on the address family --- -see above.) On some systems this function is not supported. -\end{methoddesc} - -\begin{methoddesc}[socket]{getsockname}{} -Return the socket's own address. This is useful to find out the port -number of an IP socket, for instance. -(The format of the address returned depends on the address family --- -see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{getsockopt}{level, optname\optional{, buflen}} -Return the value of the given socket option (see the \UNIX{} man page -\manpage{getsockopt}{2}). The needed symbolic constants -(\constant{SO_*} etc.) are defined in this module. If \var{buflen} -is absent, an integer option is assumed and its integer value -is returned by the function. If \var{buflen} is present, it specifies -the maximum length of the buffer used to receive the option in, and -this buffer is returned as a string. It is up to the caller to decode -the contents of the buffer (see the optional built-in module -\module{struct} for a way to decode C structures encoded as strings). -\end{methoddesc} - -\begin{methoddesc}[socket]{listen}{backlog} -Listen for connections made to the socket. The \var{backlog} argument -specifies the maximum number of queued connections and should be at -least 1; the maximum value is system-dependent (usually 5). -\end{methoddesc} - -\begin{methoddesc}[socket]{makefile}{\optional{mode\optional{, bufsize}}} -Return a \dfn{file object} associated with the socket. (File objects -were described earlier in \ref{bltin-file-objects}, ``File Objects.'') -The file object references a \cfunction{dup()}ped version of the -socket file descriptor, so the file object and socket object may be -closed or garbage-collected independently. The optional \var{mode} -and \var{bufsize} arguments are interpreted the same way as by the -built-in \function{open()} function. -\end{methoddesc} - -\begin{methoddesc}[socket]{recv}{bufsize\optional{, flags}} -Receive data from the socket. The return value is a string representing -the data received. The maximum amount of data to be received -at once is specified by \var{bufsize}. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. -\end{methoddesc} - -\begin{methoddesc}[socket]{recvfrom}{bufsize\optional{, flags}} -Receive data from the socket. The return value is a pair -\code{(\var{string}, \var{address})} where \var{string} is a string -representing the data received and \var{address} is the address of the -socket sending the data. The optional \var{flags} argument has the -same meaning as for \method{recv()} above. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{send}{string\optional{, flags}} -Send data to the socket. The socket must be connected to a remote -socket. The optional \var{flags} argument has the same meaning as for -\method{recv()} above. Returns the number of bytes sent. -\end{methoddesc} - -\begin{methoddesc}[socket]{sendto}{string\optional{, flags}, address} -Send data to the socket. The socket should not be connected to a -remote socket, since the destination socket is specified by -\var{address}. The optional \var{flags} argument has the same -meaning as for \method{recv()} above. Return the number of bytes sent. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{setblocking}{flag} -Set blocking or non-blocking mode of the socket: if \var{flag} is 0, -the socket is set to non-blocking, else to blocking mode. Initially -all sockets are in blocking mode. In non-blocking mode, if a -\method{recv()} call doesn't find any data, or if a \code{send} call can't -immediately dispose of the data, a \exception{error} exception is -raised; in blocking mode, the calls block until they can proceed. -\end{methoddesc} - -\begin{methoddesc}[socket]{setsockopt}{level, optname, value} -Set the value of the given socket option (see the \UNIX{} man page -\manpage{setsockopt}{2}). The needed symbolic constants are defined in -the \module{socket} module (\code{SO_*} etc.). The value can be an -integer or a string representing a buffer. In the latter case it is -up to the caller to ensure that the string contains the proper bits -(see the optional built-in module -\module{struct}\refbimodindex{struct} for a way to encode C structures -as strings). -\end{methoddesc} - -\begin{methoddesc}[socket]{shutdown}{how} -Shut down one or both halves of the connection. If \var{how} is -\code{0}, further receives are disallowed. If \var{how} is \code{1}, -further sends are disallowed. If \var{how} is \code{2}, further sends -and receives are disallowed. -\end{methoddesc} - -Note that there are no methods \method{read()} or \method{write()}; -use \method{recv()} and \method{send()} without \var{flags} argument -instead. - -\subsection{Example} -\nodename{Socket Example} - -Here are two minimal example programs using the TCP/IP protocol:\ a -server that echoes all data that it receives back (servicing only one -client), and a client using it. Note that a server must perform the -sequence \function{socket()}, \method{bind()}, \method{listen()}, -\method{accept()} (possibly repeating the \method{accept()} to service -more than one client), while a client only needs the sequence -\function{socket()}, \method{connect()}. Also note that the server -does not \method{send()}/\method{recv()} on the -socket it is listening on but on the new socket returned by -\method{accept()}. - -\begin{verbatim} -# Echo server program -from socket import * -HOST = '' # Symbolic name meaning the local host -PORT = 50007 # Arbitrary non-privileged server -s = socket(AF_INET, SOCK_STREAM) -s.bind(HOST, PORT) -s.listen(1) -conn, addr = s.accept() -print 'Connected by', addr -while 1: - data = conn.recv(1024) - if not data: break - conn.send(data) -conn.close() -\end{verbatim} - -\begin{verbatim} -# Echo client program -from socket import * -HOST = 'daring.cwi.nl' # The remote host -PORT = 50007 # The same port as used by the server -s = socket(AF_INET, SOCK_STREAM) -s.connect(HOST, PORT) -s.send('Hello, world') -data = s.recv(1024) -s.close() -print 'Received', `data` -\end{verbatim} - -\begin{seealso} -\seemodule{SocketServer}{classes that simplify writing network servers} -\end{seealso} |