Socket Objects
--------------
Socket objects have the following methods. Except for `makefile()'
these correspond to UNIX system calls applicable to sockets.
`accept()'
Accept a connection. The socket must be bound to an address and
listening for connections. The return value is a pair `(CONN,
ADDRESS)' where CONN is a _new_ socket object usable to send and
receive data on the connection, and ADDRESS is the address bound
to the socket on the other end of the connection.
`bind(address)'
Bind the socket to ADDRESS. The socket must not already be bound.
(The format of ADDRESS depends on the address family -- see
above.) *Note:* This method has historically accepted a pair of
parameters for `AF_INET' addresses instead of only a tuple. This
was never intentional and is no longer be available in Python 2.0.
`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.
`connect(address)'
Connect to a remote socket at ADDRESS. (The format of ADDRESS
depends on the address family -- see above.) *Note:* This method
has historically accepted a pair of parameters for `AF_INET'
addresses instead of only a tuple. This was never intentional and
is no longer available in Python 2.0 and later.
`connect_ex(address)'
Like `connect(ADDRESS)', but return an error indicator instead of
raising an exception for errors returned by the C-level
`connect()' call (other problems, such as "host not found," can
still raise exceptions). The error indicator is `0' if the
operation succeeded, otherwise the value of the `errno' variable.
This is useful to support, for example, asynchronous connects.
*Note:* This method has historically accepted a pair of
parameters for `AF_INET' addresses instead of only a tuple. This
was never intentional and is no longer be available in Python 2.0
and later.
`fileno()'
Return the socket's file descriptor (a small integer). This is
useful with `select.select()'.
`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.
`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.)
`getsockopt(level, optname[, buflen])'
Return the value of the given socket option (see the UNIX man page
`getsockopt(2)'). The needed symbolic constants (`SO_*' etc.) are
defined in this module. If BUFLEN is absent, an integer option is
assumed and its integer value is returned by the function. If
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 `struct' for a way to
decode C structures encoded as strings).
`listen(backlog)'
Listen for connections made to the socket. The BACKLOG argument
specifies the maximum number of queued connections and should be at
least 1; the maximum value is system-dependent (usually 5).
`makefile([mode[, bufsize]])'
Return a "file object" associated with the socket. (File objects
are described in Note:File Objectsfile, "File Objects.") The
file object references a `dup()'ped version of the socket file
descriptor, so the file object and socket object may be closed or
garbage-collected independently. The optional MODE and BUFSIZE
arguments are interpreted the same way as by the built-in `open()'
function; see "Built-in Functions" (section Note:Built-in
Functions) for more information.
`recv(bufsize[, 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 BUFSIZE. See the UNIX manual page
`recv(2)' for the meaning of the optional argument FLAGS; it
defaults to zero.
`recvfrom(bufsize[, flags])'
Receive data from the socket. The return value is a pair
`(STRING, ADDRESS)' where STRING is a string representing the data
received and ADDRESS is the address of the socket sending the
data. The optional FLAGS argument has the same meaning as for
`recv()' above. (The format of ADDRESS depends on the address
family -- see above.)
`send(string[, flags])'
Send data to the socket. The socket must be connected to a remote
socket. The optional FLAGS argument has the same meaning as for
`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.
`sendall(string[, flags])'
Send data to the socket. The socket must be connected to a remote
socket. The optional FLAGS argument has the same meaning as for
`recv()' above. Unlike `send()', this method continues to send
data from STRING until either all data has been sent or an error
occurs. `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.
`sendto(string[, flags], address)'
Send data to the socket. The socket should not be connected to a
remote socket, since the destination socket is specified by
ADDRESS. The optional FLAGS argument has the same meaning as for
`recv()' above. Return the number of bytes sent. (The format of
ADDRESS depends on the address family -- see above.)
`setblocking(flag)'
Set blocking or non-blocking mode of the socket: if 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
`recv()' call doesn't find any data, or if a `send()' call can't
immediately dispose of the data, a `error' exception is raised; in
blocking mode, the calls block until they can proceed.
`setsockopt(level, optname, value)'
Set the value of the given socket option (see the UNIX manual page
`setsockopt(2)'). The needed symbolic constants are defined in
the `socket' module (`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 `struct' for a way to encode C
structures as strings).
`shutdown(how)'
Shut down one or both halves of the connection. If HOW is `0',
further receives are disallowed. If HOW is `1', further sends are
disallowed. If HOW is `2', further sends and receives are
disallowed.
Note that there are no methods `read()' or `write()'; use `recv()' and
`send()' without FLAGS argument instead.