/
usr
/
share
/
doc
/
python2-docs
/
html
/
library
/
/usr/share/doc/python2-docs/html/library
mkdir
upload
Name
Size
Mode
Actions
2to3.html
59507
0644
edit
dl
rm
abc.html
25826
0644
edit
dl
rm
aepack.html
14164
0644
edit
dl
rm
aetools.html
16389
0644
edit
dl
rm
aetypes.html
21021
0644
edit
dl
rm
aifc.html
25064
0644
edit
dl
rm
al.html
18672
0644
edit
dl
rm
allos.html
35297
0644
edit
dl
rm
anydbm.html
18124
0644
edit
dl
rm
archiving.html
10078
0644
edit
dl
rm
argparse.html
263616
0644
edit
dl
rm
array.html
31855
0644
edit
dl
rm
ast.html
38167
0644
edit
dl
rm
asynchat.html
33930
0644
edit
dl
rm
asyncore.html
40631
0644
edit
dl
rm
atexit.html
18455
0644
edit
dl
rm
audioop.html
34252
0644
edit
dl
rm
autogil.html
8733
0644
edit
dl
rm
base64.html
21862
0644
edit
dl
rm
basehttpserver.html
37441
0644
edit
dl
rm
bastion.html
11798
0644
edit
dl
rm
bdb.html
41395
0644
edit
dl
rm
binascii.html
22997
0644
edit
dl
rm
binhex.html
11309
0644
edit
dl
rm
bisect.html
24666
0644
edit
dl
rm
bsddb.html
28589
0644
edit
dl
rm
bz2.html
29048
0644
edit
dl
rm
calendar.html
41762
0644
edit
dl
rm
carbon.html
51998
0644
edit
dl
rm
cd.html
30033
0644
edit
dl
rm
cgi.html
55922
0644
edit
dl
rm
cgihttpserver.html
14026
0644
edit
dl
rm
cgitb.html
12263
0644
edit
dl
rm
chunk.html
15899
0644
edit
dl
rm
cmath.html
28365
0644
edit
dl
rm
cmd.html
29042
0644
edit
dl
rm
code.html
26959
0644
edit
dl
rm
codecs.html
118258
0644
edit
dl
rm
codeop.html
15898
0644
edit
dl
rm
collections.html
147647
0644
edit
dl
rm
colorpicker.html
8035
0644
edit
dl
rm
colorsys.html
11919
0644
edit
dl
rm
commands.html
15516
0644
edit
dl
rm
compileall.html
18621
0644
edit
dl
rm
compiler.html
75897
0644
edit
dl
rm
configparser.html
67751
0644
edit
dl
rm
constants.html
13979
0644
edit
dl
rm
contextlib.html
22777
0644
edit
dl
rm
cookie.html
41854
0644
edit
dl
rm
cookielib.html
91032
0644
edit
dl
rm
copy.html
13004
0644
edit
dl
rm
copy_reg.html
14691
0644
edit
dl
rm
crypt.html
10647
0644
edit
dl
rm
crypto.html
7761
0644
edit
dl
rm
csv.html
76456
0644
edit
dl
rm
ctypes.html
264575
0644
edit
dl
rm
curses.ascii.html
24873
0644
edit
dl
rm
curses.html
167501
0644
edit
dl
rm
curses.panel.html
15824
0644
edit
dl
rm
custominterp.html
8026
0644
edit
dl
rm
datatypes.html
18015
0644
edit
dl
rm
datetime.html
253438
0644
edit
dl
rm
dbhash.html
16825
0644
edit
dl
rm
dbm.html
13507
0644
edit
dl
rm
debug.html
10703
0644
edit
dl
rm
decimal.html
222315
0644
edit
dl
rm
development.html
14828
0644
edit
dl
rm
difflib.html
91975
0644
edit
dl
rm
dircache.html
12299
0644
edit
dl
rm
dis.html
84156
0644
edit
dl
rm
distribution.html
7679
0644
edit
dl
rm
distutils.html
10152
0644
edit
dl
rm
dl.html
17668
0644
edit
dl
rm
doctest.html
185883
0644
edit
dl
rm
docxmlrpcserver.html
17573
0644
edit
dl
rm
dumbdbm.html
15549
0644
edit
dl
rm
dummy_thread.html
10065
0644
edit
dl
rm
dummy_threading.html
8934
0644
edit
dl
rm
easydialogs.html
33124
0644
edit
dl
rm
email-examples.html
47424
0644
edit
dl
rm
email.charset.html
29424
0644
edit
dl
rm
email.encoders.html
12847
0644
edit
dl
rm
email.errors.html
17952
0644
edit
dl
rm
email.generator.html
23141
0644
edit
dl
rm
email.header.html
29108
0644
edit
dl
rm
email.html
55722
0644
edit
dl
rm
email.iterators.html
12623
0644
edit
dl
rm
email.message.html
70189
0644
edit
dl
rm
email.mime.html
31655
0644
edit
dl
rm
email.parser.html
35142
0644
edit
dl
rm
email.utils.html
27076
0644
edit
dl
rm
ensurepip.html
18327
0644
edit
dl
rm
errno.html
40246
0644
edit
dl
rm
exceptions.html
63693
0644
edit
dl
rm
fcntl.html
26245
0644
edit
dl
rm
filecmp.html
23997
0644
edit
dl
rm
fileformats.html
9653
0644
edit
dl
rm
fileinput.html
27071
0644
edit
dl
rm
filesys.html
10866
0644
edit
dl
rm
fl.html
56525
0644
edit
dl
rm
fm.html
13009
0644
edit
dl
rm
fnmatch.html
16258
0644
edit
dl
rm
formatter.html
37371
0644
edit
dl
rm
fpectl.html
16879
0644
edit
dl
rm
fpformat.html
11455
0644
edit
dl
rm
fractions.html
24888
0644
edit
dl
rm
framework.html
36934
0644
edit
dl
rm
frameworks.html
7551
0644
edit
dl
rm
ftplib.html
49577
0644
edit
dl
rm
functions.html
205640
0644
edit
dl
rm
functools.html
29645
0644
edit
dl
rm
future_builtins.html
14477
0644
edit
dl
rm
gc.html
28423
0644
edit
dl
rm
gdbm.html
17805
0644
edit
dl
rm
gensuitemodule.html
12574
0644
edit
dl
rm
getopt.html
25280
0644
edit
dl
rm
getpass.html
11426
0644
edit
dl
rm
gettext.html
84971
0644
edit
dl
rm
gl.html
24342
0644
edit
dl
rm
glob.html
14430
0644
edit
dl
rm
grp.html
11316
0644
edit
dl
rm
gzip.html
20576
0644
edit
dl
rm
hashlib.html
25467
0644
edit
dl
rm
heapq.html
34890
0644
edit
dl
rm
hmac.html
14374
0644
edit
dl
rm
hotshot.html
20147
0644
edit
dl
rm
htmllib.html
27682
0644
edit
dl
rm
htmlparser.html
42433
0644
edit
dl
rm
httplib.html
70932
0644
edit
dl
rm
i18n.html
10047
0644
edit
dl
rm
ic.html
18654
0644
edit
dl
rm
idle.html
42148
0644
edit
dl
rm
imageop.html
16099
0644
edit
dl
rm
imaplib.html
58515
0644
edit
dl
rm
imgfile.html
12732
0644
edit
dl
rm
imghdr.html
12238
0644
edit
dl
rm
imp.html
37603
0644
edit
dl
rm
importlib.html
8926
0644
edit
dl
rm
imputil.html
33563
0644
edit
dl
rm
index.html
79088
0644
edit
dl
rm
inspect.html
56823
0644
edit
dl
rm
internet.html
26138
0644
edit
dl
rm
intro.html
9353
0644
edit
dl
rm
io.html
113701
0644
edit
dl
rm
ipc.html
16598
0644
edit
dl
rm
itertools.html
125397
0644
edit
dl
rm
jpeg.html
13757
0644
edit
dl
rm
json.html
73678
0644
edit
dl
rm
keyword.html
8210
0644
edit
dl
rm
language.html
11687
0644
edit
dl
rm
linecache.html
11416
0644
edit
dl
rm
locale.html
61576
0644
edit
dl
rm
logging.config.html
80045
0644
edit
dl
rm
logging.handlers.html
80194
0644
edit
dl
rm
logging.html
110254
0644
edit
dl
rm
mac.html
23376
0644
edit
dl
rm
macos.html
16129
0644
edit
dl
rm
macosa.html
14080
0644
edit
dl
rm
macostools.html
16898
0644
edit
dl
rm
macpath.html
8386
0644
edit
dl
rm
mailbox.html
171121
0644
edit
dl
rm
mailcap.html
14132
0644
edit
dl
rm
markup.html
19862
0644
edit
dl
rm
marshal.html
19456
0644
edit
dl
rm
math.html
44015
0644
edit
dl
rm
md5.html
15123
0644
edit
dl
rm
mhlib.html
24123
0644
edit
dl
rm
mimetools.html
21206
0644
edit
dl
rm
mimetypes.html
30634
0644
edit
dl
rm
mimewriter.html
16078
0644
edit
dl
rm
mimify.html
15279
0644
edit
dl
rm
miniaeframe.html
13109
0644
edit
dl
rm
misc.html
7236
0644
edit
dl
rm
mm.html
9570
0644
edit
dl
rm
mmap.html
30832
0644
edit
dl
rm
modulefinder.html
18096
0644
edit
dl
rm
modules.html
9017
0644
edit
dl
rm
msilib.html
57853
0644
edit
dl
rm
msvcrt.html
21232
0644
edit
dl
rm
multifile.html
26256
0644
edit
dl
rm
multiprocessing.html
414535
0644
edit
dl
rm
mutex.html
12147
0644
edit
dl
rm
netdata.html
18379
0644
edit
dl
rm
netrc.html
14021
0644
edit
dl
rm
new.html
13177
0644
edit
dl
rm
nis.html
11502
0644
edit
dl
rm
nntplib.html
45689
0644
edit
dl
rm
numbers.html
40636
0644
edit
dl
rm
numeric.html
14292
0644
edit
dl
rm
operator.html
93622
0644
edit
dl
rm
optparse.html
250109
0644
edit
dl
rm
os.html
240195
0644
edit
dl
rm
os.path.html
43402
0644
edit
dl
rm
ossaudiodev.html
45594
0644
edit
dl
rm
othergui.html
9403
0644
edit
dl
rm
parser.html
42558
0644
edit
dl
rm
pdb.html
38603
0644
edit
dl
rm
persistence.html
15676
0644
edit
dl
rm
pickle.html
109684
0644
edit
dl
rm
pickletools.html
11475
0644
edit
dl
rm
pipes.html
19685
0644
edit
dl
rm
pkgutil.html
27367
0644
edit
dl
rm
platform.html
31599
0644
edit
dl
rm
plistlib.html
18344
0644
edit
dl
rm
popen2.html
27601
0644
edit
dl
rm
poplib.html
24320
0644
edit
dl
rm
posix.html
16626
0644
edit
dl
rm
posixfile.html
21387
0644
edit
dl
rm
pprint.html
32207
0644
edit
dl
rm
profile.html
72788
0644
edit
dl
rm
pty.html
10195
0644
edit
dl
rm
pwd.html
12388
0644
edit
dl
rm
pyclbr.html
15812
0644
edit
dl
rm
pydoc.html
13650
0644
edit
dl
rm
pyexpat.html
80886
0644
edit
dl
rm
python.html
12854
0644
edit
dl
rm
py_compile.html
11932
0644
edit
dl
rm
queue.html
26856
0644
edit
dl
rm
quopri.html
12739
0644
edit
dl
rm
random.html
42722
0644
edit
dl
rm
re.html
155985
0644
edit
dl
rm
readline.html
37383
0644
edit
dl
rm
repr.html
21778
0644
edit
dl
rm
resource.html
28286
0644
edit
dl
rm
restricted.html
12366
0644
edit
dl
rm
rexec.html
40566
0644
edit
dl
rm
rfc822.html
46408
0644
edit
dl
rm
rlcompleter.html
14460
0644
edit
dl
rm
robotparser.html
13403
0644
edit
dl
rm
runpy.html
21925
0644
edit
dl
rm
sched.html
19878
0644
edit
dl
rm
scrolledtext.html
9728
0644
edit
dl
rm
select.html
44090
0644
edit
dl
rm
sets.html
40151
0644
edit
dl
rm
sgi.html
10371
0644
edit
dl
rm
sgmllib.html
34464
0644
edit
dl
rm
sha.html
13062
0644
edit
dl
rm
shelve.html
29955
0644
edit
dl
rm
shlex.html
35033
0644
edit
dl
rm
shutil.html
45454
0644
edit
dl
rm
signal.html
34023
0644
edit
dl
rm
simplehttpserver.html
20351
0644
edit
dl
rm
simplexmlrpcserver.html
37794
0644
edit
dl
rm
site.html
26887
0644
edit
dl
rm
smtpd.html
13587
0644
edit
dl
rm
smtplib.html
47054
0644
edit
dl
rm
sndhdr.html
10993
0644
edit
dl
rm
socket.html
116414
0644
edit
dl
rm
socketserver.html
76430
0644
edit
dl
rm
someos.html
16472
0644
edit
dl
rm
spwd.html
11163
0644
edit
dl
rm
sqlite3.html
150014
0644
edit
dl
rm
ssl.html
202453
0644
edit
dl
rm
stat.html
34597
0644
edit
dl
rm
statvfs.html
11326
0644
edit
dl
rm
stdtypes.html
298144
0644
edit
dl
rm
string.html
120219
0644
edit
dl
rm
stringio.html
20061
0644
edit
dl
rm
stringprep.html
17729
0644
edit
dl
rm
strings.html
15905
0644
edit
dl
rm
struct.html
44896
0644
edit
dl
rm
subprocess.html
110447
0644
edit
dl
rm
sun.html
7253
0644
edit
dl
rm
sunau.html
30011
0644
edit
dl
rm
sunaudio.html
19236
0644
edit
dl
rm
symbol.html
8140
0644
edit
dl
rm
symtable.html
25871
0644
edit
dl
rm
sys.html
110996
0644
edit
dl
rm
sysconfig.html
26299
0644
edit
dl
rm
syslog.html
19737
0644
edit
dl
rm
tabnanny.html
11393
0644
edit
dl
rm
tarfile.html
88728
0644
edit
dl
rm
telnetlib.html
27782
0644
edit
dl
rm
tempfile.html
31903
0644
edit
dl
rm
termios.html
17309
0644
edit
dl
rm
test.html
57030
0644
edit
dl
rm
textwrap.html
30135
0644
edit
dl
rm
thread.html
21486
0644
edit
dl
rm
threading.html
86655
0644
edit
dl
rm
time.html
63798
0644
edit
dl
rm
timeit.html
40529
0644
edit
dl
rm
tix.html
50582
0644
edit
dl
rm
tk.html
26568
0644
edit
dl
rm
tkinter.html
84316
0644
edit
dl
rm
token.html
20999
0644
edit
dl
rm
tokenize.html
20607
0644
edit
dl
rm
trace.html
28668
0644
edit
dl
rm
traceback.html
40900
0644
edit
dl
rm
ttk.html
108515
0644
edit
dl
rm
tty.html
9753
0644
edit
dl
rm
turtle.html
230483
0644
edit
dl
rm
types.html
29833
0644
edit
dl
rm
undoc.html
24680
0644
edit
dl
rm
unicodedata.html
20186
0644
edit
dl
rm
unittest.html
225021
0644
edit
dl
rm
unix.html
11223
0644
edit
dl
rm
urllib.html
68266
0644
edit
dl
rm
urllib2.html
113380
0644
edit
dl
rm
urlparse.html
43474
0644
edit
dl
rm
user.html
12707
0644
edit
dl
rm
userdict.html
32069
0644
edit
dl
rm
uu.html
11810
0644
edit
dl
rm
uuid.html
30137
0644
edit
dl
rm
warnings.html
50950
0644
edit
dl
rm
wave.html
24894
0644
edit
dl
rm
weakref.html
38808
0644
edit
dl
rm
webbrowser.html
26565
0644
edit
dl
rm
whichdb.html
9499
0644
edit
dl
rm
windows.html
9817
0644
edit
dl
rm
winsound.html
20466
0644
edit
dl
rm
wsgiref.html
88384
0644
edit
dl
rm
xdrlib.html
33018
0644
edit
dl
rm
xml.dom.html
97877
0644
edit
dl
rm
xml.dom.minidom.html
43230
0644
edit
dl
rm
xml.dom.pulldom.html
13835
0644
edit
dl
rm
xml.etree.elementtree.html
111804
0644
edit
dl
rm
xml.html
18007
0644
edit
dl
rm
xml.sax.handler.html
41877
0644
edit
dl
rm
xml.sax.html
23458
0644
edit
dl
rm
xml.sax.reader.html
44802
0644
edit
dl
rm
xml.sax.utils.html
16087
0644
edit
dl
rm
xmlrpclib.html
69191
0644
edit
dl
rm
zipfile.html
62227
0644
edit
dl
rm
zipimport.html
22769
0644
edit
dl
rm
zlib.html
31230
0644
edit
dl
rm
_winreg.html
64631
0644
edit
dl
rm
__builtin__.html
11069
0644
edit
dl
rm
__future__.html
14688
0644
edit
dl
rm
__main__.html
7512
0644
edit
dl
rm
Edit:
/usr/share/doc/python2-docs/html/library/socket.html
(116414B)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>17.2. socket — Low-level networking interface — Python 2.7.16 documentation</title> <link rel="stylesheet" href="../_static/classic.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 2.7.16 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="next" title="17.3. ssl — TLS/SSL wrapper for socket objects" href="ssl.html" /> <link rel="prev" title="17.1. subprocess — Subprocess management" href="subprocess.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> <link rel="canonical" href="https://docs.python.org/2/library/socket.html" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="ssl.html" title="17.3. ssl — TLS/SSL wrapper for socket objects" accesskey="N">next</a> |</li> <li class="right" > <a href="subprocess.html" title="17.1. subprocess — Subprocess management" accesskey="P">previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.16 documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> <li class="nav-item nav-item-2"><a href="ipc.html" accesskey="U">17. Interprocess Communication and Networking</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="module-socket"> <span id="socket-low-level-networking-interface"></span><h1>17.2. <a class="reference internal" href="#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> — Low-level networking interface<a class="headerlink" href="#module-socket" title="Permalink to this headline">¶</a></h1> <p>This module provides access to the BSD <em>socket</em> interface. It is available on all modern Unix systems, Windows, Mac OS X, BeOS, OS/2, and probably additional platforms.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">Some behavior may be platform dependent, since calls are made to the operating system socket APIs.</p> </div> <p>For an introduction to socket programming (in C), see the following papers: An Introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest and An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J. Leffler et al, both in the 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 <span class="target" id="index-0"></span><a class="rfc reference external" href="https://tools.ietf.org/html/rfc3493.html"><strong>RFC 3493</strong></a> titled Basic Socket Interface Extensions for IPv6.</p> <p id="index-1">The Python interface is a straightforward transliteration of the Unix system call and library interface for sockets to Python’s object-oriented style: the <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a> function returns a <em class="dfn">socket object</em> whose methods implement the various socket system calls. Parameter types are somewhat higher-level than in the C interface: as with <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> operations on Python files, buffer allocation on receive operations is automatic, and buffer length is implicit on send operations.</p> <p id="host-port">Socket addresses are represented as follows: A single string is used for the <a class="reference internal" href="#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a> address family. A pair <code class="docutils literal notranslate"><span class="pre">(host,</span> <span class="pre">port)</span></code> is used for the <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> address family, where <em>host</em> is a string representing either a hostname in Internet domain notation like <code class="docutils literal notranslate"><span class="pre">'daring.cwi.nl'</span></code> or an IPv4 address like <code class="docutils literal notranslate"><span class="pre">'100.50.200.5'</span></code>, and <em>port</em> is an integer. For <a class="reference internal" href="#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a> address family, a four-tuple <code class="docutils literal notranslate"><span class="pre">(host,</span> <span class="pre">port,</span> <span class="pre">flowinfo,</span> <span class="pre">scopeid)</span></code> is used, where <em>flowinfo</em> and <em>scopeid</em> represents <code class="docutils literal notranslate"><span class="pre">sin6_flowinfo</span></code> and <code class="docutils literal notranslate"><span class="pre">sin6_scope_id</span></code> member in <code class="xref py py-const docutils literal notranslate"><span class="pre">struct</span> <span class="pre">sockaddr_in6</span></code> in C. For <a class="reference internal" href="#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> module methods, <em>flowinfo</em> and <em>scopeid</em> can be omitted just for backward compatibility. Note, however, omission of <em>scopeid</em> 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.</p> <p>For IPv4 addresses, two special forms are accepted instead of a host address: the empty string represents <code class="xref py py-const docutils literal notranslate"><span class="pre">INADDR_ANY</span></code>, and the string <code class="docutils literal notranslate"><span class="pre">'<broadcast>'</span></code> represents <code class="xref py py-const docutils literal notranslate"><span class="pre">INADDR_BROADCAST</span></code>. 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.</p> <p>If you use a hostname in the <em>host</em> 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 <em>host</em> portion.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.5: </span>AF_NETLINK sockets are represented as pairs <code class="docutils literal notranslate"><span class="pre">pid,</span> <span class="pre">groups</span></code>.</p> </div> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6: </span>Linux-only support for TIPC is also available using the <code class="xref py py-const docutils literal notranslate"><span class="pre">AF_TIPC</span></code> address family. TIPC is an open, non-IP based networked protocol designed for use in clustered computer environments. Addresses are represented by a tuple, and the fields depend on the address type. The general tuple form is <code class="docutils literal notranslate"><span class="pre">(addr_type,</span> <span class="pre">v1,</span> <span class="pre">v2,</span> <span class="pre">v3</span> <span class="pre">[,</span> <span class="pre">scope])</span></code>, where:</p> <ul> <li><p class="first"><em>addr_type</em> is one of <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ADDR_NAMESEQ</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ADDR_NAME</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ADDR_ID</span></code>.</p> </li> <li><p class="first"><em>scope</em> is one of <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ZONE_SCOPE</span></code>, <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_CLUSTER_SCOPE</span></code>, and <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_NODE_SCOPE</span></code>.</p> </li> <li><p class="first">If <em>addr_type</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ADDR_NAME</span></code>, then <em>v1</em> is the server type, <em>v2</em> is the port identifier, and <em>v3</em> should be 0.</p> <p>If <em>addr_type</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ADDR_NAMESEQ</span></code>, then <em>v1</em> is the server type, <em>v2</em> is the lower port number, and <em>v3</em> is the upper port number.</p> <p>If <em>addr_type</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">TIPC_ADDR_ID</span></code>, then <em>v1</em> is the node, <em>v2</em> is the reference, and <em>v3</em> should be set to 0.</p> </li> </ul> </div> <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 <a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">socket.error</span></code></a>.</p> <p>Non-blocking mode is supported through <a class="reference internal" href="#socket.socket.setblocking" title="socket.socket.setblocking"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setblocking()</span></code></a>. A generalization of this based on timeouts is supported through <a class="reference internal" href="#socket.socket.settimeout" title="socket.socket.settimeout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">settimeout()</span></code></a>.</p> <p>The module <a class="reference internal" href="#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> exports the following constants and functions:</p> <dl class="exception"> <dt id="socket.error"> <em class="property">exception </em><code class="descclassname">socket.</code><code class="descname">error</code><a class="headerlink" href="#socket.error" title="Permalink to this definition">¶</a></dt> <dd><p id="index-2">This exception is raised for socket-related errors. The accompanying value is either a string telling what went wrong or a pair <code class="docutils literal notranslate"><span class="pre">(errno,</span> <span class="pre">string)</span></code> representing an error returned by a system call, similar to the value accompanying <a class="reference internal" href="os.html#os.error" title="os.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">os.error</span></code></a>. See the module <a class="reference internal" href="errno.html#module-errno" title="errno: Standard errno system symbols."><code class="xref py py-mod docutils literal notranslate"><span class="pre">errno</span></code></a>, which contains names for the error codes defined by the underlying operating system.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 2.6: </span><a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">socket.error</span></code></a> is now a child class of <a class="reference internal" href="exceptions.html#exceptions.IOError" title="exceptions.IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a>.</p> </div> </dd></dl> <dl class="exception"> <dt id="socket.herror"> <em class="property">exception </em><code class="descclassname">socket.</code><code class="descname">herror</code><a class="headerlink" href="#socket.herror" title="Permalink to this definition">¶</a></dt> <dd><p>This exception is raised for address-related errors, i.e. for functions that use <em>h_errno</em> in the C API, including <a class="reference internal" href="#socket.gethostbyname_ex" title="socket.gethostbyname_ex"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyname_ex()</span></code></a> and <a class="reference internal" href="#socket.gethostbyaddr" title="socket.gethostbyaddr"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyaddr()</span></code></a>.</p> <p>The accompanying value is a pair <code class="docutils literal notranslate"><span class="pre">(h_errno,</span> <span class="pre">string)</span></code> representing an error returned by a library call. <em>string</em> represents the description of <em>h_errno</em>, as returned by the <code class="xref c c-func docutils literal notranslate"><span class="pre">hstrerror()</span></code> C function.</p> </dd></dl> <dl class="exception"> <dt id="socket.gaierror"> <em class="property">exception </em><code class="descclassname">socket.</code><code class="descname">gaierror</code><a class="headerlink" href="#socket.gaierror" title="Permalink to this definition">¶</a></dt> <dd><p>This exception is raised for address-related errors, for <a class="reference internal" href="#socket.getaddrinfo" title="socket.getaddrinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a> and <a class="reference internal" href="#socket.getnameinfo" title="socket.getnameinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">getnameinfo()</span></code></a>. The accompanying value is a pair <code class="docutils literal notranslate"><span class="pre">(error,</span> <span class="pre">string)</span></code> representing an error returned by a library call. <em>string</em> represents the description of <em>error</em>, as returned by the <code class="xref c c-func docutils literal notranslate"><span class="pre">gai_strerror()</span></code> C function. The <em>error</em> value will match one of the <code class="xref py py-const docutils literal notranslate"><span class="pre">EAI_*</span></code> constants defined in this module.</p> </dd></dl> <dl class="exception"> <dt id="socket.timeout"> <em class="property">exception </em><code class="descclassname">socket.</code><code class="descname">timeout</code><a class="headerlink" href="#socket.timeout" title="Permalink to this definition">¶</a></dt> <dd><p>This exception is raised when a timeout occurs on a socket which has had timeouts enabled via a prior call to <code class="xref py py-meth docutils literal notranslate"><span class="pre">settimeout()</span></code>. The accompanying value is a string whose value is currently always “timed out”.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="data"> <dt id="socket.AF_UNIX"> <code class="descclassname">socket.</code><code class="descname">AF_UNIX</code><a class="headerlink" href="#socket.AF_UNIX" title="Permalink to this definition">¶</a></dt> <dt id="socket.AF_INET"> <code class="descclassname">socket.</code><code class="descname">AF_INET</code><a class="headerlink" href="#socket.AF_INET" title="Permalink to this definition">¶</a></dt> <dt id="socket.AF_INET6"> <code class="descclassname">socket.</code><code class="descname">AF_INET6</code><a class="headerlink" href="#socket.AF_INET6" title="Permalink to this definition">¶</a></dt> <dd><p>These constants represent the address (and protocol) families, used for the first argument to <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a>. If the <a class="reference internal" href="#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a> constant is not defined then this protocol is unsupported.</p> </dd></dl> <dl class="data"> <dt id="socket.SOCK_STREAM"> <code class="descclassname">socket.</code><code class="descname">SOCK_STREAM</code><a class="headerlink" href="#socket.SOCK_STREAM" title="Permalink to this definition">¶</a></dt> <dt id="socket.SOCK_DGRAM"> <code class="descclassname">socket.</code><code class="descname">SOCK_DGRAM</code><a class="headerlink" href="#socket.SOCK_DGRAM" title="Permalink to this definition">¶</a></dt> <dt id="socket.SOCK_RAW"> <code class="descclassname">socket.</code><code class="descname">SOCK_RAW</code><a class="headerlink" href="#socket.SOCK_RAW" title="Permalink to this definition">¶</a></dt> <dt id="socket.SOCK_RDM"> <code class="descclassname">socket.</code><code class="descname">SOCK_RDM</code><a class="headerlink" href="#socket.SOCK_RDM" title="Permalink to this definition">¶</a></dt> <dt id="socket.SOCK_SEQPACKET"> <code class="descclassname">socket.</code><code class="descname">SOCK_SEQPACKET</code><a class="headerlink" href="#socket.SOCK_SEQPACKET" title="Permalink to this definition">¶</a></dt> <dd><p>These constants represent the socket types, used for the second argument to <a class="reference internal" href="#module-socket" title="socket: Low-level networking interface."><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a>. (Only <a class="reference internal" href="#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_STREAM</span></code></a> and <a class="reference internal" href="#socket.SOCK_DGRAM" title="socket.SOCK_DGRAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_DGRAM</span></code></a> appear to be generally useful.)</p> </dd></dl> <dl class="data"> <dt> <code class="descname">SO_*</code></dt> <dt id="socket.SOMAXCONN"> <code class="descclassname">socket.</code><code class="descname">SOMAXCONN</code><a class="headerlink" href="#socket.SOMAXCONN" title="Permalink to this definition">¶</a></dt> <dt> <code class="descname">MSG_*</code></dt> <dt> <code class="descname">SOL_*</code></dt> <dt> <code class="descname">IPPROTO_*</code></dt> <dt> <code class="descname">IPPORT_*</code></dt> <dt> <code class="descname">INADDR_*</code></dt> <dt> <code class="descname">IP_*</code></dt> <dt> <code class="descname">IPV6_*</code></dt> <dt> <code class="descname">EAI_*</code></dt> <dt> <code class="descname">AI_*</code></dt> <dt> <code class="descname">NI_*</code></dt> <dt> <code class="descname">TCP_*</code></dt> <dd><p>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 class="xref py py-meth docutils literal notranslate"><span class="pre">setsockopt()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">getsockopt()</span></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.</p> </dd></dl> <dl class="data"> <dt> <code class="descname">SIO_*</code></dt> <dt> <code class="descname">RCVALL_*</code></dt> <dd><p>Constants for Windows’ WSAIoctl(). The constants are used as arguments to the <a class="reference internal" href="#socket.socket.ioctl" title="socket.socket.ioctl"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ioctl()</span></code></a> method of socket objects.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="data"> <dt> <code class="descname">TIPC_*</code></dt> <dd><p>TIPC related constants, matching the ones exported by the C socket API. See the TIPC documentation for more information.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="data"> <dt id="socket.has_ipv6"> <code class="descclassname">socket.</code><code class="descname">has_ipv6</code><a class="headerlink" href="#socket.has_ipv6" title="Permalink to this definition">¶</a></dt> <dd><p>This constant contains a boolean value which indicates if IPv6 is supported on this platform.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.create_connection"> <code class="descclassname">socket.</code><code class="descname">create_connection</code><span class="sig-paren">(</span><em>address</em><span class="optional">[</span>, <em>timeout</em><span class="optional">[</span>, <em>source_address</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.create_connection" title="Permalink to this definition">¶</a></dt> <dd><p>Connect to a TCP service listening on the Internet <em>address</em> (a 2-tuple <code class="docutils literal notranslate"><span class="pre">(host,</span> <span class="pre">port)</span></code>), and return the socket object. This is a higher-level function than <a class="reference internal" href="#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.connect()</span></code></a>: if <em>host</em> is a non-numeric hostname, it will try to resolve it for both <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-data docutils literal notranslate"><span class="pre">AF_INET</span></code></a> and <a class="reference internal" href="#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-data docutils literal notranslate"><span class="pre">AF_INET6</span></code></a>, and then try to connect to all possible addresses in turn until a connection succeeds. This makes it easy to write clients that are compatible to both IPv4 and IPv6.</p> <p>Passing the optional <em>timeout</em> parameter will set the timeout on the socket instance before attempting to connect. If no <em>timeout</em> is supplied, the global default timeout setting returned by <a class="reference internal" href="#socket.getdefaulttimeout" title="socket.getdefaulttimeout"><code class="xref py py-func docutils literal notranslate"><span class="pre">getdefaulttimeout()</span></code></a> is used.</p> <p>If supplied, <em>source_address</em> must be a 2-tuple <code class="docutils literal notranslate"><span class="pre">(host,</span> <span class="pre">port)</span></code> for the socket to bind to as its source address before connecting. If host or port are ‘’ or 0 respectively the OS default behavior will be used.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 2.7: </span><em>source_address</em> was added.</p> </div> </dd></dl> <dl class="function"> <dt id="socket.getaddrinfo"> <code class="descclassname">socket.</code><code class="descname">getaddrinfo</code><span class="sig-paren">(</span><em>host</em>, <em>port</em><span class="optional">[</span>, <em>family</em><span class="optional">[</span>, <em>socktype</em><span class="optional">[</span>, <em>proto</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.getaddrinfo" title="Permalink to this definition">¶</a></dt> <dd><p>Translate the <em>host</em>/<em>port</em> argument into a sequence of 5-tuples that contain all the necessary arguments for creating a socket connected to that service. <em>host</em> is a domain name, a string representation of an IPv4/v6 address or <code class="docutils literal notranslate"><span class="pre">None</span></code>. <em>port</em> is a string service name such as <code class="docutils literal notranslate"><span class="pre">'http'</span></code>, a numeric port number or <code class="docutils literal notranslate"><span class="pre">None</span></code>. By passing <code class="docutils literal notranslate"><span class="pre">None</span></code> as the value of <em>host</em> and <em>port</em>, you can pass <code class="docutils literal notranslate"><span class="pre">NULL</span></code> to the underlying C API.</p> <p>The <em>family</em>, <em>socktype</em> and <em>proto</em> arguments can be optionally specified in order to narrow the list of addresses returned. By default, their value is <code class="docutils literal notranslate"><span class="pre">0</span></code>, meaning that the full range of results is selected. The <em>flags</em> argument can be one or several of the <code class="docutils literal notranslate"><span class="pre">AI_*</span></code> constants, and will influence how results are computed and returned. Its default value is <code class="docutils literal notranslate"><span class="pre">0</span></code>. For example, <code class="xref py py-const docutils literal notranslate"><span class="pre">AI_NUMERICHOST</span></code> will disable domain name resolution and will raise an error if <em>host</em> is a domain name.</p> <p>The function returns a list of 5-tuples with the following structure:</p> <p><code class="docutils literal notranslate"><span class="pre">(family,</span> <span class="pre">socktype,</span> <span class="pre">proto,</span> <span class="pre">canonname,</span> <span class="pre">sockaddr)</span></code></p> <p>In these tuples, <em>family</em>, <em>socktype</em>, <em>proto</em> are all integers and are meant to be passed to the <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a> function. <em>canonname</em> will be a string representing the canonical name of the <em>host</em> if <code class="xref py py-const docutils literal notranslate"><span class="pre">AI_CANONNAME</span></code> is part of the <em>flags</em> argument; else <em>canonname</em> will be empty. <em>sockaddr</em> is a tuple describing a socket address, whose format depends on the returned <em>family</em> (a <code class="docutils literal notranslate"><span class="pre">(address,</span> <span class="pre">port)</span></code> 2-tuple for <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a>, a <code class="docutils literal notranslate"><span class="pre">(address,</span> <span class="pre">port,</span> <span class="pre">flow</span> <span class="pre">info,</span> <span class="pre">scope</span> <span class="pre">id)</span></code> 4-tuple for <a class="reference internal" href="#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a>), and is meant to be passed to the <a class="reference internal" href="#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.connect()</span></code></a> method.</p> <p>The following example fetches address information for a hypothetical TCP connection to <code class="docutils literal notranslate"><span class="pre">example.org</span></code> on port 80 (results may differ on your system if IPv6 isn’t enabled):</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">socket</span><span class="o">.</span><span class="n">getaddrinfo</span><span class="p">(</span><span class="s2">"example.org"</span><span class="p">,</span> <span class="mi">80</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">IPPROTO_TCP</span><span class="p">)</span> <span class="go">[(10, 1, 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),</span> <span class="go"> (2, 1, 6, '', ('93.184.216.34', 80))]</span> </pre></div> </div> <div class="versionadded"> <p><span class="versionmodified">New in version 2.2.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.getfqdn"> <code class="descclassname">socket.</code><code class="descname">getfqdn</code><span class="sig-paren">(</span><span class="optional">[</span><em>name</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.getfqdn" title="Permalink to this definition">¶</a></dt> <dd><p>Return a fully qualified domain name for <em>name</em>. If <em>name</em> is omitted or empty, it is interpreted as the local host. To find the fully qualified name, the hostname returned by <a class="reference internal" href="#socket.gethostbyaddr" title="socket.gethostbyaddr"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyaddr()</span></code></a> is checked, followed by 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 <a class="reference internal" href="#socket.gethostname" title="socket.gethostname"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostname()</span></code></a> is returned.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.0.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.gethostbyname"> <code class="descclassname">socket.</code><code class="descname">gethostbyname</code><span class="sig-paren">(</span><em>hostname</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.gethostbyname" title="Permalink to this definition">¶</a></dt> <dd><p>Translate a host name to IPv4 address format. The IPv4 address is returned as a string, such as <code class="docutils literal notranslate"><span class="pre">'100.50.200.5'</span></code>. If the host name is an IPv4 address itself it is returned unchanged. See <a class="reference internal" href="#socket.gethostbyname_ex" title="socket.gethostbyname_ex"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyname_ex()</span></code></a> for a more complete interface. <a class="reference internal" href="#socket.gethostbyname" title="socket.gethostbyname"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyname()</span></code></a> does not support IPv6 name resolution, and <a class="reference internal" href="#socket.getaddrinfo" title="socket.getaddrinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a> should be used instead for IPv4/v6 dual stack support.</p> </dd></dl> <dl class="function"> <dt id="socket.gethostbyname_ex"> <code class="descclassname">socket.</code><code class="descname">gethostbyname_ex</code><span class="sig-paren">(</span><em>hostname</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.gethostbyname_ex" title="Permalink to this definition">¶</a></dt> <dd><p>Translate a host name to IPv4 address format, extended interface. Return a triple <code class="docutils literal notranslate"><span class="pre">(hostname,</span> <span class="pre">aliaslist,</span> <span class="pre">ipaddrlist)</span></code> where <em>hostname</em> is the primary host name responding to the given <em>ip_address</em>, <em>aliaslist</em> is a (possibly empty) list of alternative host names for the same address, and <em>ipaddrlist</em> is a list of IPv4 addresses for the same interface on the same host (often but not always a single address). <a class="reference internal" href="#socket.gethostbyname_ex" title="socket.gethostbyname_ex"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyname_ex()</span></code></a> does not support IPv6 name resolution, and <a class="reference internal" href="#socket.getaddrinfo" title="socket.getaddrinfo"><code class="xref py py-func docutils literal notranslate"><span class="pre">getaddrinfo()</span></code></a> should be used instead for IPv4/v6 dual stack support.</p> </dd></dl> <dl class="function"> <dt id="socket.gethostname"> <code class="descclassname">socket.</code><code class="descname">gethostname</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.gethostname" title="Permalink to this definition">¶</a></dt> <dd><p>Return a string containing the hostname of the machine where the Python interpreter is currently executing.</p> <p>If you want to know the current machine’s IP address, you may want to use <code class="docutils literal notranslate"><span class="pre">gethostbyname(gethostname())</span></code>. This operation assumes that there is a valid address-to-host mapping for the host, and the assumption does not always hold.</p> <p>Note: <a class="reference internal" href="#socket.gethostname" title="socket.gethostname"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostname()</span></code></a> doesn’t always return the fully qualified domain name; use <code class="docutils literal notranslate"><span class="pre">getfqdn()</span></code> (see above).</p> </dd></dl> <dl class="function"> <dt id="socket.gethostbyaddr"> <code class="descclassname">socket.</code><code class="descname">gethostbyaddr</code><span class="sig-paren">(</span><em>ip_address</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.gethostbyaddr" title="Permalink to this definition">¶</a></dt> <dd><p>Return a triple <code class="docutils literal notranslate"><span class="pre">(hostname,</span> <span class="pre">aliaslist,</span> <span class="pre">ipaddrlist)</span></code> where <em>hostname</em> is the primary host name responding to the given <em>ip_address</em>, <em>aliaslist</em> is a (possibly empty) list of alternative host names for the same address, and <em>ipaddrlist</em> 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 <a class="reference internal" href="#socket.getfqdn" title="socket.getfqdn"><code class="xref py py-func docutils literal notranslate"><span class="pre">getfqdn()</span></code></a>. <a class="reference internal" href="#socket.gethostbyaddr" title="socket.gethostbyaddr"><code class="xref py py-func docutils literal notranslate"><span class="pre">gethostbyaddr()</span></code></a> supports both IPv4 and IPv6.</p> </dd></dl> <dl class="function"> <dt id="socket.getnameinfo"> <code class="descclassname">socket.</code><code class="descname">getnameinfo</code><span class="sig-paren">(</span><em>sockaddr</em>, <em>flags</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.getnameinfo" title="Permalink to this definition">¶</a></dt> <dd><p>Translate a socket address <em>sockaddr</em> into a 2-tuple <code class="docutils literal notranslate"><span class="pre">(host,</span> <span class="pre">port)</span></code>. Depending on the settings of <em>flags</em>, the result can contain a fully-qualified domain name or numeric address representation in <em>host</em>. Similarly, <em>port</em> can contain a string port name or a numeric port number.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.2.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.getprotobyname"> <code class="descclassname">socket.</code><code class="descname">getprotobyname</code><span class="sig-paren">(</span><em>protocolname</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.getprotobyname" title="Permalink to this definition">¶</a></dt> <dd><p>Translate an Internet protocol name (for example, <code class="docutils literal notranslate"><span class="pre">'icmp'</span></code>) to a constant suitable for passing as the (optional) third argument to the <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a> function. This is usually only needed for sockets opened in “raw” mode (<a class="reference internal" href="#socket.SOCK_RAW" title="socket.SOCK_RAW"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_RAW</span></code></a>); for the normal socket modes, the correct protocol is chosen automatically if the protocol is omitted or zero.</p> </dd></dl> <dl class="function"> <dt id="socket.getservbyname"> <code class="descclassname">socket.</code><code class="descname">getservbyname</code><span class="sig-paren">(</span><em>servicename</em><span class="optional">[</span>, <em>protocolname</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.getservbyname" title="Permalink to this definition">¶</a></dt> <dd><p>Translate an Internet service name and protocol name to a port number for that service. The optional protocol name, if given, should be <code class="docutils literal notranslate"><span class="pre">'tcp'</span></code> or <code class="docutils literal notranslate"><span class="pre">'udp'</span></code>, otherwise any protocol will match.</p> </dd></dl> <dl class="function"> <dt id="socket.getservbyport"> <code class="descclassname">socket.</code><code class="descname">getservbyport</code><span class="sig-paren">(</span><em>port</em><span class="optional">[</span>, <em>protocolname</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.getservbyport" title="Permalink to this definition">¶</a></dt> <dd><p>Translate an Internet port number and protocol name to a service name for that service. The optional protocol name, if given, should be <code class="docutils literal notranslate"><span class="pre">'tcp'</span></code> or <code class="docutils literal notranslate"><span class="pre">'udp'</span></code>, otherwise any protocol will match.</p> </dd></dl> <dl class="function"> <dt id="socket.socket"> <code class="descclassname">socket.</code><code class="descname">socket</code><span class="sig-paren">(</span><span class="optional">[</span><em>family</em><span class="optional">[</span>, <em>type</em><span class="optional">[</span>, <em>proto</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket" title="Permalink to this definition">¶</a></dt> <dd><p>Create a new socket using the given address family, socket type and protocol number. The address family should be <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> (the default), <a class="reference internal" href="#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a> or <a class="reference internal" href="#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a>. The socket type should be <a class="reference internal" href="#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_STREAM</span></code></a> (the default), <a class="reference internal" href="#socket.SOCK_DGRAM" title="socket.SOCK_DGRAM"><code class="xref py py-const docutils literal notranslate"><span class="pre">SOCK_DGRAM</span></code></a> or perhaps one of the other <code class="docutils literal notranslate"><span class="pre">SOCK_</span></code> constants. The protocol number is usually zero and may be omitted in that case.</p> </dd></dl> <dl class="function"> <dt id="socket.socketpair"> <code class="descclassname">socket.</code><code class="descname">socketpair</code><span class="sig-paren">(</span><span class="optional">[</span><em>family</em><span class="optional">[</span>, <em>type</em><span class="optional">[</span>, <em>proto</em><span class="optional">]</span><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socketpair" title="Permalink to this definition">¶</a></dt> <dd><p>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 <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a> function above. The default family is <a class="reference internal" href="#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_UNIX</span></code></a> if defined on the platform; otherwise, the default is <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a>. Availability: Unix.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.4.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.fromfd"> <code class="descclassname">socket.</code><code class="descname">fromfd</code><span class="sig-paren">(</span><em>fd</em>, <em>family</em>, <em>type</em><span class="optional">[</span>, <em>proto</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.fromfd" title="Permalink to this definition">¶</a></dt> <dd><p>Duplicate the file descriptor <em>fd</em> (an integer as returned by a file object’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">fileno()</span></code> method) and build a socket object from the result. Address family, socket type and protocol number are as for the <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a> 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.</p> </dd></dl> <dl class="function"> <dt id="socket.ntohl"> <code class="descclassname">socket.</code><code class="descname">ntohl</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.ntohl" title="Permalink to this definition">¶</a></dt> <dd><p>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.</p> </dd></dl> <dl class="function"> <dt id="socket.ntohs"> <code class="descclassname">socket.</code><code class="descname">ntohs</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.ntohs" title="Permalink to this definition">¶</a></dt> <dd><p>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.</p> </dd></dl> <dl class="function"> <dt id="socket.htonl"> <code class="descclassname">socket.</code><code class="descname">htonl</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.htonl" title="Permalink to this definition">¶</a></dt> <dd><p>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.</p> </dd></dl> <dl class="function"> <dt id="socket.htons"> <code class="descclassname">socket.</code><code class="descname">htons</code><span class="sig-paren">(</span><em>x</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.htons" title="Permalink to this definition">¶</a></dt> <dd><p>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.</p> </dd></dl> <dl class="function"> <dt id="socket.inet_aton"> <code class="descclassname">socket.</code><code class="descname">inet_aton</code><span class="sig-paren">(</span><em>ip_string</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.inet_aton" title="Permalink to this definition">¶</a></dt> <dd><p>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 <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">in_addr</span></code>, which is the C type for the 32-bit packed binary this function returns.</p> <p><a class="reference internal" href="#socket.inet_aton" title="socket.inet_aton"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_aton()</span></code></a> also accepts strings with less than three dots; see the Unix manual page <em class="manpage">inet(3)</em> for details.</p> <p>If the IPv4 address string passed to this function is invalid, <a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">socket.error</span></code></a> will be raised. Note that exactly what is valid depends on the underlying C implementation of <code class="xref c c-func docutils literal notranslate"><span class="pre">inet_aton()</span></code>.</p> <p><a class="reference internal" href="#socket.inet_aton" title="socket.inet_aton"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_aton()</span></code></a> does not support IPv6, and <a class="reference internal" href="#socket.inet_pton" title="socket.inet_pton"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_pton()</span></code></a> should be used instead for IPv4/v6 dual stack support.</p> </dd></dl> <dl class="function"> <dt id="socket.inet_ntoa"> <code class="descclassname">socket.</code><code class="descname">inet_ntoa</code><span class="sig-paren">(</span><em>packed_ip</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.inet_ntoa" title="Permalink to this definition">¶</a></dt> <dd><p>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 <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">in_addr</span></code>, which is the C type for the 32-bit packed binary data this function takes as an argument.</p> <p>If the string passed to this function is not exactly 4 bytes in length, <a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">socket.error</span></code></a> will be raised. <a class="reference internal" href="#socket.inet_ntoa" title="socket.inet_ntoa"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_ntoa()</span></code></a> does not support IPv6, and <a class="reference internal" href="#socket.inet_ntop" title="socket.inet_ntop"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_ntop()</span></code></a> should be used instead for IPv4/v6 dual stack support.</p> </dd></dl> <dl class="function"> <dt id="socket.inet_pton"> <code class="descclassname">socket.</code><code class="descname">inet_pton</code><span class="sig-paren">(</span><em>address_family</em>, <em>ip_string</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.inet_pton" title="Permalink to this definition">¶</a></dt> <dd><p>Convert an IP address from its family-specific string format to a packed, binary format. <a class="reference internal" href="#socket.inet_pton" title="socket.inet_pton"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_pton()</span></code></a> is useful when a library or network protocol calls for an object of type <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">in_addr</span></code> (similar to <a class="reference internal" href="#socket.inet_aton" title="socket.inet_aton"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_aton()</span></code></a>) or <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">in6_addr</span></code>.</p> <p>Supported values for <em>address_family</em> are currently <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> and <a class="reference internal" href="#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a>. If the IP address string <em>ip_string</em> is invalid, <a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">socket.error</span></code></a> will be raised. Note that exactly what is valid depends on both the value of <em>address_family</em> and the underlying implementation of <code class="xref c c-func docutils literal notranslate"><span class="pre">inet_pton()</span></code>.</p> <p>Availability: Unix (maybe not all platforms).</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.inet_ntop"> <code class="descclassname">socket.</code><code class="descname">inet_ntop</code><span class="sig-paren">(</span><em>address_family</em>, <em>packed_ip</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.inet_ntop" title="Permalink to this definition">¶</a></dt> <dd><p>Convert a packed IP address (a string of some number of characters) to its standard, family-specific string representation (for example, <code class="docutils literal notranslate"><span class="pre">'7.10.0.5'</span></code> or <code class="docutils literal notranslate"><span class="pre">'5aef:2b::8'</span></code>) <a class="reference internal" href="#socket.inet_ntop" title="socket.inet_ntop"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_ntop()</span></code></a> is useful when a library or network protocol returns an object of type <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">in_addr</span></code> (similar to <a class="reference internal" href="#socket.inet_ntoa" title="socket.inet_ntoa"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_ntoa()</span></code></a>) or <code class="xref c c-type docutils literal notranslate"><span class="pre">struct</span> <span class="pre">in6_addr</span></code>.</p> <p>Supported values for <em>address_family</em> are currently <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> and <a class="reference internal" href="#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET6</span></code></a>. If the string <em>packed_ip</em> is not the correct length for the specified address family, <a class="reference internal" href="exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised. A <a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">socket.error</span></code></a> is raised for errors from the call to <a class="reference internal" href="#socket.inet_ntop" title="socket.inet_ntop"><code class="xref py py-func docutils literal notranslate"><span class="pre">inet_ntop()</span></code></a>.</p> <p>Availability: Unix (maybe not all platforms).</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.getdefaulttimeout"> <code class="descclassname">socket.</code><code class="descname">getdefaulttimeout</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.getdefaulttimeout" title="Permalink to this definition">¶</a></dt> <dd><p>Return the default timeout in seconds (float) for new socket objects. A value of <code class="docutils literal notranslate"><span class="pre">None</span></code> indicates that new socket objects have no timeout. When the socket module is first imported, the default is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="function"> <dt id="socket.setdefaulttimeout"> <code class="descclassname">socket.</code><code class="descname">setdefaulttimeout</code><span class="sig-paren">(</span><em>timeout</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.setdefaulttimeout" title="Permalink to this definition">¶</a></dt> <dd><p>Set the default timeout in seconds (float) for new socket objects. A value of <code class="docutils literal notranslate"><span class="pre">None</span></code> indicates that new socket objects have no timeout. When the socket module is first imported, the default is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="data"> <dt id="socket.SocketType"> <code class="descclassname">socket.</code><code class="descname">SocketType</code><a class="headerlink" href="#socket.SocketType" title="Permalink to this definition">¶</a></dt> <dd><p>This is a Python type object that represents the socket object type. It is the same as <code class="docutils literal notranslate"><span class="pre">type(socket(...))</span></code>.</p> </dd></dl> <div class="admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt>Module <a class="reference internal" href="socketserver.html#module-SocketServer" title="SocketServer: A framework for network servers."><code class="xref py py-mod docutils literal notranslate"><span class="pre">SocketServer</span></code></a></dt> <dd>Classes that simplify writing network servers.</dd> <dt>Module <a class="reference internal" href="ssl.html#module-ssl" title="ssl: TLS/SSL wrapper for socket objects"><code class="xref py py-mod docutils literal notranslate"><span class="pre">ssl</span></code></a></dt> <dd>A TLS/SSL wrapper for socket objects.</dd> </dl> </div> <div class="section" id="socket-objects"> <span id="id1"></span><h2>17.2.1. Socket Objects<a class="headerlink" href="#socket-objects" title="Permalink to this headline">¶</a></h2> <p>Socket objects have the following methods. Except for <code class="xref py py-meth docutils literal notranslate"><span class="pre">makefile()</span></code> these correspond to Unix system calls applicable to sockets.</p> <dl class="method"> <dt id="socket.socket.accept"> <code class="descclassname">socket.</code><code class="descname">accept</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.accept" title="Permalink to this definition">¶</a></dt> <dd><p>Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair <code class="docutils literal notranslate"><span class="pre">(conn,</span> <span class="pre">address)</span></code> where <em>conn</em> is a <em>new</em> socket object usable to send and receive data on the connection, and <em>address</em> is the address bound to the socket on the other end of the connection.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.bind"> <code class="descclassname">socket.</code><code class="descname">bind</code><span class="sig-paren">(</span><em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.bind" title="Permalink to this definition">¶</a></dt> <dd><p>Bind the socket to <em>address</em>. The socket must not already be bound. (The format of <em>address</em> depends on the address family — see above.)</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">This method has historically accepted a pair of parameters for <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> addresses instead of only a tuple. This was never intentional and is no longer available in Python 2.0 and later.</p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.close"> <code class="descclassname">socket.</code><code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.close" title="Permalink to this definition">¶</a></dt> <dd><p>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.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last"><a class="reference internal" href="#socket.socket.close" title="socket.socket.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> releases the resource associated with a connection but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call <a class="reference internal" href="#socket.socket.shutdown" title="socket.socket.shutdown"><code class="xref py py-meth docutils literal notranslate"><span class="pre">shutdown()</span></code></a> before <a class="reference internal" href="#socket.socket.close" title="socket.socket.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a>.</p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.connect"> <code class="descclassname">socket.</code><code class="descname">connect</code><span class="sig-paren">(</span><em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.connect" title="Permalink to this definition">¶</a></dt> <dd><p>Connect to a remote socket at <em>address</em>. (The format of <em>address</em> depends on the address family — see above.)</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">This method has historically accepted a pair of parameters for <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> addresses instead of only a tuple. This was never intentional and is no longer available in Python 2.0 and later.</p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.connect_ex"> <code class="descclassname">socket.</code><code class="descname">connect_ex</code><span class="sig-paren">(</span><em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.connect_ex" title="Permalink to this definition">¶</a></dt> <dd><p>Like <code class="docutils literal notranslate"><span class="pre">connect(address)</span></code>, but return an error indicator instead of raising an exception for errors returned by the C-level <code class="xref c c-func docutils literal notranslate"><span class="pre">connect()</span></code> call (other problems, such as “host not found,” can still raise exceptions). The error indicator is <code class="docutils literal notranslate"><span class="pre">0</span></code> if the operation succeeded, otherwise the value of the <code class="xref c c-data docutils literal notranslate"><span class="pre">errno</span></code> variable. This is useful to support, for example, asynchronous connects.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">This method has historically accepted a pair of parameters for <a class="reference internal" href="#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-const docutils literal notranslate"><span class="pre">AF_INET</span></code></a> addresses instead of only a tuple. This was never intentional and is no longer available in Python 2.0 and later.</p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.fileno"> <code class="descclassname">socket.</code><code class="descname">fileno</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.fileno" title="Permalink to this definition">¶</a></dt> <dd><p>Return the socket’s file descriptor (a small integer). This is useful with <a class="reference internal" href="select.html#select.select" title="select.select"><code class="xref py py-func docutils literal notranslate"><span class="pre">select.select()</span></code></a>.</p> <p>Under Windows the small integer returned by this method cannot be used where a file descriptor can be used (such as <a class="reference internal" href="os.html#os.fdopen" title="os.fdopen"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.fdopen()</span></code></a>). Unix does not have this limitation.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.getpeername"> <code class="descclassname">socket.</code><code class="descname">getpeername</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.getpeername" title="Permalink to this definition">¶</a></dt> <dd><p>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.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.getsockname"> <code class="descclassname">socket.</code><code class="descname">getsockname</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.getsockname" title="Permalink to this definition">¶</a></dt> <dd><p>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.)</p> </dd></dl> <dl class="method"> <dt id="socket.socket.getsockopt"> <code class="descclassname">socket.</code><code class="descname">getsockopt</code><span class="sig-paren">(</span><em>level</em>, <em>optname</em><span class="optional">[</span>, <em>buflen</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.getsockopt" title="Permalink to this definition">¶</a></dt> <dd><p>Return the value of the given socket option (see the Unix man page <em class="manpage">getsockopt(2)</em>). The needed symbolic constants (<code class="xref py py-const docutils literal notranslate"><span class="pre">SO_*</span></code> etc.) are defined in this module. If <em>buflen</em> is absent, an integer option is assumed and its integer value is returned by the function. If <em>buflen</em> 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 <a class="reference internal" href="struct.html#module-struct" title="struct: Interpret strings as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> for a way to decode C structures encoded as strings).</p> </dd></dl> <dl class="method"> <dt id="socket.socket.ioctl"> <code class="descclassname">socket.</code><code class="descname">ioctl</code><span class="sig-paren">(</span><em>control</em>, <em>option</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.ioctl" title="Permalink to this definition">¶</a></dt> <dd><table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Platform:</th><td class="field-body">Windows</td> </tr> </tbody> </table> <p>The <a class="reference internal" href="#socket.socket.ioctl" title="socket.socket.ioctl"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ioctl()</span></code></a> method is a limited interface to the WSAIoctl system interface. Please refer to the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/ms741621%28VS.85%29.aspx">Win32 documentation</a> for more information.</p> <p>On other platforms, the generic <a class="reference internal" href="fcntl.html#fcntl.fcntl" title="fcntl.fcntl"><code class="xref py py-func docutils literal notranslate"><span class="pre">fcntl.fcntl()</span></code></a> and <a class="reference internal" href="fcntl.html#fcntl.ioctl" title="fcntl.ioctl"><code class="xref py py-func docutils literal notranslate"><span class="pre">fcntl.ioctl()</span></code></a> functions may be used; they accept a socket object as their first argument.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.listen"> <code class="descclassname">socket.</code><code class="descname">listen</code><span class="sig-paren">(</span><em>backlog</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.listen" title="Permalink to this definition">¶</a></dt> <dd><p>Listen for connections made to the socket. The <em>backlog</em> argument specifies the maximum number of queued connections and should be at least 0; the maximum value is system-dependent (usually 5), the minimum value is forced to 0.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.makefile"> <code class="descclassname">socket.</code><code class="descname">makefile</code><span class="sig-paren">(</span><span class="optional">[</span><em>mode</em><span class="optional">[</span>, <em>bufsize</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.makefile" title="Permalink to this definition">¶</a></dt> <dd><p id="index-3">Return a <em class="dfn">file object</em> associated with the socket. (File objects are described in <a class="reference internal" href="stdtypes.html#bltin-file-objects"><span class="std std-ref">File Objects</span></a>.) The file object does not close the socket explicitly when its <a class="reference internal" href="#socket.socket.close" title="socket.socket.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method is called, but only removes its reference to the socket object, so that the socket will be closed if it is not referenced from anywhere else.</p> <p>The socket must be in blocking mode (it can not have a timeout). The optional <em>mode</em> and <em>bufsize</em> arguments are interpreted the same way as by the built-in <a class="reference internal" href="functions.html#file" title="file"><code class="xref py py-func docutils literal notranslate"><span class="pre">file()</span></code></a> function.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">On Windows, the file-like object created by <a class="reference internal" href="#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">makefile()</span></code></a> cannot be used where a file object with a file descriptor is expected, such as the stream arguments of <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-meth docutils literal notranslate"><span class="pre">subprocess.Popen()</span></code></a>.</p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.recv"> <code class="descclassname">socket.</code><code class="descname">recv</code><span class="sig-paren">(</span><em>bufsize</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.recv" title="Permalink to this definition">¶</a></dt> <dd><p>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 <em>bufsize</em>. See the Unix manual page <em class="manpage">recv(2)</em> for the meaning of the optional argument <em>flags</em>; it defaults to zero.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">For best match with hardware and network realities, the value of <em>bufsize</em> should be a relatively small power of 2, for example, 4096.</p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.recvfrom"> <code class="descclassname">socket.</code><code class="descname">recvfrom</code><span class="sig-paren">(</span><em>bufsize</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.recvfrom" title="Permalink to this definition">¶</a></dt> <dd><p>Receive data from the socket. The return value is a pair <code class="docutils literal notranslate"><span class="pre">(string,</span> <span class="pre">address)</span></code> where <em>string</em> is a string representing the data received and <em>address</em> is the address of the socket sending the data. See the Unix manual page <em class="manpage">recv(2)</em> for the meaning of the optional argument <em>flags</em>; it defaults to zero. (The format of <em>address</em> depends on the address family — see above.)</p> </dd></dl> <dl class="method"> <dt id="socket.socket.recvfrom_into"> <code class="descclassname">socket.</code><code class="descname">recvfrom_into</code><span class="sig-paren">(</span><em>buffer</em><span class="optional">[</span>, <em>nbytes</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.recvfrom_into" title="Permalink to this definition">¶</a></dt> <dd><p>Receive data from the socket, writing it into <em>buffer</em> instead of creating a new string. The return value is a pair <code class="docutils literal notranslate"><span class="pre">(nbytes,</span> <span class="pre">address)</span></code> where <em>nbytes</em> is the number of bytes received and <em>address</em> is the address of the socket sending the data. See the Unix manual page <em class="manpage">recv(2)</em> for the meaning of the optional argument <em>flags</em>; it defaults to zero. (The format of <em>address</em> depends on the address family — see above.)</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.5.</span></p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.recv_into"> <code class="descclassname">socket.</code><code class="descname">recv_into</code><span class="sig-paren">(</span><em>buffer</em><span class="optional">[</span>, <em>nbytes</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.recv_into" title="Permalink to this definition">¶</a></dt> <dd><p>Receive up to <em>nbytes</em> bytes from the socket, storing the data into a buffer rather than creating a new string. If <em>nbytes</em> is not specified (or 0), receive up to the size available in the given buffer. Returns the number of bytes received. See the Unix manual page <em class="manpage">recv(2)</em> for the meaning of the optional argument <em>flags</em>; it defaults to zero.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.5.</span></p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.send"> <code class="descclassname">socket.</code><code class="descname">send</code><span class="sig-paren">(</span><em>string</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.send" title="Permalink to this definition">¶</a></dt> <dd><p>Send data to the socket. The socket must be connected to a remote socket. The optional <em>flags</em> argument has the same meaning as for <a class="reference internal" href="#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> 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. For further information on this concept, consult the <a class="reference internal" href="../howto/sockets.html#socket-howto"><span class="std std-ref">Socket Programming HOWTO</span></a>.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.sendall"> <code class="descclassname">socket.</code><code class="descname">sendall</code><span class="sig-paren">(</span><em>string</em><span class="optional">[</span>, <em>flags</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.sendall" title="Permalink to this definition">¶</a></dt> <dd><p>Send data to the socket. The socket must be connected to a remote socket. The optional <em>flags</em> argument has the same meaning as for <a class="reference internal" href="#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> above. Unlike <a class="reference internal" href="#socket.socket.send" title="socket.socket.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a>, this method continues to send data from <em>string</em> until either all data has been sent or an error occurs. <code class="docutils literal notranslate"><span class="pre">None</span></code> 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.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.sendto"> <code class="descclassname">socket.</code><code class="descname">sendto</code><span class="sig-paren">(</span><em>string</em>, <em>address</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.sendto" title="Permalink to this definition">¶</a></dt> <dt> <code class="descclassname">socket.</code><code class="descname">sendto</code><span class="sig-paren">(</span><em>string</em>, <em>flags</em>, <em>address</em><span class="sig-paren">)</span></dt> <dd><p>Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by <em>address</em>. The optional <em>flags</em> argument has the same meaning as for <a class="reference internal" href="#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> above. Return the number of bytes sent. (The format of <em>address</em> depends on the address family — see above.)</p> </dd></dl> <dl class="method"> <dt id="socket.socket.setblocking"> <code class="descclassname">socket.</code><code class="descname">setblocking</code><span class="sig-paren">(</span><em>flag</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.setblocking" title="Permalink to this definition">¶</a></dt> <dd><p>Set blocking or non-blocking mode of the socket: if <em>flag</em> 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 <a class="reference internal" href="#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> call doesn’t find any data, or if a <a class="reference internal" href="#socket.socket.send" title="socket.socket.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> call can’t immediately dispose of the data, an <a class="reference internal" href="#socket.error" title="socket.error"><code class="xref py py-exc docutils literal notranslate"><span class="pre">error</span></code></a> exception is raised; in blocking mode, the calls block until they can proceed. <code class="docutils literal notranslate"><span class="pre">s.setblocking(0)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">s.settimeout(0.0)</span></code>; <code class="docutils literal notranslate"><span class="pre">s.setblocking(1)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">s.settimeout(None)</span></code>.</p> </dd></dl> <dl class="method"> <dt id="socket.socket.settimeout"> <code class="descclassname">socket.</code><code class="descname">settimeout</code><span class="sig-paren">(</span><em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.settimeout" title="Permalink to this definition">¶</a></dt> <dd><p>Set a timeout on blocking socket operations. The <em>value</em> argument can be a nonnegative float expressing seconds, or <code class="docutils literal notranslate"><span class="pre">None</span></code>. If a float is given, subsequent socket operations will raise a <a class="reference internal" href="#socket.timeout" title="socket.timeout"><code class="xref py py-exc docutils literal notranslate"><span class="pre">timeout</span></code></a> exception if the timeout period <em>value</em> has elapsed before the operation has completed. Setting a timeout of <code class="docutils literal notranslate"><span class="pre">None</span></code> disables timeouts on socket operations. <code class="docutils literal notranslate"><span class="pre">s.settimeout(0.0)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">s.setblocking(0)</span></code>; <code class="docutils literal notranslate"><span class="pre">s.settimeout(None)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">s.setblocking(1)</span></code>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="method"> <dt id="socket.socket.gettimeout"> <code class="descclassname">socket.</code><code class="descname">gettimeout</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.gettimeout" title="Permalink to this definition">¶</a></dt> <dd><p>Return the timeout in seconds (float) associated with socket operations, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no timeout is set. This reflects the last call to <a class="reference internal" href="#socket.socket.setblocking" title="socket.socket.setblocking"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setblocking()</span></code></a> or <a class="reference internal" href="#socket.socket.settimeout" title="socket.socket.settimeout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">settimeout()</span></code></a>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <p>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 or the system returns an error (such as connection timed out). 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 or if the system returns an error. The <a class="reference internal" href="#socket.socket.setblocking" title="socket.socket.setblocking"><code class="xref py py-meth docutils literal notranslate"><span class="pre">setblocking()</span></code></a> method is simply a shorthand for certain <a class="reference internal" href="#socket.socket.settimeout" title="socket.socket.settimeout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">settimeout()</span></code></a> calls.</p> <p>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 <a class="reference internal" href="#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">makefile()</span></code></a> 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.</p> <p>Note that the <a class="reference internal" href="#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a> operation is subject to the timeout setting, and in general it is recommended to call <a class="reference internal" href="#socket.socket.settimeout" title="socket.socket.settimeout"><code class="xref py py-meth docutils literal notranslate"><span class="pre">settimeout()</span></code></a> before calling <a class="reference internal" href="#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a> or pass a timeout parameter to <a class="reference internal" href="#socket.create_connection" title="socket.create_connection"><code class="xref py py-meth docutils literal notranslate"><span class="pre">create_connection()</span></code></a>. The system network stack may return a connection timeout error of its own regardless of any Python socket timeout setting.</p> <dl class="method"> <dt id="socket.socket.setsockopt"> <code class="descclassname">socket.</code><code class="descname">setsockopt</code><span class="sig-paren">(</span><em>level</em>, <em>optname</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.setsockopt" title="Permalink to this definition">¶</a></dt> <dd><p id="index-4">Set the value of the given socket option (see the Unix manual page <em class="manpage">setsockopt(2)</em>). The needed symbolic constants are defined in the <a class="reference internal" href="#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> module (<code class="xref py py-const docutils literal notranslate"><span class="pre">SO_*</span></code> 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 <a class="reference internal" href="struct.html#module-struct" title="struct: Interpret strings as packed binary data."><code class="xref py py-mod docutils literal notranslate"><span class="pre">struct</span></code></a> for a way to encode C structures as strings).</p> </dd></dl> <dl class="method"> <dt id="socket.socket.shutdown"> <code class="descclassname">socket.</code><code class="descname">shutdown</code><span class="sig-paren">(</span><em>how</em><span class="sig-paren">)</span><a class="headerlink" href="#socket.socket.shutdown" title="Permalink to this definition">¶</a></dt> <dd><p>Shut down one or both halves of the connection. If <em>how</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">SHUT_RD</span></code>, further receives are disallowed. If <em>how</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">SHUT_WR</span></code>, further sends are disallowed. If <em>how</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">SHUT_RDWR</span></code>, further sends and receives are disallowed. Depending on the platform, shutting down one half of the connection can also close the opposite half (e.g. on Mac OS X, <code class="docutils literal notranslate"><span class="pre">shutdown(SHUT_WR)</span></code> does not allow further reads on the other end of the connection).</p> </dd></dl> <p>Note that there are no methods <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code>; use <a class="reference internal" href="#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> and <a class="reference internal" href="#socket.socket.send" title="socket.socket.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> without <em>flags</em> argument instead.</p> <p>Socket objects also have these (read-only) attributes that correspond to the values given to the <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket</span></code></a> constructor.</p> <dl class="attribute"> <dt id="socket.socket.family"> <code class="descclassname">socket.</code><code class="descname">family</code><a class="headerlink" href="#socket.socket.family" title="Permalink to this definition">¶</a></dt> <dd><p>The socket family.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.5.</span></p> </div> </dd></dl> <dl class="attribute"> <dt id="socket.socket.type"> <code class="descclassname">socket.</code><code class="descname">type</code><a class="headerlink" href="#socket.socket.type" title="Permalink to this definition">¶</a></dt> <dd><p>The socket type.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.5.</span></p> </div> </dd></dl> <dl class="attribute"> <dt id="socket.socket.proto"> <code class="descclassname">socket.</code><code class="descname">proto</code><a class="headerlink" href="#socket.socket.proto" title="Permalink to this definition">¶</a></dt> <dd><p>The socket protocol.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.5.</span></p> </div> </dd></dl> </div> <div class="section" id="example"> <span id="socket-example"></span><h2>17.2.2. Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2> <p>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 <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a>, <a class="reference internal" href="#socket.socket.bind" title="socket.socket.bind"><code class="xref py py-meth docutils literal notranslate"><span class="pre">bind()</span></code></a>, <a class="reference internal" href="#socket.socket.listen" title="socket.socket.listen"><code class="xref py py-meth docutils literal notranslate"><span class="pre">listen()</span></code></a>, <a class="reference internal" href="#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal notranslate"><span class="pre">accept()</span></code></a> (possibly repeating the <a class="reference internal" href="#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal notranslate"><span class="pre">accept()</span></code></a> to service more than one client), while a client only needs the sequence <a class="reference internal" href="#socket.socket" title="socket.socket"><code class="xref py py-func docutils literal notranslate"><span class="pre">socket()</span></code></a>, <a class="reference internal" href="#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a>. Also note that the server does not <a class="reference internal" href="#socket.socket.sendall" title="socket.socket.sendall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">sendall()</span></code></a>/<a class="reference internal" href="#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> on the socket it is listening on but on the new socket returned by <a class="reference internal" href="#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal notranslate"><span class="pre">accept()</span></code></a>.</p> <p>The first two examples support IPv4 only.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Echo server program</span> <span class="kn">import</span> <span class="nn">socket</span> <span class="n">HOST</span> <span class="o">=</span> <span class="s1">''</span> <span class="c1"># Symbolic name meaning all available interfaces</span> <span class="n">PORT</span> <span class="o">=</span> <span class="mi">50007</span> <span class="c1"># Arbitrary non-privileged port</span> <span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_STREAM</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">bind</span><span class="p">((</span><span class="n">HOST</span><span class="p">,</span> <span class="n">PORT</span><span class="p">))</span> <span class="n">s</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="n">conn</span><span class="p">,</span> <span class="n">addr</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">accept</span><span class="p">()</span> <span class="nb">print</span> <span class="s1">'Connected by'</span><span class="p">,</span> <span class="n">addr</span> <span class="k">while</span> <span class="mi">1</span><span class="p">:</span> <span class="n">data</span> <span class="o">=</span> <span class="n">conn</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">data</span><span class="p">:</span> <span class="k">break</span> <span class="n">conn</span><span class="o">.</span><span class="n">sendall</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> <span class="n">conn</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Echo client program</span> <span class="kn">import</span> <span class="nn">socket</span> <span class="n">HOST</span> <span class="o">=</span> <span class="s1">'daring.cwi.nl'</span> <span class="c1"># The remote host</span> <span class="n">PORT</span> <span class="o">=</span> <span class="mi">50007</span> <span class="c1"># The same port as used by the server</span> <span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_STREAM</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">connect</span><span class="p">((</span><span class="n">HOST</span><span class="p">,</span> <span class="n">PORT</span><span class="p">))</span> <span class="n">s</span><span class="o">.</span><span class="n">sendall</span><span class="p">(</span><span class="s1">'Hello, world'</span><span class="p">)</span> <span class="n">data</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="nb">print</span> <span class="s1">'Received'</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> </pre></div> </div> <p>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.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Echo server program</span> <span class="kn">import</span> <span class="nn">socket</span> <span class="kn">import</span> <span class="nn">sys</span> <span class="n">HOST</span> <span class="o">=</span> <span class="kc">None</span> <span class="c1"># Symbolic name meaning all available interfaces</span> <span class="n">PORT</span> <span class="o">=</span> <span class="mi">50007</span> <span class="c1"># Arbitrary non-privileged port</span> <span class="n">s</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">for</span> <span class="n">res</span> <span class="ow">in</span> <span class="n">socket</span><span class="o">.</span><span class="n">getaddrinfo</span><span class="p">(</span><span class="n">HOST</span><span class="p">,</span> <span class="n">PORT</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">AF_UNSPEC</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_STREAM</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">AI_PASSIVE</span><span class="p">):</span> <span class="n">af</span><span class="p">,</span> <span class="n">socktype</span><span class="p">,</span> <span class="n">proto</span><span class="p">,</span> <span class="n">canonname</span><span class="p">,</span> <span class="n">sa</span> <span class="o">=</span> <span class="n">res</span> <span class="k">try</span><span class="p">:</span> <span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">af</span><span class="p">,</span> <span class="n">socktype</span><span class="p">,</span> <span class="n">proto</span><span class="p">)</span> <span class="k">except</span> <span class="n">socket</span><span class="o">.</span><span class="n">error</span> <span class="k">as</span> <span class="n">msg</span><span class="p">:</span> <span class="n">s</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">continue</span> <span class="k">try</span><span class="p">:</span> <span class="n">s</span><span class="o">.</span><span class="n">bind</span><span class="p">(</span><span class="n">sa</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">listen</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="k">except</span> <span class="n">socket</span><span class="o">.</span><span class="n">error</span> <span class="k">as</span> <span class="n">msg</span><span class="p">:</span> <span class="n">s</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="n">s</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">continue</span> <span class="k">break</span> <span class="k">if</span> <span class="n">s</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span> <span class="nb">print</span> <span class="s1">'could not open socket'</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="n">conn</span><span class="p">,</span> <span class="n">addr</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">accept</span><span class="p">()</span> <span class="nb">print</span> <span class="s1">'Connected by'</span><span class="p">,</span> <span class="n">addr</span> <span class="k">while</span> <span class="mi">1</span><span class="p">:</span> <span class="n">data</span> <span class="o">=</span> <span class="n">conn</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">data</span><span class="p">:</span> <span class="k">break</span> <span class="n">conn</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> <span class="n">conn</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> </pre></div> </div> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Echo client program</span> <span class="kn">import</span> <span class="nn">socket</span> <span class="kn">import</span> <span class="nn">sys</span> <span class="n">HOST</span> <span class="o">=</span> <span class="s1">'daring.cwi.nl'</span> <span class="c1"># The remote host</span> <span class="n">PORT</span> <span class="o">=</span> <span class="mi">50007</span> <span class="c1"># The same port as used by the server</span> <span class="n">s</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">for</span> <span class="n">res</span> <span class="ow">in</span> <span class="n">socket</span><span class="o">.</span><span class="n">getaddrinfo</span><span class="p">(</span><span class="n">HOST</span><span class="p">,</span> <span class="n">PORT</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">AF_UNSPEC</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_STREAM</span><span class="p">):</span> <span class="n">af</span><span class="p">,</span> <span class="n">socktype</span><span class="p">,</span> <span class="n">proto</span><span class="p">,</span> <span class="n">canonname</span><span class="p">,</span> <span class="n">sa</span> <span class="o">=</span> <span class="n">res</span> <span class="k">try</span><span class="p">:</span> <span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">af</span><span class="p">,</span> <span class="n">socktype</span><span class="p">,</span> <span class="n">proto</span><span class="p">)</span> <span class="k">except</span> <span class="n">socket</span><span class="o">.</span><span class="n">error</span> <span class="k">as</span> <span class="n">msg</span><span class="p">:</span> <span class="n">s</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">continue</span> <span class="k">try</span><span class="p">:</span> <span class="n">s</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="n">sa</span><span class="p">)</span> <span class="k">except</span> <span class="n">socket</span><span class="o">.</span><span class="n">error</span> <span class="k">as</span> <span class="n">msg</span><span class="p">:</span> <span class="n">s</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="n">s</span> <span class="o">=</span> <span class="kc">None</span> <span class="k">continue</span> <span class="k">break</span> <span class="k">if</span> <span class="n">s</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span> <span class="nb">print</span> <span class="s1">'could not open socket'</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">sendall</span><span class="p">(</span><span class="s1">'Hello, world'</span><span class="p">)</span> <span class="n">data</span> <span class="o">=</span> <span class="n">s</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">1024</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> <span class="nb">print</span> <span class="s1">'Received'</span><span class="p">,</span> <span class="nb">repr</span><span class="p">(</span><span class="n">data</span><span class="p">)</span> </pre></div> </div> <p>The last example shows how to write a very simple network sniffer with raw sockets on Windows. The example requires administrator privileges to modify the interface:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">socket</span> <span class="c1"># the public network interface</span> <span class="n">HOST</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">gethostbyname</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">gethostname</span><span class="p">())</span> <span class="c1"># create a raw socket and bind it to the public interface</span> <span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_RAW</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">IPPROTO_IP</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">bind</span><span class="p">((</span><span class="n">HOST</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span> <span class="c1"># Include IP headers</span> <span class="n">s</span><span class="o">.</span><span class="n">setsockopt</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">IPPROTO_IP</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">IP_HDRINCL</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="c1"># receive all packages</span> <span class="n">s</span><span class="o">.</span><span class="n">ioctl</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">SIO_RCVALL</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">RCVALL_ON</span><span class="p">)</span> <span class="c1"># receive a package</span> <span class="nb">print</span> <span class="n">s</span><span class="o">.</span><span class="n">recvfrom</span><span class="p">(</span><span class="mi">65565</span><span class="p">)</span> <span class="c1"># disabled promiscuous mode</span> <span class="n">s</span><span class="o">.</span><span class="n">ioctl</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">SIO_RCVALL</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">RCVALL_OFF</span><span class="p">)</span> </pre></div> </div> <p>Running an example several times with too small delay between executions, could lead to this error:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">socket</span><span class="o">.</span><span class="n">error</span><span class="p">:</span> <span class="p">[</span><span class="n">Errno</span> <span class="mi">98</span><span class="p">]</span> <span class="n">Address</span> <span class="n">already</span> <span class="ow">in</span> <span class="n">use</span> </pre></div> </div> <p>This is because the previous execution has left the socket in a <code class="docutils literal notranslate"><span class="pre">TIME_WAIT</span></code> state, and can’t be immediately reused.</p> <p>There is a <a class="reference internal" href="#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a> flag to set, in order to prevent this, <code class="xref py py-data docutils literal notranslate"><span class="pre">socket.SO_REUSEADDR</span></code>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">s</span> <span class="o">=</span> <span class="n">socket</span><span class="o">.</span><span class="n">socket</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">AF_INET</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SOCK_STREAM</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">setsockopt</span><span class="p">(</span><span class="n">socket</span><span class="o">.</span><span class="n">SOL_SOCKET</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">SO_REUSEADDR</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span> <span class="n">s</span><span class="o">.</span><span class="n">bind</span><span class="p">((</span><span class="n">HOST</span><span class="p">,</span> <span class="n">PORT</span><span class="p">))</span> </pre></div> </div> <p>the <code class="xref py py-data docutils literal notranslate"><span class="pre">SO_REUSEADDR</span></code> flag tells the kernel to reuse a local socket in <code class="docutils literal notranslate"><span class="pre">TIME_WAIT</span></code> state, without waiting for its natural timeout to expire.</p> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">17.2. <code class="docutils literal notranslate"><span class="pre">socket</span></code> — Low-level networking interface</a><ul> <li><a class="reference internal" href="#socket-objects">17.2.1. Socket Objects</a></li> <li><a class="reference internal" href="#example">17.2.2. Example</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="subprocess.html" title="previous chapter">17.1. <code class="docutils literal notranslate"><span class="pre">subprocess</span></code> — Subprocess management</a></p> <h4>Next topic</h4> <p class="topless"><a href="ssl.html" title="next chapter">17.3. <code class="docutils literal notranslate"><span class="pre">ssl</span></code> — TLS/SSL wrapper for socket objects</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/library/socket.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="ssl.html" title="17.3. ssl — TLS/SSL wrapper for socket objects" >next</a> |</li> <li class="right" > <a href="subprocess.html" title="17.1. subprocess — Subprocess management" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.16 documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li> <li class="nav-item nav-item-2"><a href="ipc.html" >17. Interprocess Communication and Networking</a> »</li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Mar 27, 2019. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6. </div> </body> </html>
Save
cmd:
run