Describe the reason for SIGPIPE

README.rst

@@ -76,6 +76,35 @@ RST packet it uses SO_LINGER socket option.
 `rstserver.py <https://github.com/rspivak/csdesign/blob/master/rstserver.py>`_
 
 
+The Nature of SIGPIPE
+~~~~~~~~~~~~~~~~~~~~~
+
+At some point when writing to a socket you might get an exception
+*"socket.error: [Errno 32] Broken pipe"*.
+
+The rule is that when a process tries to write to a socket that has
+already received an RST packet, the SIGPIPE signal is sent to that
+process which causes the exception.
+
+The code in *sigpipe.py* shows how to simulate *SIGPIPE*.
+
+`sigpipe.py <https://github.com/rspivak/csdesign/blob/master/sigpipe.py>`_
+
+First you need to start `rstserver.py <https://github.com/rspivak/csdesign/blob/master/rstserver.py>`_
+
+Then run *sigpipe.py* which in turn connects to the *rstserver*, gets
+an RST as a response, ignores it and tries to write to the socket:
+
+::
+
+    $ python sigpipe.py
+    [Errno 104] Connection reset by peer
+
+    Traceback (most recent call last):
+      File "sigpipe.py", line 43, in <module>
+        s.send('hello')
+    socket.error: [Errno 32] Broken pipe
+
 Roadmap
 -------
 
@@ -91,8 +120,6 @@ Roadmap
 
 - Documentation for every example
 
-- Miscellanea, SIGPIPE
-
 Acknowledgments
 ---------------
 

sigpipe.py

@@ -0,0 +1,43 @@
+###############################################################################
+#
+# Copyright (c) 2012 Ruslan Spivak
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+###############################################################################
+
+__author__ = 'Ruslan Spivak <ruslan.spivak@gmail.com>'
+
+import socket
+
+# connect to rstserver, port 2000
+s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+s.connect(('', 2000))
+
+# first read gets an RST packet
+try:
+    s.recv(1024)
+except socket.error as e:
+    print e
+    print
+
+# write after getting the RST causes SIGPIPE signal
+# to be sent to this process which causes a socket.error
+# exception
+s.send('hello')