Copyright	(c) Johan Tibell 2007-2010
License	BSD-style
Maintainer	johan.tibell@gmail.com
Stability	stable
Portability	portable
Safe Haskell	None
Language	Haskell2010

Network.Socket.ByteString

Contents

Send data to a socket
- Vectored I/O
Receive data from a socket
Advanced send and recv

Description

This module provides access to the BSD socket interface. For detailed documentation, consult your favorite POSIX socket reference. All functions communicate failures by converting the error number to an IOError .

This module is made to be imported with Network.Socket like so:

import Network.Socket
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 )
sendMsg :: Socket -> SockAddr -> [ ByteString ] -> [ Cmsg ] -> MsgFlag -> IO Int
recvMsg :: Socket -> Int -> Int -> MsgFlag -> IO ( SockAddr , ByteString , [ Cmsg ], MsgFlag )

Send data to a socket

send Source #

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

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 :: Socket -> ByteString -> SockAddr -> IO Int Source #

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 :: Socket -> ByteString -> SockAddr -> IO () Source #

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

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

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

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 :: Socket -> Int -> IO ( ByteString , SockAddr ) Source #

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.

Advanced send and recv

sendMsg Source #

Arguments

:: Socket	Socket
-> SockAddr	Destination address
-> [ ByteString ]	Data to be sent
-> [ Cmsg ]	Control messages
-> MsgFlag	Message flags
-> IO Int	The length actually sent

Send data to the socket using sendmsg(2).

recvMsg Source #

Arguments

:: Socket	Socket
-> Int	The maximum length of data to be received If the total length is not large enough, `MSG_TRUNC` is returned
-> Int	The buffer size for control messages. If the length is not large enough, `MSG_CTRUNC` is returned
-> MsgFlag	Message flags
-> IO ( SockAddr , ByteString , [ Cmsg ], MsgFlag )	Source address, received data, control messages and message flags

Receive data from the socket using recvmsg(2).