GNU Info
(python2.1-lib.info)socket
Low-level networking interface
==============================
Low-level networking interface.
This module provides access to the BSD _socket_ interface. It is
available on all modern UNIX systems, Windows, MacOS, BeOS, OS/2, and
probably additional platforms.
For an introduction to socket programming (in C), see the following
papers: , by Stuart Sechrest and , by Samuel J. Leffler et al, both in
the (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.
The Python interface is a straightforward transliteration of the UNIX
system call and library interface for sockets to Python's
object-oriented style: the `socket()' function returns a "socket object"
whose methods implement the various socket system calls. Parameter
types are somewhat higher-level than in the C interface: as with
`read()' and `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 `AF_UNIX'
address family and as a pair `(HOST, PORT)' for the `AF_INET' address
family, where HOST is a string representing either a hostname in
Internet domain notation like `'daring.cwi.nl'' or an IP address like
`'100.50.200.5'', and 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 `INADDR_ANY', and the string
`'<broadcast>'' represents `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 `socket.error'.
Non-blocking mode is supported through the `setblocking()' method.
The module `socket' exports the following constants and functions:
`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 `(ERRNO, STRING)' representing an error returned by a
system call, similar to the value accompanying `os.error'. See
the module `errno' , which contains names for the error codes
defined by the underlying operating system.
`AF_UNIX'
`AF_INET'
These constants represent the address (and protocol) families,
used for the first argument to `socket()'. If the `AF_UNIX'
constant is not defined then this protocol is unsupported.
`SOCK_STREAM'
`SOCK_DGRAM'
`SOCK_RAW'
`SOCK_RDM'
`SOCK_SEQPACKET'
These constants represent the socket types, used for the second
argument to `socket()'. (Only `SOCK_STREAM' and `SOCK_DGRAM'
appear to be generally useful.)
`SO_*'
`SOMAXCONN'
`MSG_*'
`SOL_*'
`IPPROTO_*'
`IPPORT_*'
`INADDR_*'
`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
`setsockopt()' and `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.
`getfqdn([name])'
Return a fully qualified domain name for NAME. If NAME is omitted
or empty, it is interpreted as the local host. To find the fully
qualified name, the hostname returned by `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 is returned. _Added in
Python version 2.0_
`gethostbyname(hostname)'
Translate a host name to IP address format. The IP address is
returned as a string, such as `'100.50.200.5''. If the host name
is an IP address itself it is returned unchanged. See
`gethostbyname_ex()' for a more complete interface.
`gethostbyname_ex(hostname)'
Translate a host name to IP address format, extended interface.
Return a triple `(hostname, aliaslist, ipaddrlist)' where
`hostname' is the primary host name responding to the given
IP_ADDRESS, `aliaslist' is a (possibly empty) list of alternative
host names for the same address, and `ipaddrlist' is a list of IP
addresses for the same interface on the same host (often but not
always a single address).
`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 `gethostbyname(gethostname())'.
Note: `gethostname()' doesn't always return the fully qualified
domain name; use `gethostbyaddr(gethostname())' (see below).
`gethostbyaddr(ip_address)'
Return a triple `(HOSTNAME, ALIASLIST, IPADDRLIST)' where HOSTNAME
is the primary host name responding to the given IP_ADDRESS,
ALIASLIST is a (possibly empty) list of alternative host names for
the same address, and 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, use the
function `getfqdn()'.
`getprotobyname(protocolname)'
Translate an Internet protocol name (for example, `'icmp'') to a
constant suitable for passing as the (optional) third argument to
the `socket()' function. This is usually only needed for sockets
opened in "raw" mode (`SOCK_RAW'); for the normal socket modes,
the correct protocol is chosen automatically if the protocol is
omitted or zero.
`getservbyname(servicename, protocolname)'
Translate an Internet service name and protocol name to a port
number for that service. The protocol name should be `'tcp'' or
`'udp''.
`socket(family, type[, proto])'
Create a new socket using the given address family, socket type and
protocol number. The address family should be `AF_INET' or
`AF_UNIX'. The socket type should be `SOCK_STREAM', `SOCK_DGRAM'
or perhaps one of the other `SOCK_' constants. The protocol
number is usually zero and may be omitted in that case.
`fromfd(fd, family, type[, proto])'
Build a socket object from an existing file descriptor (an integer
as returned by a file object's `fileno()' method). Address family,
socket type and protocol number are as for the `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). Availability: UNIX.
`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.
`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.
`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.
`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.
`inet_aton(ip_string)'
Convert an IP 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.
Useful when conversing with a program that uses the standard C
library and needs objects of type `struct in_addr', which is the C
type for the 32-bit packed binary this function returns.
If the IP address string passed to this function is invalid,
`socket.error' will be raised. Note that exactly what is valid
depends on the underlying C implementation of `inet_aton()'.
`inet_ntoa(packed_ip)'
Convert a 32-bit packed IP address (a string four characters in
length) to its standard dotted-quad string representation (for
example, '123.45.67.89').
Useful when conversing with a program that uses the standard C
library and needs objects of type `struct in_addr', which is the C
type for the 32-bit packed binary this function takes as an
argument.
If the string passed to this function is not exactly 4 bytes in
length, `socket.error' will be raised.
`SocketType'
This is a Python type object that represents the socket object
type. It is the same as `type(socket(...))'.
See also:
Note: SocketServer Classes that simplify writing network servers.
automatically generated by info2www version 1.2.2.9