network-2.4.1.2: Low-level networking interface

Portability | portable
Stability | stable
Maintainer | johan.tibell@gmail.com
Safe Haskell | None

Network.Socket.ByteString

Contents

- Send data to a socket
  - Vectored I/O
- Receive data from a socket
- Example

Description

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

Synopsis

- 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

send

Arguments

:: 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.

sendAll

Arguments

:: 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.

sendTo

Arguments

:: 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.

sendAllTo

Arguments

:: 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.

## 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.

sendMany

Arguments

:: 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.

sendManyTo

Arguments

:: 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.

# Receive data from a socket

recv

Arguments

:: 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.

recvFrom

Arguments

:: 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.

# 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
            bindSocket sock (addrAddress serveraddr)
            listen sock 1
            (conn, _) <- accept sock
            talk conn
            sClose conn
            sClose 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
            sClose sock
            putStr "Received "
            C.putStrLn msg