The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/p/python/pyhtmldoc/s/socket

Text File | 1996-11-14 | 7.1 KB | 143 lines

<TITLE>socket -- Python library reference</TITLE>
Prev: <A HREF="../s/signal" TYPE="Prev">signal</A>
Up: <A HREF="../o/optional_operating_system_services" TYPE="Up">Optional Operating System Services</A>
Top: <A HREF="../t/top" TYPE="Top">Top</A>
<H1>7.2. Built-in Module <CODE>socket</CODE></H1>
This module provides access to the BSD <I>socket</I> interface.
It is available on UNIX systems that support this interface.
<P>
For an introduction to socket programming (in C), see the following
papers: <I>An Introductory 4.3BSD Interprocess Communication
Tutorial</I>, by Stuart Sechrest and <I>An Advanced 4.3BSD Interprocess
Communication Tutorial</I>, 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.
<P>
The Python interface is a straightforward transliteration of the
UNIX system call and library interface for sockets to Python's
object-oriented style: the <CODE>socket()</CODE> function returns a
<DFN>socket object</DFN> whose methods implement the various socket system
calls.  Parameter types are somewhat higer-level than in the C
interface: as with <CODE>read()</CODE> and <CODE>write()</CODE> operations on Python
files, buffer allocation on receive operations is automatic, and
buffer length is implicit on send operations.
<P>
Socket addresses are represented as a single string for the
<CODE>AF_UNIX</CODE> address family and as a pair
<CODE>(<VAR>host</VAR>, <VAR>port</VAR>)</CODE> for the <CODE>AF_INET</CODE> address family,
where <VAR>host</VAR> is a string representing
either a hostname in Internet domain notation like
<CODE>'daring.cwi.nl'</CODE> or an IP address like <CODE>'100.50.200.5'</CODE>,
and <VAR>port</VAR> 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.
<P>
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</CODE>.
<P>
Non-blocking mode is supported through the <CODE>setblocking()</CODE>
method.
<P>
The module <CODE>socket</CODE> exports the following constants and functions:
<P>
<DL><DT><B>error</B> -- exception of module socket<DD>
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>, <VAR>string</VAR>)</CODE>
representing an error returned by a system
call, similar to the value accompanying <CODE>posix.error</CODE>.
</DL>
<DL><DT><B>AF_UNIX</B> -- data of module socket<DD>
</DL>
<DL><DT><B>AF_INET</B> -- data of module socket<DD>
These constants represent the address (and protocol) families,
used for the first argument to <CODE>socket()</CODE>.  If the <CODE>AF_UNIX</CODE>
constant is not defined then this protocol is unsupported.
</DL>
<DL><DT><B>SOCK_STREAM</B> -- data of module socket<DD>
</DL>
<DL><DT><B>SOCK_DGRAM</B> -- data of module socket<DD>
</DL>
<DL><DT><B>SOCK_RAW</B> -- data of module socket<DD>
</DL>
<DL><DT><B>SOCK_RDM</B> -- data of module socket<DD>
</DL>
<DL><DT><B>SOCK_SEQPACKET</B> -- data of module socket<DD>
These constants represent the socket types,
used for the second argument to <CODE>socket()</CODE>.
(Only <CODE>SOCK_STREAM</CODE> and
<CODE>SOCK_DGRAM</CODE> appear to be generally useful.)
</DL>
<DL><DT><B>SO_*</B> -- data of module socket<DD>
</DL>
<DL><DT><B>SOMAXCONN</B> -- data of module socket<DD>
</DL>
<DL><DT><B>MSG_*</B> -- data of module socket<DD>
</DL>
<DL><DT><B>SOL_*</B> -- data of module socket<DD>
</DL>
<DL><DT><B>IPPROTO_*</B> -- data of module socket<DD>
</DL>
<DL><DT><B>IPPORT_*</B> -- data of module socket<DD>
</DL>
<DL><DT><B>INADDR_*</B> -- data of module socket<DD>
</DL>
<DL><DT><B>IP_*</B> -- data of module socket<DD>
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 <CODE>setsockopt</CODE> and
<CODE>getsockopt</CODE> 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.
</DL>
<DL><DT><B>gethostbyname</B> (<VAR>hostname</VAR>) -- function of module socket<DD>
Translate a host name to IP address format.  The IP address is
returned as a string, e.g.,  <CODE>'100.50.200.5'</CODE>.  If the host name
is an IP address itself it is returned unchanged.
</DL>
<DL><DT><B>gethostname</B> () -- function of module socket<DD>
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>socket.gethostbyname(socket.gethostname())</CODE>.
</DL>
<DL><DT><B>gethostbyaddr</B> (<VAR>ip_address</VAR>) -- function of module socket<DD>
Return a triple <CODE>(hostname, aliaslist, ipaddrlist)</CODE> where
<CODE>hostname</CODE> is the primary host name responding to the given
<VAR>ip_address</VAR>, <CODE>aliaslist</CODE> is a (possibly empty) list of
alternative host names for the same address, and <CODE>ipaddrlist</CODE> is
a list of IP addresses for the same interface on the same
host (most likely containing only a single address).
</DL>
<DL><DT><B>getservbyname</B> (<VAR>servicename</VAR>, <VAR>protocolname</VAR>) -- function of module socket<DD>
Translate an Internet service name and protocol name to a port number
for that service.  The protocol name should be <CODE>'tcp'</CODE> or
<CODE>'udp'</CODE>.
</DL>
<DL><DT><B>socket</B> (<VAR>family</VAR>, <VAR>type</VAR>[, <VAR>proto</VAR>]) -- function of module socket<DD>
Create a new socket using the given address family, socket type and
protocol number.  The address family should be <CODE>AF_INET</CODE> or
<CODE>AF_UNIX</CODE>.  The socket type should be <CODE>SOCK_STREAM</CODE>,
<CODE>SOCK_DGRAM</CODE> or perhaps one of the other `<SAMP>SOCK_</SAMP>' constants.
The protocol number is usually zero and may be omitted in that case.
</DL>
<DL><DT><B>fromfd</B> (<VAR>fd</VAR>, <VAR>family</VAR>, <VAR>type</VAR>[, <VAR>proto</VAR>]) -- function of module socket<DD>
Build a socket object from an existing file descriptor (an integer as
returned by a file object's <CODE>fileno</CODE> method).  Address family,
socket type and protocol number are as for the <CODE>socket</CODE> 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).
</DL>
<H2>Menu</H2><DL COMPACT>
<DT><A HREF="../s/socket_objects" TYPE=Menu>Socket Objects</A>
<DD><DT><A HREF="../s/socket_example" TYPE=Menu>Socket Example</A>
<DD></DL>