-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Low-level networking interface
--
-- This package provides a low-level networking interface.
--
-- High-Level Packages
--
-- Other packages provide higher level interfaces:
--
--
-- - connection
-- - hookup
-- - network-simple
--
--
-- Extended Packages
--
-- network seeks to provide a cross-platform core for
-- networking. As such some APIs live in extended libraries. Packages in
-- the network ecosystem are often prefixed with
-- network-.
--
-- network-bsd
--
-- In network-3.0.0.0 the Network.BSD module was split
-- off into its own package, network-bsd-3.0.0.0.
--
-- network-uri
--
-- In network-2.6 the Network.URI module was split off
-- into its own package, network-uri-2.6. If you're using the
-- Network.URI module you can automatically get it from the
-- right package by adding this to your .cabal file:
--
--
-- library
-- build-depends: network-uri-flag
--
@package network
@version 3.1.2.1
-- | A module containing semi-public Network.Socket internals.
-- Modules which extend the Network.Socket module will need to use
-- this module while ideally most users will be able to make do with the
-- public interface.
module Network.Socket.Internal
-- | Throw an IOError corresponding to the current socket error.
throwSocketError :: String -> IO a
-- | Like throwSocketError, but the error code is supplied as an
-- argument.
--
-- On Windows, do not use errno. Use a system error code instead.
throwSocketErrorCode :: String -> CInt -> IO a
-- | Throw an IOError corresponding to the current socket error if
-- the IO action returns a result of -1. Discards the result of
-- the IO action after error handling.
throwSocketErrorIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO ()
-- | Throw an IOError corresponding to the current socket error if
-- the IO action returns a result of -1, but retries in case of
-- an interrupted operation.
throwSocketErrorIfMinus1Retry :: (Eq a, Num a) => String -> IO a -> IO a
-- | Throw an IOError corresponding to the current socket error if
-- the IO action returns a result of -1, but retries in case of
-- an interrupted operation. Discards the result of the IO action after
-- error handling.
throwSocketErrorIfMinus1Retry_ :: (Eq a, Num a) => String -> IO a -> IO ()
-- | Throw an IOError corresponding to the current socket error if
-- the IO action returns a result of -1, but retries in case of
-- an interrupted operation. Checks for operations that would block and
-- executes an alternative action before retrying in that case.
throwSocketErrorIfMinus1RetryMayBlock :: (Eq a, Num a) => String -> IO b -> IO a -> IO a
-- | Like throwSocketErrorIfMinus1Retry, but if the action fails
-- with EWOULDBLOCK or similar, wait for the socket to be
-- read-ready, and try again.
throwSocketErrorWaitRead :: (Eq a, Num a) => Socket -> String -> IO a -> IO a
-- | Like throwSocketErrorIfMinus1Retry, but if the action fails
-- with EWOULDBLOCK or similar, wait for the socket to be
-- read-ready, and try again. If it fails with the error the user was
-- expecting then ignore the error
throwSocketErrorWaitReadBut :: (Eq a, Num a) => (CInt -> Bool) -> Socket -> String -> IO a -> IO a
-- | Like throwSocketErrorIfMinus1Retry, but if the action fails
-- with EWOULDBLOCK or similar, wait for the socket to be
-- write-ready, and try again.
throwSocketErrorWaitWrite :: (Eq a, Num a) => Socket -> String -> IO a -> IO a
-- | With older versions of the network library (version 2.6.0.2
-- or earlier) on Windows operating systems, the networking subsystem
-- must be initialised using withSocketsDo before any networking
-- operations can be used. eg.
--
--
-- main = withSocketsDo $ do {...}
--
--
-- It is fine to nest calls to withSocketsDo, and to perform
-- networking operations after withSocketsDo has returned.
--
-- withSocketsDo is not necessary for the current network library.
-- However, for compatibility with older versions on Windows, it is good
-- practice to always call withSocketsDo (it's very cheap).
withSocketsDo :: IO a -> IO a
-- | Zero a structure.
zeroMemory :: Ptr a -> CSize -> IO ()
-- | 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
--
module Network.Socket.ByteString
-- | 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.
send :: Socket -> ByteString -> IO Int
-- | 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.
sendAll :: Socket -> ByteString -> IO ()
-- | 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.
sendTo :: Socket -> ByteString -> SockAddr -> IO Int
-- | 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.
sendAllTo :: Socket -> ByteString -> SockAddr -> 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.
sendMany :: Socket -> [ByteString] -> 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.
sendManyTo :: Socket -> [ByteString] -> SockAddr -> IO ()
-- | 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.
recv :: Socket -> Int -> IO ByteString
-- | 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.
recvFrom :: Socket -> Int -> IO (ByteString, SockAddr)
-- | Send data to the socket using sendmsg(2).
sendMsg :: Socket -> SockAddr -> [ByteString] -> [Cmsg] -> MsgFlag -> IO Int
-- | Receive data from the socket using recvmsg(2).
recvMsg :: Socket -> Int -> Int -> MsgFlag -> IO (SockAddr, ByteString, [Cmsg], MsgFlag)
-- | This module provides extensible APIs for socket addresses.
module Network.Socket.Address
-- | The core typeclass to unify socket addresses.
class SocketAddress sa
sizeOfSocketAddress :: SocketAddress sa => sa -> Int
peekSocketAddress :: SocketAddress sa => Ptr sa -> IO sa
pokeSocketAddress :: SocketAddress sa => Ptr a -> sa -> IO ()
-- | Getting peer's socket address.
getPeerName :: SocketAddress sa => Socket -> IO sa
-- | Getting my socket address.
getSocketName :: SocketAddress sa => Socket -> IO sa
-- | Connect to a remote socket at address.
connect :: SocketAddress sa => Socket -> sa -> IO ()
-- | Bind the socket to an address. The socket must not already be bound.
-- The Family passed to bind must be the same as that
-- passed to socket. If the special port number defaultPort
-- is passed then the system assigns the next available use port.
bind :: SocketAddress sa => Socket -> sa -> IO ()
-- | Accept a connection. The socket must be bound to an address and
-- listening for connections. The return value is a pair (conn,
-- address) where conn is a new socket object usable to
-- send and receive data on the connection, and address is the
-- address bound to the socket on the other end of the connection. On
-- Unix, FD_CLOEXEC is set to the new Socket.
accept :: SocketAddress sa => Socket -> IO (Socket, sa)
-- | 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.
sendTo :: SocketAddress sa => Socket -> ByteString -> sa -> IO Int
-- | 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.
sendAllTo :: SocketAddress sa => Socket -> ByteString -> sa -> IO ()
-- | 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.
--
-- If the first return value is zero, it means EOF.
recvFrom :: SocketAddress sa => Socket -> Int -> IO (ByteString, sa)
-- | 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.
sendBufTo :: SocketAddress sa => Socket -> Ptr a -> Int -> sa -> IO Int
-- | Receive data from the socket, writing it into buffer instead of
-- creating a new string. The socket need not be in a connected state.
-- Returns (nbytes, address) where nbytes is the number
-- of bytes received and address is a SockAddr
-- representing the address of the sending socket.
--
-- If the first return value is zero, it means EOF.
--
-- For Stream sockets, the second return value would be invalid.
--
-- NOTE: blocking on Windows unless you compile with -threaded (see GHC
-- ticket #1129)
recvBufFrom :: SocketAddress sa => Socket -> Ptr a -> Int -> IO (Int, sa)
-- | Send data to the socket using sendmsg(2).
sendBufMsg :: SocketAddress sa => Socket -> sa -> [(Ptr Word8, Int)] -> [Cmsg] -> MsgFlag -> IO Int
-- | Receive data from the socket using recvmsg(2). The supplied buffers
-- are filled in order, with subsequent buffers used only after all the
-- preceding buffers are full. If the message is short enough some of the
-- supplied buffers may remain unused.
recvBufMsg :: SocketAddress sa => Socket -> [(Ptr Word8, Int)] -> Int -> MsgFlag -> IO (sa, Int, [Cmsg], MsgFlag)
-- | This is the main module of the network package supposed to be used
-- with either Network.Socket.ByteString or
-- Network.Socket.ByteString.Lazy for sending/receiving.
--
-- Here are two minimal example programs using the TCP/IP protocol:
--
--
-- - a server that echoes all data that it receives back
-- - a client using it
--
--
--
-- -- Echo server program
-- module Main (main) where
--
-- import Control.Concurrent (forkFinally)
-- import qualified Control.Exception as E
-- import Control.Monad (unless, forever, void)
-- import qualified Data.ByteString as S
-- import Network.Socket
-- import Network.Socket.ByteString (recv, sendAll)
--
-- main :: IO ()
-- main = runTCPServer Nothing "3000" talk
-- where
-- talk s = do
-- msg <- recv s 1024
-- unless (S.null msg) $ do
-- sendAll s msg
-- talk s
--
-- -- from the "network-run" package.
-- runTCPServer :: Maybe HostName -> ServiceName -> (Socket -> IO a) -> IO a
-- runTCPServer mhost port server = withSocketsDo $ do
-- addr <- resolve
-- E.bracket (open addr) close loop
-- where
-- resolve = do
-- let hints = defaultHints {
-- addrFlags = [AI_PASSIVE]
-- , addrSocketType = Stream
-- }
-- head <$> getAddrInfo (Just hints) mhost (Just port)
-- open addr = E.bracketOnError (openSocket addr) close $ \sock -> do
-- setSocketOption sock ReuseAddr 1
-- withFdSocket sock setCloseOnExecIfNeeded
-- bind sock $ addrAddress addr
-- listen sock 1024
-- return sock
-- loop sock = forever $ E.bracketOnError (accept sock) (close . fst)
-- $ \(conn, _peer) -> void $
-- -- 'forkFinally' alone is unlikely to fail thus leaking @conn@,
-- -- but 'E.bracketOnError' above will be necessary if some
-- -- non-atomic setups (e.g. spawning a subprocess to handle
-- -- @conn@) before proper cleanup of @conn@ is your case
-- forkFinally (server conn) (const $ gracefulClose conn 5000)
--
--
--
-- {-# LANGUAGE OverloadedStrings #-}
-- -- Echo client program
-- module Main (main) where
--
-- import qualified Control.Exception as E
-- import qualified Data.ByteString.Char8 as C
-- import Network.Socket
-- import Network.Socket.ByteString (recv, sendAll)
--
-- main :: IO ()
-- main = runTCPClient "127.0.0.1" "3000" $ \s -> do
-- sendAll s "Hello, world!"
-- msg <- recv s 1024
-- putStr "Received: "
-- C.putStrLn msg
--
-- -- from the "network-run" package.
-- runTCPClient :: HostName -> ServiceName -> (Socket -> IO a) -> IO a
-- runTCPClient host port client = withSocketsDo $ do
-- addr <- resolve
-- E.bracket (open addr) close client
-- where
-- resolve = do
-- let hints = defaultHints { addrSocketType = Stream }
-- head <$> getAddrInfo (Just hints) (Just host) (Just port)
-- open addr = E.bracketOnError (openSocket addr) close $ \sock -> do
-- connect sock $ addrAddress addr
-- return sock
--
--
-- The proper programming model is that one Socket is handled by a
-- single thread. If multiple threads use one Socket concurrently,
-- unexpected things would happen. There is one exception for multiple
-- threads vs a single Socket: one thread reads data from a
-- Socket only and the other thread writes data to the
-- Socket only.
module Network.Socket
-- | With older versions of the network library (version 2.6.0.2
-- or earlier) on Windows operating systems, the networking subsystem
-- must be initialised using withSocketsDo before any networking
-- operations can be used. eg.
--
--
-- main = withSocketsDo $ do {...}
--
--
-- It is fine to nest calls to withSocketsDo, and to perform
-- networking operations after withSocketsDo has returned.
--
-- withSocketsDo is not necessary for the current network library.
-- However, for compatibility with older versions on Windows, it is good
-- practice to always call withSocketsDo (it's very cheap).
withSocketsDo :: IO a -> IO a
-- | Resolve a host or service name to one or more addresses. The
-- AddrInfo values that this function returns contain
-- SockAddr values that you can pass directly to connect or
-- bind.
--
-- This function is protocol independent. It can return both IPv4 and
-- IPv6 address information.
--
-- The AddrInfo argument specifies the preferred query behaviour,
-- socket options, or protocol. You can override these conveniently using
-- Haskell's record update syntax on defaultHints, for example as
-- follows:
--
--
-- >>> let hints = defaultHints { addrFlags = [AI_NUMERICHOST], addrSocketType = Stream }
--
--
-- You must provide a Just value for at least one of the
-- HostName or ServiceName arguments. HostName can
-- be either a numeric network address (dotted quad for IPv4,
-- colon-separated hex for IPv6) or a hostname. In the latter case, its
-- addresses will be looked up unless AI_NUMERICHOST is specified
-- as a hint. If you do not provide a HostName value and do
-- not set AI_PASSIVE as a hint, network addresses in the result
-- will contain the address of the loopback interface.
--
-- If the query fails, this function throws an IO exception instead of
-- returning an empty list. Otherwise, it returns a non-empty list of
-- AddrInfo values.
--
-- There are several reasons why a query might result in several values.
-- For example, the queried-for host could be multihomed, or the service
-- might be available via several protocols.
--
-- Note: the order of arguments is slightly different to that defined for
-- getaddrinfo in RFC 2553. The AddrInfo parameter comes
-- first to make partial application easier.
--
--
-- >>> addr:_ <- getAddrInfo (Just hints) (Just "127.0.0.1") (Just "http")
--
-- >>> addrAddress addr
-- 127.0.0.1:80
--
getAddrInfo :: Maybe AddrInfo -> Maybe HostName -> Maybe ServiceName -> IO [AddrInfo]
-- | Either a host name e.g., "haskell.org" or a numeric host
-- address string consisting of a dotted decimal IPv4 address or an IPv6
-- address e.g., "192.168.0.1".
type HostName = String
-- | Either a service name e.g., "http" or a numeric port number.
type ServiceName = String
data AddrInfo
AddrInfo :: [AddrInfoFlag] -> Family -> SocketType -> ProtocolNumber -> SockAddr -> Maybe String -> AddrInfo
[addrFlags] :: AddrInfo -> [AddrInfoFlag]
[addrFamily] :: AddrInfo -> Family
[addrSocketType] :: AddrInfo -> SocketType
[addrProtocol] :: AddrInfo -> ProtocolNumber
[addrAddress] :: AddrInfo -> SockAddr
[addrCanonName] :: AddrInfo -> Maybe String
-- | Default hints for address lookup with getAddrInfo.
--
--
-- >>> addrFlags defaultHints
-- []
--
-- >>> addrFamily defaultHints
-- AF_UNSPEC
--
-- >>> addrSocketType defaultHints
-- NoSocketType
--
-- >>> addrProtocol defaultHints
-- 0
--
defaultHints :: AddrInfo
-- | Flags that control the querying behaviour of getAddrInfo. For
-- more information, see
-- https://tools.ietf.org/html/rfc3493#page-25
data AddrInfoFlag
-- | The list of returned AddrInfo values will only contain IPv4
-- addresses if the local system has at least one IPv4 interface
-- configured, and likewise for IPv6. (Only some platforms support this.)
AI_ADDRCONFIG :: AddrInfoFlag
-- | If AI_ALL is specified, return all matching IPv6 and IPv4
-- addresses. Otherwise, this flag has no effect. (Only some platforms
-- support this.)
AI_ALL :: AddrInfoFlag
-- | The addrCanonName field of the first returned AddrInfo
-- will contain the "canonical name" of the host.
AI_CANONNAME :: AddrInfoFlag
-- | The HostName argument must be a numeric address in
-- string form, and network name lookups will not be attempted.
AI_NUMERICHOST :: AddrInfoFlag
-- | The ServiceName argument must be a port number in string
-- form, and service name lookups will not be attempted. (Only some
-- platforms support this.)
AI_NUMERICSERV :: AddrInfoFlag
-- | If no HostName value is provided, the network address in each
-- SockAddr will be left as a "wild card". This is useful for
-- server applications that will accept connections from any client.
AI_PASSIVE :: AddrInfoFlag
-- | If an IPv6 lookup is performed, and no IPv6 addresses are found,
-- IPv6-mapped IPv4 addresses will be returned. (Only some platforms
-- support this.)
AI_V4MAPPED :: AddrInfoFlag
-- | Indicate whether the given AddrInfoFlag will have any effect on
-- this system.
addrInfoFlagImplemented :: AddrInfoFlag -> Bool
-- | Connect to a remote socket at address.
connect :: Socket -> SockAddr -> IO ()
-- | Bind the socket to an address. The socket must not already be bound.
-- The Family passed to bind must be the same as that
-- passed to socket. If the special port number
-- defaultPort is passed then the system assigns the next
-- available use port.
bind :: Socket -> SockAddr -> IO ()
-- | Listen for connections made to the socket. The second argument
-- specifies the maximum number of queued connections and should be at
-- least 1; the maximum value is system-dependent (usually 5).
listen :: Socket -> Int -> IO ()
-- | Accept a connection. The socket must be bound to an address and
-- listening for connections. The return value is a pair (conn,
-- address) where conn is a new socket object usable to
-- send and receive data on the connection, and address is the
-- address bound to the socket on the other end of the connection. On
-- Unix, FD_CLOEXEC is set to the new Socket.
accept :: Socket -> IO (Socket, SockAddr)
-- | Close the socket. This function does not throw exceptions even if the
-- underlying system call returns errors.
--
-- If multiple threads use the same socket and one uses
-- unsafeFdSocket and the other use close, unexpected
-- behavior may happen. For more information, please refer to the
-- documentation of unsafeFdSocket.
close :: Socket -> IO ()
-- | Close the socket. This function throws exceptions if the underlying
-- system call returns errors.
close' :: Socket -> IO ()
-- | Closing a socket gracefully. This sends TCP FIN and check if TCP FIN
-- is received from the peer. The second argument is time out to receive
-- TCP FIN in millisecond. In both normal cases and error cases, socket
-- is deallocated finally.
--
-- Since: 3.1.1.0
gracefulClose :: Socket -> Int -> IO ()
-- | Shut down one or both halves of the connection, depending on the
-- second argument to the function. If the second argument is
-- ShutdownReceive, further receives are disallowed. If it is
-- ShutdownSend, further sends are disallowed. If it is
-- ShutdownBoth, further sends and receives are disallowed.
shutdown :: Socket -> ShutdownCmd -> IO ()
data ShutdownCmd
ShutdownReceive :: ShutdownCmd
ShutdownSend :: ShutdownCmd
ShutdownBoth :: ShutdownCmd
-- | Socket options for use with setSocketOption and
-- getSocketOption.
--
-- The existence of a constructor does not imply that the relevant option
-- is supported on your system: see isSupportedSocketOption
data SocketOption
SockOpt :: !CInt -> !CInt -> SocketOption
pattern UnsupportedSocketOption :: SocketOption
-- | SO_DEBUG
pattern Debug :: SocketOption
-- | SO_REUSEADDR
pattern ReuseAddr :: SocketOption
-- | SO_DOMAIN, read-only
pattern SoDomain :: SocketOption
-- | SO_TYPE, read-only
pattern Type :: SocketOption
-- | SO_PROTOCOL, read-only
pattern SoProtocol :: SocketOption
-- | SO_ERROR
pattern SoError :: SocketOption
-- | SO_DONTROUTE
pattern DontRoute :: SocketOption
-- | SO_BROADCAST
pattern Broadcast :: SocketOption
-- | SO_SNDBUF
pattern SendBuffer :: SocketOption
-- | SO_RCVBUF
pattern RecvBuffer :: SocketOption
-- | SO_KEEPALIVE
pattern KeepAlive :: SocketOption
-- | SO_OOBINLINE
pattern OOBInline :: SocketOption
-- | IP_TTL
pattern TimeToLive :: SocketOption
-- | TCP_MAXSEG
pattern MaxSegment :: SocketOption
-- | TCP_NODELAY
pattern NoDelay :: SocketOption
-- | TCP_CORK
pattern Cork :: SocketOption
-- | SO_LINGER: timeout in seconds, 0 means disabling/disabled.
pattern Linger :: SocketOption
-- | SO_REUSEPORT
pattern ReusePort :: SocketOption
-- | SO_RCVLOWAT
pattern RecvLowWater :: SocketOption
-- | SO_SNDLOWAT
pattern SendLowWater :: SocketOption
-- | SO_RCVTIMEO: this does not work at this moment.
pattern RecvTimeOut :: SocketOption
-- | SO_SNDTIMEO: this does not work at this moment.
pattern SendTimeOut :: SocketOption
-- | SO_USELOOPBACK
pattern UseLoopBack :: SocketOption
-- | TCP_USER_TIMEOUT
pattern UserTimeout :: SocketOption
-- | IPV6_V6ONLY: don't use this on OpenBSD.
pattern IPv6Only :: SocketOption
-- | Receiving IPv4 TTL.
pattern RecvIPv4TTL :: SocketOption
-- | Receiving IPv4 TOS.
pattern RecvIPv4TOS :: SocketOption
-- | Receiving IP_PKTINFO (struct in_pktinfo).
pattern RecvIPv4PktInfo :: SocketOption
-- | Receiving IPv6 hop limit.
pattern RecvIPv6HopLimit :: SocketOption
-- | Receiving IPv6 traffic class.
pattern RecvIPv6TClass :: SocketOption
-- | Receiving IPV6_PKTINFO (struct in6_pktinfo).
pattern RecvIPv6PktInfo :: SocketOption
-- | Does the SocketOption exist on this system?
isSupportedSocketOption :: SocketOption -> Bool
-- | Execute the given action only when the specified socket option is
-- supported. Any return value is ignored.
whenSupported :: SocketOption -> IO a -> IO ()
-- | Get a socket option that gives an Int value. There is currently no API
-- to get e.g. the timeval socket options
getSocketOption :: Socket -> SocketOption -> IO Int
-- | Set a socket option that expects an Int value. There is currently no
-- API to set e.g. the timeval socket options
setSocketOption :: Socket -> SocketOption -> Int -> IO ()
-- | Get a socket option.
getSockOpt :: forall a. Storable a => Socket -> SocketOption -> IO a
-- | Set a socket option.
setSockOpt :: Storable a => Socket -> SocketOption -> a -> IO ()
-- | Basic type for a socket.
data Socket
-- | Create a new socket using the given address family, socket type and
-- protocol number. The address family is usually AF_INET,
-- AF_INET6, or AF_UNIX. The socket type is usually
-- Stream or Datagram. The protocol number is usually
-- defaultProtocol. If AF_INET6 is used and the socket type
-- is Stream or Datagram, the IPv6Only socket option
-- is set to 0 so that both IPv4 and IPv6 can be handled with one socket.
--
--
-- >>> import Network.Socket
--
-- >>> let hints = defaultHints { addrFlags = [AI_NUMERICHOST, AI_NUMERICSERV], addrSocketType = Stream }
--
-- >>> addr:_ <- getAddrInfo (Just hints) (Just "127.0.0.1") (Just "5000")
--
-- >>> sock <- socket (addrFamily addr) (addrSocketType addr) (addrProtocol addr)
--
-- >>> Network.Socket.bind sock (addrAddress addr)
--
-- >>> getSocketName sock
-- 127.0.0.1:5000
--
socket :: Family -> SocketType -> ProtocolNumber -> IO Socket
-- | A utility function to open a socket with AddrInfo. This is a
-- just wrapper for the following code:
--
--
-- \addr -> socket (addrFamily addr) (addrSocketType addr) (addrProtocol addr)
--
openSocket :: AddrInfo -> IO Socket
-- | Get a file descriptor from a Socket. The socket will never be
-- closed automatically before withFdSocket completes, but it
-- may still be closed by an explicit call to close or
-- close`, either before or during the call.
--
-- The file descriptor must not be used after withFdSocket
-- returns, because the Socket may have been garbage-collected,
-- invalidating the file descriptor.
--
-- Since: 3.1.0.0
withFdSocket :: Socket -> (CInt -> IO r) -> IO r
-- | Getting a file descriptor from a socket.
--
-- If a Socket is shared with multiple threads and one uses
-- unsafeFdSocket, unexpected issues may happen. Consider the
-- following scenario:
--
-- 1) Thread A acquires a Fd from Socket by
-- unsafeFdSocket.
--
-- 2) Thread B close the Socket.
--
-- 3) Thread C opens a new Socket. Unfortunately it gets the same
-- Fd number which thread A is holding.
--
-- In this case, it is safer for Thread A to clone Fd by
-- dup. But this would still suffer from a race condition between
-- unsafeFdSocket and close.
--
-- If you use this function, you need to guarantee that the Socket
-- does not get garbage-collected until after you finish using the file
-- descriptor. touchSocket can be used for this purpose.
--
-- A safer option is to use withFdSocket instead.
unsafeFdSocket :: Socket -> IO CInt
-- | Ensure that the given Socket stays alive (i.e. not
-- garbage-collected) at the given place in the sequence of IO actions.
-- This function can be used in conjunction with unsafeFdSocket to
-- guarantee that the file descriptor is not prematurely freed.
--
--
-- fd <- unsafeFdSocket sock
-- -- using fd with blocking operations such as accept(2)
-- touchSocket sock
--
touchSocket :: Socket -> IO ()
-- | Socket is closed and a duplicated file descriptor is returned. The
-- duplicated descriptor is no longer subject to the possibility of
-- unexpectedly being closed if the socket is finalized. It is now the
-- caller's responsibility to ultimately close the duplicated file
-- descriptor.
socketToFd :: Socket -> IO CInt
-- | Currently, this is an alias of unsafeFdSocket.
-- | Deprecated: Use withFdSocket or unsafeFdSocket instead
fdSocket :: Socket -> IO CInt
-- | Creating a socket from a file descriptor.
mkSocket :: CInt -> IO Socket
-- | Turns a Socket into an Handle. By default, the new handle is
-- unbuffered. Use hSetBuffering to change the buffering.
--
-- Note that since a Handle is automatically closed by a finalizer
-- when it is no longer referenced, you should avoid doing any more
-- operations on the Socket after calling socketToHandle.
-- To close the Socket after socketToHandle, call
-- hClose on the Handle.
--
-- Caveat Handle is not recommended for network programming in
-- Haskell, e.g. merely performing hClose on a TCP socket won't
-- cooperate with peer's gracefulClose, i.e. proper shutdown
-- sequence with appropriate handshakes specified by the protocol.
socketToHandle :: Socket -> IOMode -> IO Handle
-- | Socket Types.
--
-- Some of the defined patterns may be unsupported on some systems: see
-- isSupportedSocketType.
data SocketType
-- | Pattern for a general socket type.
pattern GeneralSocketType :: CInt -> SocketType
-- | Unsupported socket type, equal to any other types not supported on
-- this system.
pattern UnsupportedSocketType :: SocketType
-- | Used in getAddrInfo hints, for example.
pattern NoSocketType :: SocketType
pattern Stream :: SocketType
pattern Datagram :: SocketType
pattern Raw :: SocketType
pattern RDM :: SocketType
pattern SeqPacket :: SocketType
-- | Is the SOCK_xxxxx constant corresponding to the given
-- SocketType known on this system? GeneralSocketType values, not
-- equal to any of the named patterns or UnsupportedSocketType,
-- will return True even when not known on this system.
isSupportedSocketType :: SocketType -> Bool
-- | Get the SocketType of an active socket.
--
-- Since: 3.0.1.0
getSocketType :: Socket -> IO SocketType
-- | Address families. The AF_xxxxx constants are widely used as
-- synonyms for the corresponding PF_xxxxx protocol family
-- values, to which they are numerically equal in mainstream socket API
-- implementations.
--
-- Stictly correct usage would be to pass the PF_xxxxx constants
-- as the first argument when creating a Socket, while the
-- AF_xxxxx constants should be used as addrFamily
-- values with getAddrInfo. For now only the AF_xxxxx
-- constants are provided.
--
-- Some of the defined patterns may be unsupported on some systems: see
-- isSupportedFamily.
data Family
-- | Pattern for a general protocol family (a.k.a. address family).
pattern GeneralFamily :: CInt -> Family
-- | Unsupported address family, equal to any other families that are not
-- supported on the system.
pattern UnsupportedFamily :: Family
-- | unspecified
pattern AF_UNSPEC :: Family
-- | UNIX-domain
pattern AF_UNIX :: Family
-- | Internet Protocol version 4
pattern AF_INET :: Family
-- | Internet Protocol version 6
pattern AF_INET6 :: Family
-- | Arpanet imp addresses
pattern AF_IMPLINK :: Family
-- | pup protocols: e.g. BSP
pattern AF_PUP :: Family
-- | mit CHAOS protocols
pattern AF_CHAOS :: Family
-- | XEROX NS protocols
pattern AF_NS :: Family
-- | nbs protocols
pattern AF_NBS :: Family
-- | european computer manufacturers
pattern AF_ECMA :: Family
-- | datakit protocols
pattern AF_DATAKIT :: Family
-- | CCITT protocols, X.25 etc
pattern AF_CCITT :: Family
-- | IBM SNA
pattern AF_SNA :: Family
-- | DECnet
pattern AF_DECnet :: Family
-- | Direct data link interface
pattern AF_DLI :: Family
-- | LAT
pattern AF_LAT :: Family
-- | NSC Hyperchannel
pattern AF_HYLINK :: Family
-- | Apple Talk
pattern AF_APPLETALK :: Family
-- | Internal Routing Protocol (aka AF_NETLINK)
pattern AF_ROUTE :: Family
-- | NetBios-style addresses
pattern AF_NETBIOS :: Family
-- | Network Interface Tap
pattern AF_NIT :: Family
-- | IEEE 802.2, also ISO 8802
pattern AF_802 :: Family
-- | ISO protocols
pattern AF_ISO :: Family
-- | umbrella of all families used by OSI
pattern AF_OSI :: Family
-- | DNA Network Management
pattern AF_NETMAN :: Family
-- | CCITT X.25
pattern AF_X25 :: Family
-- | AX25
pattern AF_AX25 :: Family
-- | AFI
pattern AF_OSINET :: Family
-- | US Government OSI
pattern AF_GOSSIP :: Family
-- | Novell Internet Protocol
pattern AF_IPX :: Family
-- | eXpress Transfer Protocol (no AF)
pattern Pseudo_AF_XTP :: Family
-- | Common Trace Facility
pattern AF_CTF :: Family
-- | Wide Area Network protocols
pattern AF_WAN :: Family
-- | SGI Data Link for DLPI
pattern AF_SDL :: Family
-- | Netware
pattern AF_NETWARE :: Family
-- | NDD
pattern AF_NDD :: Family
-- | Debugging use only
pattern AF_INTF :: Family
-- | connection-oriented IP, aka ST II
pattern AF_COIP :: Family
-- | Computer Network Technology
pattern AF_CNT :: Family
-- | Help Identify RTIP packets
pattern Pseudo_AF_RTIP :: Family
-- | Help Identify PIP packets
pattern Pseudo_AF_PIP :: Family
-- | Simple Internet Protocol
pattern AF_SIP :: Family
-- | Integrated Services Digital Network
pattern AF_ISDN :: Family
-- | Internal key-management function
pattern Pseudo_AF_KEY :: Family
-- | native ATM access
pattern AF_NATM :: Family
-- | ARP (RFC 826)
pattern AF_ARP :: Family
-- | Used by BPF to not rewrite hdrs in iface output
pattern Pseudo_AF_HDRCMPLT :: Family
-- | ENCAP
pattern AF_ENCAP :: Family
-- | Link layer interface
pattern AF_LINK :: Family
-- | Link layer interface
pattern AF_RAW :: Family
-- | raw interface
pattern AF_RIF :: Family
-- | Amateur radio NetROM
pattern AF_NETROM :: Family
-- | multiprotocol bridge
pattern AF_BRIDGE :: Family
-- | ATM PVCs
pattern AF_ATMPVC :: Family
-- | Amateur Radio X.25 PLP
pattern AF_ROSE :: Family
-- | Netbeui 802.2LLC
pattern AF_NETBEUI :: Family
-- | Security callback pseudo AF
pattern AF_SECURITY :: Family
-- | Packet family
pattern AF_PACKET :: Family
-- | Ash
pattern AF_ASH :: Family
-- | Acorn Econet
pattern AF_ECONET :: Family
-- | ATM SVCs
pattern AF_ATMSVC :: Family
-- | IRDA sockets
pattern AF_IRDA :: Family
-- | PPPoX sockets
pattern AF_PPPOX :: Family
-- | Wanpipe API sockets
pattern AF_WANPIPE :: Family
-- | bluetooth sockets
pattern AF_BLUETOOTH :: Family
-- | Controller Area Network
pattern AF_CAN :: Family
-- | Does one of the AF_ constants correspond to a known address family on
-- this system. GeneralFamily values, not equal to any of the
-- named AF_xxxxx patterns or UnsupportedFamily, will
-- return True even when not known on this system.
isSupportedFamily :: Family -> Bool
packFamily :: Family -> CInt
-- | Convert CInt to Family.
unpackFamily :: CInt -> Family
-- | Protocol number.
type ProtocolNumber = CInt
-- | This is the default protocol for a given service.
--
--
-- >>> defaultProtocol
-- 0
--
defaultProtocol :: ProtocolNumber
-- | Socket addresses. The existence of a constructor does not necessarily
-- imply that that socket address type is supported on your system: see
-- isSupportedSockAddr.
data SockAddr
SockAddrInet :: !PortNumber -> !HostAddress -> SockAddr
SockAddrInet6 :: !PortNumber -> !FlowInfo -> !HostAddress6 -> !ScopeID -> SockAddr
-- | The path must have fewer than 104 characters. All of these characters
-- must have code points less than 256.
SockAddrUnix :: String -> SockAddr
-- | Is the socket address type supported on this system?
isSupportedSockAddr :: SockAddr -> Bool
-- | Getting peer's SockAddr.
getPeerName :: Socket -> IO SockAddr
-- | Getting my SockAddr.
getSocketName :: Socket -> IO SockAddr
-- | The raw network byte order number is read using host byte order.
-- Therefore on little-endian architectures the byte order is swapped.
-- For example 127.0.0.1 is represented as 0x0100007f
-- on little-endian hosts and as 0x7f000001 on big-endian hosts.
--
-- For direct manipulation prefer hostAddressToTuple and
-- tupleToHostAddress.
type HostAddress = Word32
-- | Converts HostAddress to representation-independent IPv4
-- quadruple. For example for 127.0.0.1 the function will return
-- (0x7f, 0, 0, 1) regardless of host endianness.
hostAddressToTuple :: HostAddress -> (Word8, Word8, Word8, Word8)
-- | Converts IPv4 quadruple to HostAddress.
tupleToHostAddress :: (Word8, Word8, Word8, Word8) -> HostAddress
-- | Independent of endianness. For example ::1 is stored as
-- (0, 0, 0, 1).
--
-- For direct manipulation prefer hostAddress6ToTuple and
-- tupleToHostAddress6.
type HostAddress6 = (Word32, Word32, Word32, Word32)
-- | Converts HostAddress6 to representation-independent IPv6
-- octuple.
hostAddress6ToTuple :: HostAddress6 -> (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16)
-- | Converts IPv6 octuple to HostAddress6.
tupleToHostAddress6 :: (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16) -> HostAddress6
-- | Flow information.
type FlowInfo = Word32
-- | Scope identifier.
type ScopeID = Word32
-- | Returns the index corresponding to the interface name.
--
-- Since 2.7.0.0.
ifNameToIndex :: String -> IO (Maybe Int)
-- | Returns the interface name corresponding to the index.
--
-- Since 2.7.0.0.
ifIndexToName :: Int -> IO (Maybe String)
-- | Port number. Use the Num instance (i.e. use a literal) to
-- create a PortNumber value.
--
--
-- >>> 1 :: PortNumber
-- 1
--
-- >>> read "1" :: PortNumber
-- 1
--
-- >>> show (12345 :: PortNumber)
-- "12345"
--
-- >>> 50000 < (51000 :: PortNumber)
-- True
--
-- >>> 50000 < (52000 :: PortNumber)
-- True
--
-- >>> 50000 + (10000 :: PortNumber)
-- 60000
--
data PortNumber
-- | Default port number.
--
--
-- >>> defaultPort
-- 0
--
defaultPort :: PortNumber
-- | Getting the port of socket.
socketPortSafe :: Socket -> IO (Maybe PortNumber)
-- | Getting the port of socket. IOError is thrown if a port is not
-- available.
socketPort :: Socket -> IO PortNumber
-- | Whether or not UNIX-domain sockets are available.
--
-- Since 2.7.0.0.
isUnixDomainSocketAvailable :: Bool
-- | Build a pair of connected socket objects. For portability, use this
-- function in the case where isUnixDomainSocketAvailable is
-- True and specify AF_UNIX to the first argument.
socketPair :: Family -> SocketType -> ProtocolNumber -> IO (Socket, Socket)
-- | Send a file descriptor over a UNIX-domain socket. Use this function in
-- the case where isUnixDomainSocketAvailable is True.
sendFd :: Socket -> CInt -> IO ()
-- | Receive a file descriptor over a UNIX-domain socket. Note that the
-- resulting file descriptor may have to be put into non-blocking mode in
-- order to be used safely. See setNonBlockIfNeeded. Use this
-- function in the case where isUnixDomainSocketAvailable is
-- True.
recvFd :: Socket -> IO CInt
-- | Getting process ID, user ID and group ID for UNIX-domain sockets.
--
-- This is implemented with SO_PEERCRED on Linux and getpeereid() on BSD
-- variants. Unfortunately, on some BSD variants getpeereid() returns
-- unexpected results, rather than an error, for AF_INET sockets. It is
-- the user's responsibility to make sure that the socket is a
-- UNIX-domain socket. Also, on some BSD variants, getpeereid() does not
-- return credentials for sockets created via socketPair, only
-- separately created and then explicitly connected UNIX-domain sockets
-- work on such systems.
--
-- Since 2.7.0.0.
getPeerCredential :: Socket -> IO (Maybe CUInt, Maybe CUInt, Maybe CUInt)
-- | Resolve an address to a host or service name. This function is
-- protocol independent. The list of NameInfoFlag values controls
-- query behaviour.
--
-- If a host or service's name cannot be looked up, then the numeric form
-- of the address or service will be returned.
--
-- If the query fails, this function throws an IO exception.
--
--
-- >>> addr:_ <- getAddrInfo (Just defaultHints) (Just "127.0.0.1") (Just "http")
--
-- >>> getNameInfo [NI_NUMERICHOST, NI_NUMERICSERV] True True $ addrAddress addr
-- (Just "127.0.0.1",Just "80")
--
getNameInfo :: [NameInfoFlag] -> Bool -> Bool -> SockAddr -> IO (Maybe HostName, Maybe ServiceName)
-- | Flags that control the querying behaviour of getNameInfo. For
-- more information, see
-- https://tools.ietf.org/html/rfc3493#page-30
data NameInfoFlag
-- | Resolve a datagram-based service name. This is required only for the
-- few protocols that have different port numbers for their
-- datagram-based versions than for their stream-based versions.
NI_DGRAM :: NameInfoFlag
-- | If the hostname cannot be looked up, an IO error is thrown.
NI_NAMEREQD :: NameInfoFlag
-- | If a host is local, return only the hostname part of the FQDN.
NI_NOFQDN :: NameInfoFlag
-- | The name of the host is not looked up. Instead, a numeric
-- representation of the host's address is returned. For an IPv4 address,
-- this will be a dotted-quad string. For IPv6, it will be
-- colon-separated hexadecimal.
NI_NUMERICHOST :: NameInfoFlag
-- | The name of the service is not looked up. Instead, a numeric
-- representation of the service is returned.
NI_NUMERICSERV :: NameInfoFlag
-- | Set the close_on_exec flag on Unix. On Windows, nothing is done.
--
-- Since 2.7.0.0.
setCloseOnExecIfNeeded :: CInt -> IO ()
-- | Get the close_on_exec flag. On Windows, this function always returns
-- False.
--
-- Since 2.7.0.0.
getCloseOnExec :: CInt -> IO Bool
-- | Set the nonblocking flag on Unix. On Windows, nothing is done.
setNonBlockIfNeeded :: CInt -> IO ()
-- | Get the nonblocking flag. On Windows, this function always returns
-- False.
--
-- Since 2.7.0.0.
getNonBlock :: CInt -> IO Bool
-- | 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.
sendBuf :: Socket -> Ptr Word8 -> Int -> IO Int
-- | 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.
--
-- The return value is the length of received data. Zero means EOF.
-- Historical note: Version 2.8.x.y or earlier, an EOF error was thrown.
-- This was changed in version 3.0.
recvBuf :: Socket -> Ptr Word8 -> Int -> IO Int
-- | 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.
sendBufTo :: Socket -> Ptr a -> Int -> SockAddr -> IO Int
-- | Receive data from the socket, writing it into buffer instead of
-- creating a new string. The socket need not be in a connected state.
-- Returns (nbytes, address) where nbytes is the number
-- of bytes received and address is a SockAddr
-- representing the address of the sending socket.
--
-- If the first return value is zero, it means EOF.
--
-- For Stream sockets, the second return value would be invalid.
--
-- NOTE: blocking on Windows unless you compile with -threaded (see GHC
-- ticket #1129)
recvBufFrom :: Socket -> Ptr a -> Int -> IO (Int, SockAddr)
-- | Send data to the socket using sendmsg(2).
sendBufMsg :: Socket -> SockAddr -> [(Ptr Word8, Int)] -> [Cmsg] -> MsgFlag -> IO Int
-- | Receive data from the socket using recvmsg(2).
recvBufMsg :: Socket -> [(Ptr Word8, Int)] -> Int -> MsgFlag -> IO (SockAddr, Int, [Cmsg], MsgFlag)
-- | Message flags. To combine flags, use (<>).
data MsgFlag
-- | Send or receive OOB(out-of-bound) data.
pattern MSG_OOB :: MsgFlag
-- | Bypass routing table lookup.
pattern MSG_DONTROUTE :: MsgFlag
-- | Peek at incoming message without removing it from the queue.
pattern MSG_PEEK :: MsgFlag
-- | End of record.
pattern MSG_EOR :: MsgFlag
-- | Received data is truncated. More data exist.
pattern MSG_TRUNC :: MsgFlag
-- | Received control message is truncated. More control message exist.
pattern MSG_CTRUNC :: MsgFlag
-- | Wait until the requested number of bytes have been read.
pattern MSG_WAITALL :: MsgFlag
-- | Control message (ancillary data) including a pair of level and type.
data Cmsg
Cmsg :: !CmsgId -> !ByteString -> Cmsg
[cmsgId] :: Cmsg -> !CmsgId
[cmsgData] :: Cmsg -> !ByteString
-- | Identifier of control message (ancillary data).
data CmsgId
CmsgId :: !CInt -> !CInt -> CmsgId
-- | The identifier for IPv4TTL.
pattern CmsgIdIPv4TTL :: CmsgId
-- | The identifier for IPv6HopLimit.
pattern CmsgIdIPv6HopLimit :: CmsgId
-- | The identifier for IPv4TOS.
pattern CmsgIdIPv4TOS :: CmsgId
-- | The identifier for IPv6TClass.
pattern CmsgIdIPv6TClass :: CmsgId
-- | The identifier for IPv4PktInfo.
pattern CmsgIdIPv4PktInfo :: CmsgId
-- | The identifier for IPv6PktInfo.
pattern CmsgIdIPv6PktInfo :: CmsgId
-- | The identifier for Fd.
pattern CmsgIdFd :: CmsgId
-- | Unsupported identifier
pattern UnsupportedCmsgId :: CmsgId
-- | Locate a control message of the given type in a list of control
-- messages. The following shows an example usage:
--
--
-- (lookupCmsg CmsgIdIPv4TOS cmsgs >>= decodeCmsg) :: Maybe IPv4TOS
--
lookupCmsg :: CmsgId -> [Cmsg] -> Maybe Cmsg
-- | Filtering control message.
filterCmsg :: CmsgId -> [Cmsg] -> [Cmsg]
decodeCmsg :: forall a. (ControlMessage a, Storable a) => Cmsg -> Maybe a
encodeCmsg :: forall a. ControlMessage a => a -> Cmsg
-- | Control message type class. Each control message type has a numeric
-- CmsgId and a Storable data representation.
class Storable a => ControlMessage a
controlMessageId :: ControlMessage a => CmsgId
-- | Time to live of IPv4.
newtype IPv4TTL
IPv4TTL :: CInt -> IPv4TTL
-- | Hop limit of IPv6.
newtype IPv6HopLimit
IPv6HopLimit :: CInt -> IPv6HopLimit
-- | TOS of IPv4.
newtype IPv4TOS
IPv4TOS :: CChar -> IPv4TOS
-- | Traffic class of IPv6.
newtype IPv6TClass
IPv6TClass :: CInt -> IPv6TClass
-- | Network interface ID and local IPv4 address.
data IPv4PktInfo
IPv4PktInfo :: Int -> HostAddress -> HostAddress -> IPv4PktInfo
-- | Network interface ID and local IPv4 address.
data IPv6PktInfo
IPv6PktInfo :: Int -> HostAddress6 -> IPv6PktInfo
-- | This is the value of SOMAXCONN, typically 128. 128 is good enough for
-- normal network servers but is too small for high performance servers.
maxListenQueue :: Int
-- | 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.Lazy
-- import Prelude hiding (getContents)
--
module Network.Socket.ByteString.Lazy
send :: Socket -> ByteString -> IO Int64
sendAll :: Socket -> ByteString -> IO ()
-- | Receive data from the socket. The socket must be in a connected state.
-- Data is received on demand, in chunks; each chunk will be sized to
-- reflect the amount of data received by individual recv calls.
--
-- All remaining data from the socket is consumed. When there is no more
-- data to be received, the receiving side of the socket is shut down. If
-- there is an error and an exception is thrown, the socket is not shut
-- down.
getContents :: Socket -> IO ByteString
-- | Receive data from the socket. The socket must be in a connected state.
-- This function may return fewer bytes than specified. If the received
-- data is longer than the specified length, it may be discarded
-- depending on the type of socket. This function may block until a
-- message arrives.
--
-- If there is no more data to be received, returns an empty
-- ByteString.
recv :: Socket -> Int64 -> IO ByteString