| Copyright | (c) Johan Tibell 2007-2010 |
|---|---|
| License | BSD-style |
| Maintainer | johan.tibell@gmail.com |
| Stability | stable |
| Portability | portable |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Network.Socket.ByteString
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 ()
- sendManyWithFds :: Socket -> [ByteString] -> [Fd] -> 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
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.
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
ByteStrings, 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.
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.
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.
Arguments
| :: Socket | Socket |
| -> [ByteString] | Data to send |
| -> [Fd] | File descriptors |
| -> IO () |
Send data and file descriptors over a UNIX-domain socket in a single system call. This function does not work on Windows.
Receive data from a socket
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.
Currently, the recv family is blocked on Windows because a proper
IO manager is not implemented. To use with timeout
on Windows, use setSocketOption with
RecvTimeOut as well.
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
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).
Arguments
| :: Socket | Socket |
| -> Int | The maximum length of data to be received
If the total length is not large enough,
|
| -> Int | The buffer size for control messages.
If the length is not large enough,
|
| -> 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).