diff options
Diffstat (limited to 'Doc/lib/libsocket.tex')
| -rw-r--r-- | Doc/lib/libsocket.tex | 921 |
1 files changed, 0 insertions, 921 deletions
diff --git a/Doc/lib/libsocket.tex b/Doc/lib/libsocket.tex deleted file mode 100644 index e3fce23..0000000 --- a/Doc/lib/libsocket.tex +++ /dev/null @@ -1,921 +0,0 @@ -\section{\module{socket} --- - Low-level networking interface} - -\declaremodule{builtin}{socket} -\modulesynopsis{Low-level networking interface.} - - -This module provides access to the BSD \emph{socket} interface. -It is available on all modern \UNIX{} systems, Windows, MacOS, BeOS, -OS/2, and probably additional platforms. \note{Some behavior may be -platform dependent, since calls are made to the operating system socket APIs.} - -For an introduction to socket programming (in C), see the following -papers: \citetitle{An Introductory 4.3BSD Interprocess Communication -Tutorial}, by Stuart Sechrest and \citetitle{An Advanced 4.3BSD -Interprocess Communication Tutorial}, by Samuel J. Leffler et al, -both in the \citetitle{UNIX Programmer's Manual, Supplementary Documents 1} -(sections PS1:7 and PS1:8). The platform-specific reference material -for the various socket-related system calls are also a valuable source -of information on the details of socket semantics. For \UNIX, refer -to the manual pages; for Windows, see the WinSock (or Winsock 2) -specification. -For IPv6-ready APIs, readers may want to refer to \rfc{2553} titled -\citetitle{Basic Socket Interface Extensions for IPv6}. - -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}\obindex{socket} 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 follows: -A single string is used for the \constant{AF_UNIX} address family. -A pair \code{(\var{host}, \var{port})} is used 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 IPv4 address like \code{'100.50.200.5'}, -and \var{port} is an integral port number. -For \constant{AF_INET6} address family, a four-tuple -\code{(\var{host}, \var{port}, \var{flowinfo}, \var{scopeid})} is -used, where \var{flowinfo} and \var{scopeid} represents -\code{sin6_flowinfo} and \code{sin6_scope_id} member in -\constant{struct sockaddr_in6} in C. -For \module{socket} module methods, \var{flowinfo} and \var{scopeid} -can be omitted just for backward compatibility. Note, however, -omission of \var{scopeid} can cause problems in manipulating scoped -IPv6 addresses. 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 IPv4 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}. -The behavior is not available for IPv6 for backward compatibility, -therefore, you may want to avoid these if you intend to support IPv6 with -your Python programs. - -If you use a hostname in the \var{host} portion of IPv4/v6 socket -address, the program may show a nondeterministic behavior, as Python -uses the first address returned from the DNS resolution. The socket -address will be resolved differently into an actual IPv4/v6 address, -depending on the results from DNS resolution and/or the host -configuration. For deterministic behavior use a numeric address in -\var{host} portion. - -\versionadded[AF_NETLINK sockets are represented as -pairs \code{\var{pid}, \var{groups}}]{2.5} - -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 -\exception{socket.error}. - -Non-blocking mode is supported through -\method{setblocking()}. A generalization of this based on timeouts -is supported through \method{settimeout()}. - -The module \module{socket} exports the following constants and functions: - - -\begin{excdesc}{error} -This exception is raised for socket-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 \exception{os.error}. -See the module \refmodule{errno}\refbimodindex{errno}, which contains -names for the error codes defined by the underlying operating system. -\end{excdesc} - -\begin{excdesc}{herror} -This exception is raised for address-related errors, i.e. for -functions that use \var{h_errno} in the C API, including -\function{gethostbyname_ex()} and \function{gethostbyaddr()}. - -The accompanying value is a pair \code{(\var{h_errno}, \var{string})} -representing an error returned by a library call. \var{string} -represents the description of \var{h_errno}, as returned by -the \cfunction{hstrerror()} C function. -\end{excdesc} - -\begin{excdesc}{gaierror} -This exception is raised for address-related errors, for -\function{getaddrinfo()} and \function{getnameinfo()}. -The accompanying value is a pair \code{(\var{error}, \var{string})} -representing an error returned by a library call. -\var{string} represents the description of \var{error}, as returned -by the \cfunction{gai_strerror()} C function. -The \var{error} value will match one of the \constant{EAI_*} constants -defined in this module. -\end{excdesc} - -\begin{excdesc}{timeout} -This exception is raised when a timeout occurs on a socket which has -had timeouts enabled via a prior call to \method{settimeout()}. The -accompanying value is a string whose value is currently always ``timed -out''. -\versionadded{2.3} -\end{excdesc} - -\begin{datadesc}{AF_UNIX} -\dataline{AF_INET} -\dataline{AF_INET6} -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_*} -\dataline{IPV6_*} -\dataline{EAI_*} -\dataline{AI_*} -\dataline{NI_*} -\dataline{TCP_*} -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{datadesc}{has_ipv6} -This constant contains a boolean value which indicates if IPv6 is -supported on this platform. -\versionadded{2.3} -\end{datadesc} - -\begin{funcdesc}{create_connection}{address\optional{, timeout}} -Connects to the \var{address} received (as usual, a \code{(host, port)} -pair), with an optional timeout for the connection. Specially useful for -higher-level protocols, it is not normally used directly from -application-level code. Passing the optional \var{timeout} parameter -will set the timeout on the socket instance (if it is not given or -\code{None}, the global default timeout setting is used). -\versionadded{2.6} -\end{funcdesc} - -\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{, - socktype\optional{, proto\optional{, - flags}}}}} -Resolves the \var{host}/\var{port} argument, into a sequence of -5-tuples that contain all the necessary argument for the sockets -manipulation. \var{host} is a domain name, a string representation of -IPv4/v6 address or \code{None}. -\var{port} is a string service name (like \code{'http'}), a numeric -port number or \code{None}. - -The rest of the arguments are optional and must be numeric if -specified. For \var{host} and \var{port}, by passing either an empty -string or \code{None}, you can pass \code{NULL} to the C API. The -\function{getaddrinfo()} function returns a list of 5-tuples with -the following structure: - -\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, - \var{sockaddr})} - -\var{family}, \var{socktype}, \var{proto} are all integer and are meant to -be passed to the \function{socket()} function. -\var{canonname} is a string representing the canonical name of the \var{host}. -It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified -for a numeric \var{host}. -\var{sockaddr} is a tuple describing a socket address, as described above. -See the source for the \refmodule{httplib} and other library modules -for a typical usage of the function. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{getfqdn}{\optional{name}} -Return a fully qualified domain name for \var{name}. -If \var{name} is omitted or empty, it is interpreted as the local -host. To find the fully qualified name, the hostname returned by -\function{gethostbyaddr()} is checked, then aliases for the host, if -available. The first name which includes a period is selected. In -case no fully qualified domain name is available, the hostname as -returned by \function{gethostname()} is returned. -\versionadded{2.0} -\end{funcdesc} - -\begin{funcdesc}{gethostbyname}{hostname} -Translate a host name to IPv4 address format. The IPv4 address is -returned as a string, such as \code{'100.50.200.5'}. If the host name -is an IPv4 address itself it is returned unchanged. See -\function{gethostbyname_ex()} for a more complete interface. -\function{gethostbyname()} does not support IPv6 name resolution, and -\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. -\end{funcdesc} - -\begin{funcdesc}{gethostbyname_ex}{hostname} -Translate a host name to IPv4 address format, extended interface. -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 IPv4 addresses for the same interface on the same -host (often but not always a single address). -\function{gethostbyname_ex()} does not support IPv6 name resolution, and -\function{getaddrinfo()} should be used instead for IPv4/v6 dual stack support. -\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, you may want to use -\code{gethostbyname(gethostname())}. -This operation assumes that there is a valid address-to-host mapping for -the host, and the assumption does not always hold. -Note: \function{gethostname()} doesn't always return the fully qualified -domain name; use \code{getfqdn()} -(see above). -\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 IPv4/v6 addresses for the same interface -on the same host (most likely containing only a single address). -To find the fully qualified domain name, use the function -\function{getfqdn()}. -\function{gethostbyaddr} supports both IPv4 and IPv6. -\end{funcdesc} - -\begin{funcdesc}{getnameinfo}{sockaddr, flags} -Translate a socket address \var{sockaddr} into a 2-tuple -\code{(\var{host}, \var{port})}. -Depending on the settings of \var{flags}, the result can contain a -fully-qualified domain name or numeric address representation in -\var{host}. Similarly, \var{port} can contain a string port name or a -numeric port number. -\versionadded{2.2} -\end{funcdesc} - -\begin{funcdesc}{getprotobyname}{protocolname} -Translate an Internet protocol name (for example, \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\optional{, protocolname}} -Translate an Internet service name and protocol name to a port number -for that service. The optional protocol name, if given, should be -\code{'tcp'} or \code{'udp'}, otherwise any protocol will match. -\end{funcdesc} - -\begin{funcdesc}{getservbyport}{port\optional{, protocolname}} -Translate an Internet port number and protocol name to a service name -for that service. The optional protocol name, if given, should be -\code{'tcp'} or \code{'udp'}, otherwise any protocol will match. -\end{funcdesc} - -\begin{funcdesc}{socket}{\optional{family\optional{, - 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} (the -default), \constant{AF_INET6} or \constant{AF_UNIX}. The socket type -should be \constant{SOCK_STREAM} (the default), \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}{ssl}{sock\optional{, keyfile, certfile}} -Initiate a SSL connection over the socket \var{sock}. \var{keyfile} is -the name of a PEM formatted file that contains your private -key. \var{certfile} is a PEM formatted certificate chain file. On -success, a new \class{SSLObject} is returned. - -\warning{This does not do any certificate verification!} -\end{funcdesc} - -\begin{funcdesc}{socketpair}{\optional{family\optional{, type\optional{, proto}}}} -Build a pair of connected socket objects using the given address -family, socket type, and protocol number. Address family, socket type, -and protocol number are as for the \function{socket()} function above. -The default family is \constant{AF_UNIX} if defined on the platform; -otherwise, the default is \constant{AF_INET}. -Availability: \UNIX. \versionadded{2.4} -\end{funcdesc} - -\begin{funcdesc}{fromfd}{fd, family, type\optional{, proto}} -Duplicate the file descriptor \var{fd} (an integer as returned by a file -object's \method{fileno()} method) and build a socket object from the -result. Address family, socket type and protocol number are as for the -\function{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 (such as a server started by the \UNIX{} inet -daemon). The socket is assumed to be in blocking mode. -Availability: \UNIX. -\end{funcdesc} - -\begin{funcdesc}{ntohl}{x} -Convert 32-bit positive 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 positive 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 positive 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 positive 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{funcdesc}{inet_aton}{ip_string} -Convert an IPv4 address from dotted-quad string format (for example, -'123.45.67.89') to 32-bit packed binary format, as a string four -characters in length. This is useful when conversing with a program -that uses the standard C library and needs objects of type -\ctype{struct in_addr}, which is the C type for the 32-bit packed -binary this function returns. - -If the IPv4 address string passed to this function is invalid, -\exception{socket.error} will be raised. Note that exactly what is -valid depends on the underlying C implementation of -\cfunction{inet_aton()}. - -\function{inet_aton()} does not support IPv6, and -\function{getnameinfo()} should be used instead for IPv4/v6 dual stack -support. -\end{funcdesc} - -\begin{funcdesc}{inet_ntoa}{packed_ip} -Convert a 32-bit packed IPv4 address (a string four characters in -length) to its standard dotted-quad string representation (for -example, '123.45.67.89'). This is useful when conversing with a -program that uses the standard C library and needs objects of type -\ctype{struct in_addr}, which is the C type for the 32-bit packed -binary data this function takes as an argument. - -If the string passed to this function is not exactly 4 bytes in -length, \exception{socket.error} will be raised. -\function{inet_ntoa()} does not support IPv6, and -\function{getnameinfo()} should be used instead for IPv4/v6 dual stack -support. -\end{funcdesc} - -\begin{funcdesc}{inet_pton}{address_family, ip_string} -Convert an IP address from its family-specific string format to a packed, -binary format. -\function{inet_pton()} is useful when a library or network protocol calls for -an object of type \ctype{struct in_addr} (similar to \function{inet_aton()}) -or \ctype{struct in6_addr}. - -Supported values for \var{address_family} are currently -\constant{AF_INET} and \constant{AF_INET6}. -If the IP address string \var{ip_string} is invalid, -\exception{socket.error} will be raised. Note that exactly what is valid -depends on both the value of \var{address_family} and the underlying -implementation of \cfunction{inet_pton()}. - -Availability: \UNIX{} (maybe not all platforms). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{inet_ntop}{address_family, packed_ip} -Convert a packed IP address (a string of some number of characters) to -its standard, family-specific string representation (for example, -\code{'7.10.0.5'} or \code{'5aef:2b::8'}) -\function{inet_ntop()} is useful when a library or network protocol returns -an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()}) -or \ctype{struct in6_addr}. - -Supported values for \var{address_family} are currently -\constant{AF_INET} and \constant{AF_INET6}. -If the string \var{packed_ip} is not the correct length for the -specified address family, \exception{ValueError} will be raised. A -\exception{socket.error} is raised for errors from the call to -\function{inet_ntop()}. - -Availability: \UNIX{} (maybe not all platforms). -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{getdefaulttimeout}{} -Return the default timeout in floating seconds for new socket objects. -A value of \code{None} indicates that new socket objects have no timeout. -When the socket module is first imported, the default is \code{None}. -\versionadded{2.3} -\end{funcdesc} - -\begin{funcdesc}{setdefaulttimeout}{timeout} -Set the default timeout in floating seconds for new socket objects. -A value of \code{None} indicates that new socket objects have no timeout. -When the socket module is first imported, the default is \code{None}. -\versionadded{2.3} -\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} - - -\begin{seealso} - \seemodule{SocketServer}{Classes that simplify writing network servers.} -\end{seealso} - - -\subsection{Socket Objects \label{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.) \note{This method has historically accepted a pair -of parameters for \constant{AF_INET} addresses instead of only a -tuple. This was never intentional and is no longer available in -Python 2.0 and later.} -\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.) \note{This method has historically accepted a pair -of parameters for \constant{AF_INET} addresses instead of only a -tuple. This was never intentional and is no longer available in -Python 2.0 and later.} -\end{methoddesc} - -\begin{methoddesc}[socket]{connect_ex}{address} -Like \code{connect(\var{address})}, but return an error indicator -instead of raising an exception for errors returned by the C-level -\cfunction{connect()} call (other problems, such as ``host not found,'' -can still raise exceptions). The error indicator is \code{0} if the -operation succeeded, otherwise the value of the \cdata{errno} -variable. This is useful to support, for example, asynchronous connects. -\note{This method has historically accepted a pair of -parameters for \constant{AF_INET} addresses instead of only a tuple. -This was never intentional and is no longer available in Python -2.0 and later.} -\end{methoddesc} - -\begin{methoddesc}[socket]{fileno}{} -Return the socket's file descriptor (a small integer). This is useful -with \function{select.select()}. - -Under Windows the small integer returned by this method cannot be used where -a file descriptor can be used (such as \function{os.fdopen()}). \UNIX{} does -not have this limitation. -\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 IPv4/v6 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 IPv4/v6 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 -\refmodule{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 -are described 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 socket must be in blocking mode (it can not have a timeout). -\index{I/O control!buffering}The optional \var{mode} -and \var{bufsize} arguments are interpreted the same way as by the -built-in \function{file()} function; see ``Built-in Functions'' -(section \ref{built-in-funcs}) for more information. -\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. -\note{For best match with hardware and network realities, the value of -\var{bufsize} should be a relatively small power of 2, for example, 4096.} -\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. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. -(The format of \var{address} depends on the address family --- see above.) -\end{methoddesc} - -\begin{methoddesc}[socket]{recvfrom_into}{buffer\optional{, nbytes\optional{, flags}}} -Receive data from the socket, writing it into \var{buffer} instead of -creating a new string. The return value is a pair -\code{(\var{nbytes}, \var{address})} where \var{nbytes} is the number -of bytes received and \var{address} is the address of the socket -sending the data. See the \UNIX{} manual page -\manpage{recv}{2} for the meaning of the optional argument -\var{flags}; it defaults to zero. (The format of \var{address} -depends on the address family --- see above.) -\versionadded{2.5} -\end{methoddesc} - -\begin{methoddesc}[socket]{recv_into}{buffer\optional{, nbytes\optional{, flags}}} -Receive up to \var{nbytes} bytes from the socket, -storing the data into a buffer rather than creating a new string. -If \var{nbytes} is not specified (or 0), -receive up to the size available in the given buffer. -See the \UNIX{} manual page \manpage{recv}{2} for the meaning of the -optional argument \var{flags}; it defaults to zero. -\versionadded{2.5} -\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. -Applications are responsible for checking that all data has been sent; -if only some of the data was transmitted, the application needs to -attempt delivery of the remaining data. -\end{methoddesc} - -\begin{methoddesc}[socket]{sendall}{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. Unlike \method{send()}, this method continues -to send data from \var{string} until either all data has been sent or -an error occurs. \code{None} is returned on success. On error, an -exception is raised, and there is no way to determine how much data, -if any, was successfully 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 -\method{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. -\code{s.setblocking(0)} is equivalent to \code{s.settimeout(0)}; -\code{s.setblocking(1)} is equivalent to \code{s.settimeout(None)}. -\end{methoddesc} - -\begin{methoddesc}[socket]{settimeout}{value} -Set a timeout on blocking socket operations. The \var{value} argument -can be a nonnegative float expressing seconds, or \code{None}. -If a float is -given, subsequent socket operations will raise an \exception{timeout} -exception if the timeout period \var{value} has elapsed before the -operation has completed. Setting a timeout of \code{None} disables -timeouts on socket operations. -\code{s.settimeout(0.0)} is equivalent to \code{s.setblocking(0)}; -\code{s.settimeout(None)} is equivalent to \code{s.setblocking(1)}. -\versionadded{2.3} -\end{methoddesc} - -\begin{methoddesc}[socket]{gettimeout}{} -Return the timeout in floating seconds associated with socket -operations, or \code{None} if no timeout is set. This reflects -the last call to \method{setblocking()} or \method{settimeout()}. -\versionadded{2.3} -\end{methoddesc} - -Some notes on socket blocking and timeouts: A socket object can be in -one of three modes: blocking, non-blocking, or timeout. Sockets are -always created in blocking mode. In blocking mode, operations block -until complete. In non-blocking mode, operations fail (with an error -that is unfortunately system-dependent) if they cannot be completed -immediately. In timeout mode, operations fail if they cannot be -completed within the timeout specified for the socket. The -\method{setblocking()} method is simply a shorthand for certain -\method{settimeout()} calls. - -Timeout mode internally sets the socket in non-blocking mode. The -blocking and timeout modes are shared between file descriptors and -socket objects that refer to the same network endpoint. A consequence -of this is that file objects returned by the \method{makefile()} -method must only be used when the socket is in blocking mode; in -timeout or non-blocking mode file operations that cannot be completed -immediately will fail. - -Note that the \method{connect()} operation is subject to the timeout -setting, and in general it is recommended to call -\method{settimeout()} before calling \method{connect()}. - -\begin{methoddesc}[socket]{setsockopt}{level, optname, value} -Set the value of the given socket option (see the \UNIX{} manual page -\manpage{setsockopt}{2}). The needed symbolic constants are defined in -the \module{socket} module (\constant{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 -\refmodule{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 -\constant{SHUT_RD}, further receives are disallowed. If \var{how} is \constant{SHUT_WR}, -further sends are disallowed. If \var{how} is \constant{SHUT_RDWR}, 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. - - -Socket objects also have these (read-only) attributes that correspond -to the values given to the \class{socket} constructor. - -\begin{memberdesc}[socket]{family} -The socket family. -\versionadded{2.5} -\end{memberdesc} - -\begin{memberdesc}[socket]{type} -The socket type. -\versionadded{2.5} -\end{memberdesc} - -\begin{memberdesc}[socket]{proto} -The socket protocol. -\versionadded{2.5} -\end{memberdesc} - - -\subsection{SSL Objects \label{ssl-objects}} - -SSL objects have the following methods. - -\begin{methoddesc}[SSL]{write}{s} -Writes the string \var{s} to the on the object's SSL connection. -The return value is the number of bytes written. -\end{methoddesc} - -\begin{methoddesc}[SSL]{read}{\optional{n}} -If \var{n} is provided, read \var{n} bytes from the SSL connection, otherwise -read until EOF. The return value is a string of the bytes read. -\end{methoddesc} - -\begin{methoddesc}[SSL]{server}{} -Returns a string describing the server's certificate. -Useful for debugging purposes; do not parse the content of this string -because its format can't be parsed unambiguously. -\end{methoddesc} - -\begin{methoddesc}[SSL]{issuer}{} -Returns a string describing the issuer of the server's certificate. -Useful for debugging purposes; do not parse the content of this string -because its format can't be parsed unambiguously. -\end{methoddesc} - -\subsection{Example \label{socket-example}} - -Here are four 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()}. - -The first two examples support IPv4 only. - -\begin{verbatim} -# Echo server program -import socket - -HOST = '' # Symbolic name meaning the local host -PORT = 50007 # Arbitrary non-privileged port -s = socket.socket(socket.AF_INET, socket.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 -import socket - -HOST = 'daring.cwi.nl' # The remote host -PORT = 50007 # The same port as used by the server -s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) -s.connect((HOST, PORT)) -s.send('Hello, world') -data = s.recv(1024) -s.close() -print 'Received', repr(data) -\end{verbatim} - -The next two examples are identical to the above two, but support both -IPv4 and IPv6. -The server side will listen to the first address family available -(it should listen to both instead). -On most of IPv6-ready systems, IPv6 will take precedence -and the server may not accept IPv4 traffic. -The client side will try to connect to the all addresses returned as a result -of the name resolution, and sends traffic to the first one connected -successfully. - -\begin{verbatim} -# Echo server program -import socket -import sys - -HOST = '' # Symbolic name meaning the local host -PORT = 50007 # Arbitrary non-privileged port -s = None -for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM, 0, socket.AI_PASSIVE): - af, socktype, proto, canonname, sa = res - try: - s = socket.socket(af, socktype, proto) - except socket.error as msg: - s = None - continue - try: - s.bind(sa) - s.listen(1) - except socket.error as msg: - s.close() - s = None - continue - break -if s is None: - print 'could not open socket' - sys.exit(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 -import socket -import sys - -HOST = 'daring.cwi.nl' # The remote host -PORT = 50007 # The same port as used by the server -s = None -for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM): - af, socktype, proto, canonname, sa = res - try: - s = socket.socket(af, socktype, proto) - except socket.error as msg: - s = None - continue - try: - s.connect(sa) - except socket.error as msg: - s.close() - s = None - continue - break -if s is None: - print 'could not open socket' - sys.exit(1) -s.send('Hello, world') -data = s.recv(1024) -s.close() -print 'Received', repr(data) -\end{verbatim} - -This example connects to an SSL server, prints the -server and issuer's distinguished names, sends some bytes, -and reads part of the response: - -\begin{verbatim} -import socket - -s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) -s.connect(('www.verisign.com', 443)) - -ssl_sock = socket.ssl(s) - -print repr(ssl_sock.server()) -print repr(ssl_sock.issuer()) - -# Set a simple HTTP request -- use httplib in actual code. -ssl_sock.write("""GET / HTTP/1.0\r -Host: www.verisign.com\r\n\r\n""") - -# Read a chunk of data. Will not necessarily -# read all the data returned by the server. -data = ssl_sock.read() - -# Note that you need to close the underlying socket, not the SSL object. -del ssl_sock -s.close() -\end{verbatim} - -At this writing, this SSL example prints the following output (line -breaks inserted for readability): - -\begin{verbatim} -'/C=US/ST=California/L=Mountain View/ - O=VeriSign, Inc./OU=Production Services/ - OU=Terms of use at www.verisign.com/rpa (c)00/ - CN=www.verisign.com' -'/O=VeriSign Trust Network/OU=VeriSign, Inc./ - OU=VeriSign International Server CA - Class 3/ - OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign' -\end{verbatim} |