Ticket #108: test.html

File test.html, 6.1 kB (added by tibbe, 4 years ago)
Line 
1<html>
2<head>
3<title>Network.Socket.ByteString</title>
4<link href="test.css" type="text/css" rel="stylesheet"></link>
5</head>
6
7<body>
8
9<div id="header">
10  <h1>Network.Socket.ByteString</h1>
11</div>
12
13<div class="article">
14
15<h3>Contents</h3>
16
17<ul>
18  <li><a href="#">Send data to a socket</a></li>
19  <li><a href="#">Receive data from a socket</a></li>
20  <li><a href="#">Example</a></li>
21</ul>
22
23<h2>Description</h2>
24
25<p>This module provides access to the BSD socket interface. This
26module is generally more efficient than the String based network
27functions in Network.Socket. For detailed documentation, consult your
28favorite POSIX socket reference. All functions communicate failures by
29converting the error number to System.IO.IOError.</p>
30
31<p>This module is made to be imported with Network.Socket like so:</p>
32
33<pre>
34import Network.Socket hiding (send, sendTo, recv, recvFrom)
35import Network.Socket.ByteString
36</pre>
37
38<h2>Synopsis</h2>
39
40<ul>
41  <li><a href="#">send :: Socket -> ByteString -> IO Int</a></li>
42  <li><a href="#">sendAll :: Socket -> ByteString -> IO ()</a></li>
43  <li><a href="#">sendMany :: Socket -> [ByteString] -> IO ()</a></li>
44  <li><a href="#">sendTo :: Socket -> ByteString -> SockAddr -> IO Int</a></li>
45  <li><a href="#">sendAllTo :: Socket -> ByteString -> SockAddr -> IO ()</a></li>
46  <li><a href="#">sendManyTo :: Socket -> [ByteString] -> SockAddr -> IO ()</a></li>
47  <li><a href="#">recv :: Socket -> Int -> IO ByteString</a></li>
48  <li><a href="#">recvFrom :: Socket -> Int -> IO (ByteString, SockAddr)</a></li>
49</ul>
50
51<h2>Send data to a socket</h2>
52
53<dl>
54  <dt class="itemname">send</dt>
55  <dd>
56    <dl>
57      <dt>:: <a href="#" class="typename">Socket</a></dt>
58      <dd>Connected socket</dd>
59      <dt>-> <a href="#" class="typename">ByteString</a></dt>
60      <dd>Data to send</dd>
61      <dt>-> <a href="#" class="typename">IO</a> <a href="#" class="typename">Int</a></dt>
62      <dd>Number of bytes sent</dd>
63    </dl>
64   
65    <p>Send data to the socket. The socket must be connected to a
66      remote socket. Returns the number of bytes sent. Applications
67      are responsible for ensuring that all data has been sent.</p>
68  </dd>
69 
70  <dt class="itemname">sendAll</dt>
71  <dd>
72    <dl>
73      <dt>:: <a href="#" class="typename">Socket</a></dt>
74      <dd>Connected socket</dd>
75      <dt>-> <a href="#" class="typename">ByteString</a></dt>
76      <dd>Data to send</dd>
77      <dt>-> <a href="#" class="typename">IO</a> ()</dt>
78      <dd></dd>
79    </dl>
80   
81    <p>Send data to the socket. The socket must be connected to a
82      remote socket. Unlike send, this function continues to send data
83      until either all data has been sent or an error occurs. On
84      error, an exception is raised, and there is no way to determine
85      how much data, if any, was successfully sent.</p>
86  </dd>
87</dd>
88</dl>
89
90<h2>Receive data from a socket</h2>
91
92<dl>
93  <dt class="itemname">recv</dt>
94  <dd>
95    <dl>
96      <dt>:: <a href="#" class="typename">Socket</a></dt>
97      <dd>Connected socket</dd>
98      <dt>-> <a href="#" class="typename">Int</a></dt>
99      <dd>Maximum number of bytes to receive</dd>
100      <dt>-> <a href="#" class="typename">IO</a> <a href="#" class="typename">ByteString</a></dt>
101      <dd>Data received</dd>
102    </dl>
103   
104    <p>Receive data from the socket. The socket must be in a connected
105      state. This function may return fewer bytes than specified. If
106      the message is longer than the specified length, it may be
107      discarded depending on the type of socket. This function may
108      block until a message arrives.</p>
109   
110    <p>Considering hardware and network realities, the maximum number
111      of bytes to receive should be a small power of 2, e.g.,
112      4096.</p>
113   
114    <p>For TCP sockets, a zero length return value means the peer has
115      closed its half side of the connection.</p>
116  </dd>
117 
118  <dt class="itemname">recvFrom</dt>
119  <dd>
120    <dl>
121      <dt>:: <a href="#" class="typename">Socket</a></dt>
122      <dd>Socket</dd>
123      <dt>-> <a href="#" class="typename">Int</a></dt>
124      <dd>Maximum number of bytes to receive</dd>
125      <dt>-> <a href="#" class="typename">IO</a>
126        (<a href="#" class="typename">ByteString</a>, <a href="#" class="typename">SockAddr</a>)</dt>
127      <dd>Data received</dd>
128    </dl>
129   
130    <p>Receive data from the socket. The socket need not be in a
131      connected state. Returns <code>(bytes, address)</code>
132      where <code>bytes</code> is a ByteString representing the data
133      received and <code>address</code> is a SockAddr representing the
134      address of the sending socket.</p>
135  </dd>
136</dl>
137
138<h2>Example</h2>
139
140<p>Here are two minimal example programs using the TCP/IP protocol: a
141server that echoes all data that it receives back (servicing only one
142client) and a client using it.</p>
143
144<pre>
145-- Echo server program
146module Main where
147
148import Control.Monad
149import qualified Data.ByteString as S
150import Network.Socket hiding (recv)
151import Network.Socket.ByteString
152
153main :: IO ()
154main = withSocketsDo $
155    do addrinfos <- getAddrInfo Nothing (Just "") (Just "3000")
156       let serveraddr = head addrinfos
157       sock <- socket (addrFamily serveraddr) Stream defaultProtocol
158       bindSocket sock (addrAddress serveraddr)
159       listen sock 1
160       (conn, _) <- accept sock
161       talk conn
162       sClose conn
163       sClose sock
164
165    where
166      talk :: Socket -> IO ()
167      talk conn =
168          do msg <- recv conn 1024
169             unless (S.null msg) $ sendAll conn msg >> talk conn
170</pre>
171
172<pre>
173-- Echo client program
174module Main where
175
176import qualified Data.ByteString.Char8 as C
177import Network.Socket hiding (recv)
178import Network.Socket.ByteString
179
180main :: IO ()
181main = withSocketsDo $
182    do addrinfos <- getAddrInfo Nothing (Just "") (Just "3000")
183       let serveraddr = head addrinfos
184       sock <- socket (addrFamily serveraddr) Stream defaultProtocol
185       connect sock (addrAddress serveraddr)
186       sendAll sock $ C.pack "Hello, world!"
187       msg <- recv sock 1024
188       sClose sock
189       putStr "Received "
190       C.putStrLn msg
191</pre>
192
193</div> <!-- article -->
194
195<div id="footer">
196  <p>Produced by Haddock version 2.4.2</p>
197</div>
198
199</body>
200</html>