Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
C
cpython
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
Kirill Smelkov
cpython
Commits
d883ca1d
Commit
d883ca1d
authored
Mar 10, 1998
by
Fred Drake
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Logical markup.
parent
816671c6
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
with
172 additions
and
166 deletions
+172
-166
Doc/lib/libsocket.tex
Doc/lib/libsocket.tex
+86
-83
Doc/libsocket.tex
Doc/libsocket.tex
+86
-83
No files found.
Doc/lib/libsocket.tex
View file @
d883ca1d
\section
{
Built-in Module
\sectcode
{
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.
...
...
@@ -16,17 +16,17 @@ 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
\
code
{
socket()
}
function returns a
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
\
code
{
read()
}
and
\code
{
write()
}
operations on Pyth
on
files, buffer allocation on receive operations is automatic, and
buffer length is implicit on send operations.
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
\co
de
{
AF
_
UNIX
}
address family and as a pair
\code
{
(
\var
{
host
}
,
\var
{
port
}
)
}
for the
\co
de
{
AF
_
INET
}
address family,
where
\var
{
host
}
is a string representing
\co
nstant
{
AF
_
UNIX
}
address family and as a pair
\code
{
(
\var
{
host
}
,
\var
{
port
}
)
}
for the
\co
nstant
{
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
...
...
@@ -35,8 +35,8 @@ 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
\co
de
{
INADDR
_
ANY
}
, and the string
\code
{
"<broadcast>"
}
represents
\co
de
{
INADDR
_
BROADCAST
}
.
address: the empty string represents
\co
nstant
{
INADDR
_
ANY
}
, and the string
\code
{
"<broadcast>"
}
represents
\co
nstant
{
INADDR
_
BROADCAST
}
.
All errors raise exceptions. The normal exceptions for invalid
argument types and out-of-memory conditions can be raised; errors
...
...
@@ -45,9 +45,9 @@ related to socket or address semantics raise the error \code{socket.error}.
Non-blocking mode is supported through the
\code
{
setblocking()
}
method.
The module
\code
{
socket
}
exports the following constants and functions:
The module
\module
{
socket
}
exports the following constants and functions:
\setindexsubitem
{
(in module socket)
}
\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
...
...
@@ -61,8 +61,9 @@ names for the error codes defined by the underlying operating system.
\begin{datadesc}
{
AF
_
UNIX
}
\dataline
{
AF
_
INET
}
These constants represent the address (and protocol) families,
used for the first argument to
\code
{
socket()
}
. If the
\code
{
AF
_
UNIX
}
constant is not defined then this protocol is unsupported.
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
}
...
...
@@ -71,9 +72,9 @@ constant is not defined then this protocol is unsupported.
\dataline
{
SOCK
_
RDM
}
\dataline
{
SOCK
_
SEQPACKET
}
These constants represent the socket types,
used for the second argument to
\
code
{
socket()
}
.
(Only
\co
de
{
SOCK
_
STREAM
}
and
\co
de
{
SOCK
_
DGRAM
}
appear to be generally useful.)
used for the second argument to
\
function
{
socket()
}
.
(Only
\co
nstant
{
SOCK
_
STREAM
}
and
\co
nstant
{
SOCK
_
DGRAM
}
appear to be generally useful.)
\end{datadesc}
\begin{datadesc}
{
SO
_
*
}
...
...
@@ -86,8 +87,8 @@ used for the second argument to \code{socket()}.
\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
\
code
{
setsockopt
}
and
\
code
{
getsockopt
}
methods of socket objects. In most cases, only
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}
...
...
@@ -101,20 +102,19 @@ is an IP address itself it is returned unchanged.
\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
{
socket.gethostbyname(socket.gethostname())
}
.
Note:
\code
{
gethostname()
}
doesn't always return the fully qualified
domain name; use
\code
{
socket.gethostbyaddr(socket.gethostname())
}
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
{
(
hostname, aliaslist, ipaddrlist)
}
where
\
code
{
hostname
}
is the primary host name responding to the given
\var
{
ip
_
address
}
,
\code
{
aliaslist
}
is a (possibly empty) list of
alternative host names for the same address, and
\code
{
ipaddrlist
}
is
a
list of IP addresses for the same interface on the sam
e
host (most likely containing only a single 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,
a
nd
\var
{
ipaddrlist
}
is a list of IP addresses for the same interfac
e
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}
...
...
@@ -122,29 +122,29 @@ items of \var{aliaslist} for an entry containing at least one period.
\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
\
code
{
socket()
}
function. This is usually only needed for sockets
opened in ``raw'' mode (
\co
de
{
SOCK
_
RAW
}
); for the normal socket modes,
the correct protocol is chosen automatically if the protocol is
\
function
{
socket()
}
function. This is usually only needed for sockets
opened in ``raw'' mode (
\co
nstant
{
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
}
\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
}}
\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
\co
de
{
AF
_
INET
}
or
\co
de
{
AF
_
UNIX
}
. The socket type should be
\code
{
SOCK
_
STREAM
}
,
\co
de
{
SOCK
_
DGRAM
}
or perhaps one of the other
\samp
{
SOCK
_}
constants.
protocol number. The address family should be
\co
nstant
{
AF
_
INET
}
or
\co
nstant
{
AF
_
UNIX
}
. The socket type should be
\constant
{
SOCK
_
STREAM
}
,
\co
nstant
{
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
}}
\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
\
code
{
fileno
}
method). Address family,
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
...
...
@@ -180,15 +180,14 @@ no-op; otherwise, it performs a 2-byte swap operation.
\begin{datadesc}
{
SocketType
}
This is a Python type object that represents the socket object type.
It is the same as
\code
{
type(socket
.socket
(...))
}
.
It is the same as
\code
{
type(socket(...))
}
.
\end{datadesc}
\subsection
{
Socket Objects
}
\noindent
Socket objects have the following methods. Except for
\
code
{
makefile()
}
these correspond to
\UNIX
{}
system calls applicable to
sockets.
\
method
{
makefile()
}
these correspond to
\UNIX
{}
system calls
applicable to
sockets.
\setindexsubitem
{
(socket method)
}
\begin{funcdesc}
{
accept
}{}
...
...
@@ -213,19 +212,20 @@ Sockets are automatically closed when they are garbage-collected.
\begin{funcdesc}
{
connect
}{
address
}
Connect to a remote socket at
\var
{
address
}
.
(The format of
\var
{
address
}
depends on the address family --- see above.)
(The format of
\var
{
address
}
depends on the address family --- see
above.)
\end{funcdesc}
\begin{funcdesc}
{
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
\c
ode
{
errno
}
operation succeeded, otherwise the value of the
\c
data
{
errno
}
variable. This is useful e.g. for asynchronous connects.
\end{funcdesc}
\begin{funcdesc}
{
fileno
}{}
Return the socket's file descriptor (a small integer). This is useful
with
\
code
{
select
}
.
with
\
function
{
select.select()
}
.
\end{funcdesc}
\begin{funcdesc}
{
getpeername
}{}
...
...
@@ -242,16 +242,16 @@ number of an IP socket, for instance.
see above.)
\end{funcdesc}
\begin{funcdesc}
{
getsockopt
}{
level
\,
optname
\optional
{
\
,
buflen
}}
\begin{funcdesc}
{
getsockopt
}{
level
, optname
\optional
{
, buflen
}}
Return the value of the given socket option (see the
\UNIX
{}
man page
\
emph
{
getsockopt
}
(2)). The needed symbolic constants (
\code
{
SO
_
*
}
etc.)
are defined in this module. If
\var
{
buflen
}
\
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
\
cod
e
{
struct
}
for a way to decode C structures encoded as strings).
\
modul
e
{
struct
}
for a way to decode C structures encoded as strings).
\end{funcdesc}
\begin{funcdesc}
{
listen
}{
backlog
}
...
...
@@ -262,42 +262,42 @@ least 1; the maximum value is system-dependent (usually 5).
\begin{funcdesc}
{
makefile
}{
\optional
{
mode
\optional
{
\,
bufsize
}}}
Return a
\dfn
{
file object
}
associated with the socket. (File objects
were described earlier
under Built-in Types.) The file object
references a
\code
{
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
a
re interpreted the same way as by the built-in
\code
{
open()
}
function.
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
}
a
nd
\var
{
bufsize
}
arguments are interpreted the same way as by the
built-in
\function
{
open()
}
function.
\end{funcdesc}
\begin{funcdesc}
{
recv
}{
bufsize
\optional
{
\
,
flags
}}
\begin{funcdesc}
{
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
for the meaning of the optional argument
\var
{
flags
}
; it defaults to
zero.
\manpage
{
recv
}{
2
}
for the meaning of the optional argument
\var
{
flags
}
; it defaults to
zero.
\end{funcdesc}
\begin{funcdesc}
{
recvfrom
}{
bufsize
\optional
{
\
,
flags
}}
\begin{funcdesc}
{
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
\
code
{
recv()
}
above.
same meaning as for
\
method
{
recv()
}
above.
(The format of
\var
{
address
}
depends on the address family --- see above.)
\end{funcdesc}
\begin{funcdesc}
{
send
}{
string
\optional
{
\
,
flags
}}
\begin{funcdesc}
{
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
\
code
{
recv()
}
above. Return
the number of bytes sent.
\
method
{
recv()
}
above. Returns
the number of bytes sent.
\end{funcdesc}
\begin{funcdesc}
{
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
\
code
{
address
}
. The optional
\var
{
flags
}
argument has the same
meaning as for
\
code
{
recv()
}
above. Return the number of bytes sent.
\
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{funcdesc}
...
...
@@ -305,30 +305,32 @@ meaning as for \code{recv()} above. Return the number of bytes sent.
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
\
code
{
recv
}
call doesn't find any data, or if a
\code
{
send
}
call can't
immediately dispose of the data, a
\
code
{
socket.
error
}
exception is
\
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{funcdesc}
\begin{funcdesc}
{
setsockopt
}{
level
\,
optname
\,
value
}
Set the value of the given socket option (see the
\UNIX
{}
man page
\
emph
{
setsockopt
}
(2)
). The needed symbolic constants are defined in
the
\
cod
e
{
socket
}
module (
\code
{
SO
_
*
}
etc.). The value can be an
\
manpage
{
setsockopt
}{
2
}
). The needed symbolic constants are defined in
the
\
modul
e
{
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
\code
{
struct
}
for a way to encode C structures as strings).
\module
{
struct
}
\refbimodindex
{
struct
}
for a way to encode C structures
as strings).
\end{funcdesc}
\begin{funcdesc}
{
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.
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{funcdesc}
Note that there are no methods
\code
{
read()
}
or
\code
{
write()
}
; use
\code
{
recv()
}
and
\code
{
send()
}
without
\var
{
flags
}
argument instead.
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
}
...
...
@@ -336,12 +338,13 @@ Note that there are no methods \code{read()} or \code{write()}; use
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
\code
{
socket
}
,
\code
{
bind
}
,
\code
{
listen
}
,
\code
{
accept
}
(possibly repeating the
\code
{
accept
}
to service more than one client),
while a client only needs the sequence
\code
{
socket
}
,
\code
{
connect
}
.
Also note that the server does not
\code
{
send
}
/
\code
{
receive
}
on 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
\
code
{
accept
}
.
\
method
{
accept()
}
.
\begin{verbatim}
# Echo server program
...
...
@@ -359,7 +362,7 @@ while 1:
conn.send(data)
conn.close()
\end{verbatim}
%
\begin{verbatim}
# Echo client program
from socket import *
...
...
@@ -372,7 +375,7 @@ data = s.recv(1024)
s.close()
print 'Received', `data`
\end{verbatim}
%
\begin{seealso}
\seemodule
{
SocketServer
}{
classes that simplify writing network servers
}
\end{seealso}
Doc/libsocket.tex
View file @
d883ca1d
\section
{
Built-in Module
\sectcode
{
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.
...
...
@@ -16,17 +16,17 @@ 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
\
code
{
socket()
}
function returns a
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
\
code
{
read()
}
and
\code
{
write()
}
operations on Pyth
on
files, buffer allocation on receive operations is automatic, and
buffer length is implicit on send operations.
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
\co
de
{
AF
_
UNIX
}
address family and as a pair
\code
{
(
\var
{
host
}
,
\var
{
port
}
)
}
for the
\co
de
{
AF
_
INET
}
address family,
where
\var
{
host
}
is a string representing
\co
nstant
{
AF
_
UNIX
}
address family and as a pair
\code
{
(
\var
{
host
}
,
\var
{
port
}
)
}
for the
\co
nstant
{
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
...
...
@@ -35,8 +35,8 @@ 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
\co
de
{
INADDR
_
ANY
}
, and the string
\code
{
"<broadcast>"
}
represents
\co
de
{
INADDR
_
BROADCAST
}
.
address: the empty string represents
\co
nstant
{
INADDR
_
ANY
}
, and the string
\code
{
"<broadcast>"
}
represents
\co
nstant
{
INADDR
_
BROADCAST
}
.
All errors raise exceptions. The normal exceptions for invalid
argument types and out-of-memory conditions can be raised; errors
...
...
@@ -45,9 +45,9 @@ related to socket or address semantics raise the error \code{socket.error}.
Non-blocking mode is supported through the
\code
{
setblocking()
}
method.
The module
\code
{
socket
}
exports the following constants and functions:
The module
\module
{
socket
}
exports the following constants and functions:
\setindexsubitem
{
(in module socket)
}
\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
...
...
@@ -61,8 +61,9 @@ names for the error codes defined by the underlying operating system.
\begin{datadesc}
{
AF
_
UNIX
}
\dataline
{
AF
_
INET
}
These constants represent the address (and protocol) families,
used for the first argument to
\code
{
socket()
}
. If the
\code
{
AF
_
UNIX
}
constant is not defined then this protocol is unsupported.
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
}
...
...
@@ -71,9 +72,9 @@ constant is not defined then this protocol is unsupported.
\dataline
{
SOCK
_
RDM
}
\dataline
{
SOCK
_
SEQPACKET
}
These constants represent the socket types,
used for the second argument to
\
code
{
socket()
}
.
(Only
\co
de
{
SOCK
_
STREAM
}
and
\co
de
{
SOCK
_
DGRAM
}
appear to be generally useful.)
used for the second argument to
\
function
{
socket()
}
.
(Only
\co
nstant
{
SOCK
_
STREAM
}
and
\co
nstant
{
SOCK
_
DGRAM
}
appear to be generally useful.)
\end{datadesc}
\begin{datadesc}
{
SO
_
*
}
...
...
@@ -86,8 +87,8 @@ used for the second argument to \code{socket()}.
\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
\
code
{
setsockopt
}
and
\
code
{
getsockopt
}
methods of socket objects. In most cases, only
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}
...
...
@@ -101,20 +102,19 @@ is an IP address itself it is returned unchanged.
\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
{
socket.gethostbyname(socket.gethostname())
}
.
Note:
\code
{
gethostname()
}
doesn't always return the fully qualified
domain name; use
\code
{
socket.gethostbyaddr(socket.gethostname())
}
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
{
(
hostname, aliaslist, ipaddrlist)
}
where
\
code
{
hostname
}
is the primary host name responding to the given
\var
{
ip
_
address
}
,
\code
{
aliaslist
}
is a (possibly empty) list of
alternative host names for the same address, and
\code
{
ipaddrlist
}
is
a
list of IP addresses for the same interface on the sam
e
host (most likely containing only a single 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,
a
nd
\var
{
ipaddrlist
}
is a list of IP addresses for the same interfac
e
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}
...
...
@@ -122,29 +122,29 @@ items of \var{aliaslist} for an entry containing at least one period.
\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
\
code
{
socket()
}
function. This is usually only needed for sockets
opened in ``raw'' mode (
\co
de
{
SOCK
_
RAW
}
); for the normal socket modes,
the correct protocol is chosen automatically if the protocol is
\
function
{
socket()
}
function. This is usually only needed for sockets
opened in ``raw'' mode (
\co
nstant
{
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
}
\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
}}
\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
\co
de
{
AF
_
INET
}
or
\co
de
{
AF
_
UNIX
}
. The socket type should be
\code
{
SOCK
_
STREAM
}
,
\co
de
{
SOCK
_
DGRAM
}
or perhaps one of the other
\samp
{
SOCK
_}
constants.
protocol number. The address family should be
\co
nstant
{
AF
_
INET
}
or
\co
nstant
{
AF
_
UNIX
}
. The socket type should be
\constant
{
SOCK
_
STREAM
}
,
\co
nstant
{
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
}}
\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
\
code
{
fileno
}
method). Address family,
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
...
...
@@ -180,15 +180,14 @@ no-op; otherwise, it performs a 2-byte swap operation.
\begin{datadesc}
{
SocketType
}
This is a Python type object that represents the socket object type.
It is the same as
\code
{
type(socket
.socket
(...))
}
.
It is the same as
\code
{
type(socket(...))
}
.
\end{datadesc}
\subsection
{
Socket Objects
}
\noindent
Socket objects have the following methods. Except for
\
code
{
makefile()
}
these correspond to
\UNIX
{}
system calls applicable to
sockets.
\
method
{
makefile()
}
these correspond to
\UNIX
{}
system calls
applicable to
sockets.
\setindexsubitem
{
(socket method)
}
\begin{funcdesc}
{
accept
}{}
...
...
@@ -213,19 +212,20 @@ Sockets are automatically closed when they are garbage-collected.
\begin{funcdesc}
{
connect
}{
address
}
Connect to a remote socket at
\var
{
address
}
.
(The format of
\var
{
address
}
depends on the address family --- see above.)
(The format of
\var
{
address
}
depends on the address family --- see
above.)
\end{funcdesc}
\begin{funcdesc}
{
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
\c
ode
{
errno
}
operation succeeded, otherwise the value of the
\c
data
{
errno
}
variable. This is useful e.g. for asynchronous connects.
\end{funcdesc}
\begin{funcdesc}
{
fileno
}{}
Return the socket's file descriptor (a small integer). This is useful
with
\
code
{
select
}
.
with
\
function
{
select.select()
}
.
\end{funcdesc}
\begin{funcdesc}
{
getpeername
}{}
...
...
@@ -242,16 +242,16 @@ number of an IP socket, for instance.
see above.)
\end{funcdesc}
\begin{funcdesc}
{
getsockopt
}{
level
\,
optname
\optional
{
\
,
buflen
}}
\begin{funcdesc}
{
getsockopt
}{
level
, optname
\optional
{
, buflen
}}
Return the value of the given socket option (see the
\UNIX
{}
man page
\
emph
{
getsockopt
}
(2)). The needed symbolic constants (
\code
{
SO
_
*
}
etc.)
are defined in this module. If
\var
{
buflen
}
\
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
\
cod
e
{
struct
}
for a way to decode C structures encoded as strings).
\
modul
e
{
struct
}
for a way to decode C structures encoded as strings).
\end{funcdesc}
\begin{funcdesc}
{
listen
}{
backlog
}
...
...
@@ -262,42 +262,42 @@ least 1; the maximum value is system-dependent (usually 5).
\begin{funcdesc}
{
makefile
}{
\optional
{
mode
\optional
{
\,
bufsize
}}}
Return a
\dfn
{
file object
}
associated with the socket. (File objects
were described earlier
under Built-in Types.) The file object
references a
\code
{
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
a
re interpreted the same way as by the built-in
\code
{
open()
}
function.
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
}
a
nd
\var
{
bufsize
}
arguments are interpreted the same way as by the
built-in
\function
{
open()
}
function.
\end{funcdesc}
\begin{funcdesc}
{
recv
}{
bufsize
\optional
{
\
,
flags
}}
\begin{funcdesc}
{
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
for the meaning of the optional argument
\var
{
flags
}
; it defaults to
zero.
\manpage
{
recv
}{
2
}
for the meaning of the optional argument
\var
{
flags
}
; it defaults to
zero.
\end{funcdesc}
\begin{funcdesc}
{
recvfrom
}{
bufsize
\optional
{
\
,
flags
}}
\begin{funcdesc}
{
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
\
code
{
recv()
}
above.
same meaning as for
\
method
{
recv()
}
above.
(The format of
\var
{
address
}
depends on the address family --- see above.)
\end{funcdesc}
\begin{funcdesc}
{
send
}{
string
\optional
{
\
,
flags
}}
\begin{funcdesc}
{
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
\
code
{
recv()
}
above. Return
the number of bytes sent.
\
method
{
recv()
}
above. Returns
the number of bytes sent.
\end{funcdesc}
\begin{funcdesc}
{
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
\
code
{
address
}
. The optional
\var
{
flags
}
argument has the same
meaning as for
\
code
{
recv()
}
above. Return the number of bytes sent.
\
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{funcdesc}
...
...
@@ -305,30 +305,32 @@ meaning as for \code{recv()} above. Return the number of bytes sent.
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
\
code
{
recv
}
call doesn't find any data, or if a
\code
{
send
}
call can't
immediately dispose of the data, a
\
code
{
socket.
error
}
exception is
\
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{funcdesc}
\begin{funcdesc}
{
setsockopt
}{
level
\,
optname
\,
value
}
Set the value of the given socket option (see the
\UNIX
{}
man page
\
emph
{
setsockopt
}
(2)
). The needed symbolic constants are defined in
the
\
cod
e
{
socket
}
module (
\code
{
SO
_
*
}
etc.). The value can be an
\
manpage
{
setsockopt
}{
2
}
). The needed symbolic constants are defined in
the
\
modul
e
{
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
\code
{
struct
}
for a way to encode C structures as strings).
\module
{
struct
}
\refbimodindex
{
struct
}
for a way to encode C structures
as strings).
\end{funcdesc}
\begin{funcdesc}
{
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.
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{funcdesc}
Note that there are no methods
\code
{
read()
}
or
\code
{
write()
}
; use
\code
{
recv()
}
and
\code
{
send()
}
without
\var
{
flags
}
argument instead.
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
}
...
...
@@ -336,12 +338,13 @@ Note that there are no methods \code{read()} or \code{write()}; use
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
\code
{
socket
}
,
\code
{
bind
}
,
\code
{
listen
}
,
\code
{
accept
}
(possibly repeating the
\code
{
accept
}
to service more than one client),
while a client only needs the sequence
\code
{
socket
}
,
\code
{
connect
}
.
Also note that the server does not
\code
{
send
}
/
\code
{
receive
}
on 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
\
code
{
accept
}
.
\
method
{
accept()
}
.
\begin{verbatim}
# Echo server program
...
...
@@ -359,7 +362,7 @@ while 1:
conn.send(data)
conn.close()
\end{verbatim}
%
\begin{verbatim}
# Echo client program
from socket import *
...
...
@@ -372,7 +375,7 @@ data = s.recv(1024)
s.close()
print 'Received', `data`
\end{verbatim}
%
\begin{seealso}
\seemodule
{
SocketServer
}{
classes that simplify writing network servers
}
\end{seealso}
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment
