Copyright | (c) Johan Tibell 2007-2010 |
---|---|
License | BSD-style |
Maintainer | johan.tibell@gmail.com |
Stability | stable |
Portability | portable |
Safe Haskell | None |
Language | Haskell98 |
This module provides access to the BSD socket interface. This
module is generally more efficient than the String
based network
functions in Socket
. For detailed documentation, consult
your favorite POSIX socket reference. All functions communicate
failures by converting the error number to IOError
.
This module is made to be imported with Socket
like so:
import Network.Socket hiding (send, sendTo, recv, recvFrom) import Network.Socket.ByteString
- send :: Socket -> ByteString -> IO Int
- sendAll :: Socket -> ByteString -> IO ()
- sendTo :: Socket -> ByteString -> SockAddr -> IO Int
- sendAllTo :: Socket -> ByteString -> SockAddr -> IO ()
- sendMany :: Socket -> [ByteString] -> IO ()
- sendManyTo :: Socket -> [ByteString] -> SockAddr -> IO ()
- recv :: Socket -> Int -> IO ByteString
- recvFrom :: Socket -> Int -> IO (ByteString, SockAddr)
Send data to a socket
:: Socket | Connected socket |
-> ByteString | Data to send |
-> IO Int | Number of bytes sent |
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.
Sending data to closed socket may lead to undefined behaviour.
:: Socket | Connected socket |
-> ByteString | Data to send |
-> IO () |
Send data to the socket. The socket must be connected to a
remote socket. Unlike send
, 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.
Sending data to closed socket may lead to undefined behaviour.
:: Socket | Socket |
-> ByteString | Data to send |
-> SockAddr | Recipient address |
-> IO Int | Number of bytes sent |
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.
Sending data to closed socket may lead to undefined behaviour.
:: Socket | Socket |
-> ByteString | Data to send |
-> SockAddr | Recipient address |
-> IO () |
Send data to the socket. The recipient can be specified
explicitly, so the socket need not be in a connected state. Unlike
sendTo
, 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.
Sending data to closed socket may lead to undefined behaviour.
Vectored I/O
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
ByteString
s, xs
,
sendMany sock xs
is equivalent to
sendAll sock (concat xs)
but potentially more efficient.
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.
:: Socket | Connected socket |
-> [ByteString] | Data to send |
-> IO () |
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.
Sending data to closed socket may lead to undefined behaviour.
:: Socket | Socket |
-> [ByteString] | Data to send |
-> SockAddr | Recipient address |
-> IO () |
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.
Sending data to closed socket may lead to undefined behaviour.
Receive data from a socket
:: Socket | Connected socket |
-> Int | Maximum number of bytes to receive |
-> IO ByteString | Data received |
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.
Considering hardware and network realities, the maximum number of bytes to receive should be a small power of 2, e.g., 4096.
For TCP sockets, a zero length return value means the peer has closed its half side of the connection.
Receiving data from closed socket may lead to undefined behaviour.
:: Socket | Socket |
-> Int | Maximum number of bytes to receive |
-> IO (ByteString, SockAddr) | Data received and sender address |
Receive data from the socket. The socket need not be in a
connected state. Returns (bytes, address)
where bytes
is a
ByteString
representing the data received and address
is a
SockAddr
representing the address of the sending socket.
Receiving data from closed socket may lead to undefined behaviour.
Example
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.
-- 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
-- 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