/usr/share/doc/libghc-network-doc/html/Network-Socket-ByteString.html is in libghc-network-doc 2.6.3.1-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 | <!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="Content-Type" content="text/html; charset=UTF-8" /><title>Network.Socket.ByteString</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script src="file:///usr/share/javascript/mathjax/MathJax.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Network-Socket-ByteString.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Network-Socket-ByteString.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">network-2.6.3.1: Low-level networking interface</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Copyright</th><td>(c) Johan Tibell 2007-2010</td></tr><tr><th>License</th><td>BSD-style</td></tr><tr><th>Maintainer</th><td>johan.tibell@gmail.com</td></tr><tr><th>Stability</th><td>stable</td></tr><tr><th>Portability</th><td>portable</td></tr><tr><th>Safe Haskell</th><td>None</td></tr><tr><th>Language</th><td>Haskell98</td></tr></table><p class="caption">Network.Socket.ByteString</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Send data to a socket</a><ul><li><a href="#g:2">Vectored I/O</a></li></ul></li><li><a href="#g:3">Receive data from a socket</a></li><li><a href="#g:4">Example</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>This module provides access to the BSD <em>socket</em> interface. This
module is generally more efficient than the <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-String.html#t:String">String</a></code> based network
functions in <code><a href="Network.html#v:Socket">Socket</a></code>. For detailed documentation, consult
your favorite POSIX socket reference. All functions communicate
failures by converting the error number to <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#v:IOError">IOError</a></code>.</p><p>This module is made to be imported with <code><a href="Network.html#v:Socket">Socket</a></code> like so:</p><pre>import Network.Socket hiding (send, sendTo, recv, recvFrom)
import Network.Socket.ByteString</pre></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:send">send</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a></li><li class="src short"><a href="#v:sendAll">sendAll</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:sendTo">sendTo</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a></li><li class="src short"><a href="#v:sendAllTo">sendAllTo</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:sendMany">sendMany</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a>] -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:sendManyTo">sendManyTo</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a>] -> <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</li><li class="src short"><a href="#v:recv">recv</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:recvFrom">recvFrom</a> :: <a href="Network-Socket.html#t:Socket">Socket</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a>, <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a>)</li></ul></div><div id="interface"><h1 id="g:1">Send data to a socket</h1><div class="top"><p class="src"><a id="v:send" class="def">send</a> <a href="src/Network-Socket-ByteString.html#send" class="link">Source</a> <a href="#v:send" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Connected socket</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>Data to send</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>Number of bytes sent</p></td></tr></table></div><div class="doc"><p>Send data to the socket. The socket must be connected to a
remote socket. Returns the number of bytes sent. Applications are
responsible for ensuring that all data has been sent.</p><p>Sending data to closed socket may lead to undefined behaviour.</p></div></div><div class="top"><p class="src"><a id="v:sendAll" class="def">sendAll</a> <a href="src/Network-Socket-ByteString.html#sendAll" class="link">Source</a> <a href="#v:sendAll" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Connected socket</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>Data to send</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Send data to the socket. The socket must be connected to a
remote socket. Unlike <code><a href="Network-Socket-ByteString.html#v:send">send</a></code>, this function continues to send data
until either all data has been sent or an error occurs. On error,
an exception is raised, and there is no way to determine how much
data, if any, was successfully sent.</p><p>Sending data to closed socket may lead to undefined behaviour.</p></div></div><div class="top"><p class="src"><a id="v:sendTo" class="def">sendTo</a> <a href="src/Network-Socket-ByteString.html#sendTo" class="link">Source</a> <a href="#v:sendTo" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Socket</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>Data to send</p></td></tr><tr><td class="src">-> <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a></td><td class="doc"><p>Recipient address</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>Number of bytes sent</p></td></tr></table></div><div class="doc"><p>Send data to the socket. The recipient can be specified
explicitly, so the socket need not be in a connected state.
Returns the number of bytes sent. Applications are responsible for
ensuring that all data has been sent.</p><p>Sending data to closed socket may lead to undefined behaviour.</p></div></div><div class="top"><p class="src"><a id="v:sendAllTo" class="def">sendAllTo</a> <a href="src/Network-Socket-ByteString.html#sendAllTo" class="link">Source</a> <a href="#v:sendAllTo" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Socket</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>Data to send</p></td></tr><tr><td class="src">-> <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a></td><td class="doc"><p>Recipient address</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Send data to the socket. The recipient can be specified
explicitly, so the socket need not be in a connected state. Unlike
<code><a href="Network-Socket-ByteString.html#v:sendTo">sendTo</a></code>, this function continues to send data until either all
data has been sent or an error occurs. On error, an exception is
raised, and there is no way to determine how much data, if any, was
successfully sent.</p><p>Sending data to closed socket may lead to undefined behaviour.</p></div></div><h2 id="g:2">Vectored I/O</h2><div class="doc"><p>Vectored I/O, also known as scatter/gather I/O, allows multiple
data segments to be sent using a single system call, without first
concatenating the segments. For example, given a list of
<code>ByteString</code>s, <code>xs</code>,</p><pre>sendMany sock xs</pre><p>is equivalent to</p><pre>sendAll sock (concat xs)</pre><p>but potentially more efficient.</p><p>Vectored I/O are often useful when implementing network protocols
that, for example, group data into segments consisting of one or
more fixed-length headers followed by a variable-length body.</p></div><div class="top"><p class="src"><a id="v:sendMany" class="def">sendMany</a> <a href="src/Network-Socket-ByteString.html#sendMany" class="link">Source</a> <a href="#v:sendMany" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Connected socket</p></td></tr><tr><td class="src">-> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a>]</td><td class="doc"><p>Data to send</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Send data to the socket. The socket must be in a connected
state. The data is sent as if the parts have been concatenated.
This function continues to send data until either all data has been
sent or an error occurs. On error, an exception is raised, and
there is no way to determine how much data, if any, was
successfully sent.</p><p>Sending data to closed socket may lead to undefined behaviour.</p></div></div><div class="top"><p class="src"><a id="v:sendManyTo" class="def">sendManyTo</a> <a href="src/Network-Socket-ByteString.html#sendManyTo" class="link">Source</a> <a href="#v:sendManyTo" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Socket</p></td></tr><tr><td class="src">-> [<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a>]</td><td class="doc"><p>Data to send</p></td></tr><tr><td class="src">-> <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a></td><td class="doc"><p>Recipient address</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> ()</td><td class="doc empty"> </td></tr></table></div><div class="doc"><p>Send data to the socket. The recipient can be specified
explicitly, so the socket need not be in a connected state. The
data is sent as if the parts have been concatenated. This function
continues to send data until either all data has been sent or an
error occurs. On error, an exception is raised, and there is no
way to determine how much data, if any, was successfully sent.</p><p>Sending data to closed socket may lead to undefined behaviour.</p></div></div><h1 id="g:3">Receive data from a socket</h1><div class="top"><p class="src"><a id="v:recv" class="def">recv</a> <a href="src/Network-Socket-ByteString.html#recv" class="link">Source</a> <a href="#v:recv" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Connected socket</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>Maximum number of bytes to receive</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></td><td class="doc"><p>Data received</p></td></tr></table></div><div class="doc"><p>Receive data from the socket. The socket must be in a connected
state. This function may return fewer bytes than specified. If
the message is longer than the specified length, it may be
discarded depending on the type of socket. This function may block
until a message arrives.</p><p>Considering hardware and network realities, the maximum number of bytes to
receive should be a small power of 2, e.g., 4096.</p><p>For TCP sockets, a zero length return value means the peer has
closed its half side of the connection.</p><p>Receiving data from closed socket may lead to undefined behaviour.</p></div></div><div class="top"><p class="src"><a id="v:recvFrom" class="def">recvFrom</a> <a href="src/Network-Socket-ByteString.html#recvFrom" class="link">Source</a> <a href="#v:recvFrom" class="selflink">#</a></p><div class="subs arguments"><p class="caption">Arguments</p><table><tr><td class="src">:: <a href="Network-Socket.html#t:Socket">Socket</a></td><td class="doc"><p>Socket</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/Data-Int.html#t:Int">Int</a></td><td class="doc"><p>Maximum number of bytes to receive</p></td></tr><tr><td class="src">-> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.0.0/System-IO.html#t:IO">IO</a> (<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a>, <a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a>)</td><td class="doc"><p>Data received and sender address</p></td></tr></table></div><div class="doc"><p>Receive data from the socket. The socket need not be in a
connected state. Returns <code>(bytes, address)</code> where <code>bytes</code> is a
<code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> representing the data received and <code>address</code> is a
<code><a href="Network-Socket-Internal.html#t:SockAddr">SockAddr</a></code> representing the address of the sending socket.</p><p>Receiving data from closed socket may lead to undefined behaviour.</p></div></div><h1 id="g:4">Example</h1><div class="doc"><p>Here are two minimal example programs using the TCP/IP protocol: a
server that echoes all data that it receives back (servicing only
one client) and a client using it.</p><pre>-- Echo server program
module Main where
import Control.Monad (unless)
import Network.Socket hiding (recv)
import qualified Data.ByteString as S
import Network.Socket.ByteString (recv, sendAll)
main :: IO ()
main = withSocketsDo $
do addrinfos <- getAddrInfo
(Just (defaultHints {addrFlags = [AI_PASSIVE]}))
Nothing (Just "3000")
let serveraddr = head addrinfos
sock <- socket (addrFamily serveraddr) Stream defaultProtocol
bind sock (addrAddress serveraddr)
listen sock 1
(conn, _) <- accept sock
talk conn
close conn
close sock
where
talk :: Socket -> IO ()
talk conn =
do msg <- recv conn 1024
unless (S.null msg) $ sendAll conn msg >> talk conn</pre><pre>-- Echo client program
module Main where
import Network.Socket hiding (recv)
import Network.Socket.ByteString (recv, sendAll)
import qualified Data.ByteString.Char8 as C
main :: IO ()
main = withSocketsDo $
do addrinfos <- getAddrInfo Nothing (Just "") (Just "3000")
let serveraddr = head addrinfos
sock <- socket (addrFamily serveraddr) Stream defaultProtocol
connect sock (addrAddress serveraddr)
sendAll sock $ C.pack "Hello, world!"
msg <- recv sock 1024
close sock
putStr "Received "
C.putStrLn msg</pre></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.17.2</p></div></body></html>
|