-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | An extensible socket library.
--   
--   This library is a minimal cross-platform interface for BSD style
--   networking.
@package socket
@version 0.8.0.1


module System.Socket.Protocol.Default
data Default
instance System.Socket.Internal.Socket.Protocol System.Socket.Protocol.Default.Default


module System.Socket.Protocol.UDP
data UDP
instance System.Socket.Internal.Socket.Protocol System.Socket.Protocol.UDP.UDP


module System.Socket.Type.Datagram
data Datagram
instance System.Socket.Internal.Socket.Type System.Socket.Type.Datagram.Datagram


module System.Socket.Type.Raw
data Raw
instance System.Socket.Internal.Socket.Type System.Socket.Type.Raw.Raw


module System.Socket.Type.SequentialPacket
data SequentialPacket
instance System.Socket.Internal.Socket.Type System.Socket.Type.SequentialPacket.SequentialPacket


module System.Socket.Protocol.TCP
data TCP

-- | If set to True, disable the Nagle's algorithm.
--   
--   <ul>
--   <li>Also know as <tt>TCP_NODELAY</tt>.</li>
--   </ul>
data NoDelay
NoDelay :: Bool -> NoDelay
instance GHC.Show.Show System.Socket.Protocol.TCP.NoDelay
instance GHC.Classes.Ord System.Socket.Protocol.TCP.NoDelay
instance GHC.Classes.Eq System.Socket.Protocol.TCP.NoDelay
instance System.Socket.Internal.Socket.Protocol System.Socket.Protocol.TCP.TCP
instance System.Socket.Internal.SocketOption.SocketOption System.Socket.Protocol.TCP.NoDelay


module System.Socket.Unsafe

-- | A generic socket type. Use <a>socket</a> to create a new socket.
--   
--   The socket is just an <a>MVar</a>-wrapped file descriptor. The
--   <a>Socket</a> constructor is exported trough the unsafe module in
--   order to make this library easily extensible, but it is usually not
--   necessary nor advised to work directly on the file descriptor. If you
--   do, the following rules must be obeyed:
--   
--   <ul>
--   <li>Make sure not to deadlock. Use <a>withMVar</a> or similar.</li>
--   <li>The lock <b>must not</b> be held during a blocking call. This
--   would make it impossible to send and receive simultaneously or to
--   close the socket.</li>
--   <li>The lock <b>must</b> be held when calling operations that use the
--   file descriptor. Otherwise the socket might get closed or even reused
--   by another thread/capability which might result in reading from or
--   writing on a totally different socket. This is a security
--   nightmare!</li>
--   <li>The socket is non-blocking and all the code relies on that
--   assumption. You need to use GHC's eventing mechanism primitives to
--   block until something happens. The former rules forbid to use
--   <a>threadWaitRead</a> as it does not separate between registering the
--   file descriptor (for which the lock <b>must</b> be held) and the
--   actual waiting (for which you must <b>not</b> hold the lock). Also see
--   <a>this</a> thread and read the library code to see how the problem is
--   currently circumvented.</li>
--   </ul>
newtype Socket f t p
Socket :: (MVar Fd) -> Socket f t p

-- | Like <a>send</a>, but using <a>Ptr</a> and length instead of a
--   <tt>ByteString</tt>.
--   
--   This function is <i>unsafe</i>. <tt>bufPtr</tt> must refer to a buffer
--   which size is at least <tt>bufSize</tt> bytes.
unsafeSend :: Socket a t p -> Ptr b -> CSize -> MessageFlags -> IO CInt

-- | Like <a>sendTo</a>, but using <a>Ptr</a> and length instead of a
--   <tt>ByteString</tt>.
--   
--   This function is <i>unsafe</i>. <tt>bufPtr</tt> must refer to a buffer
--   which size is at least <tt>bufSize</tt> bytes.
unsafeSendTo :: Socket f t p -> Ptr b -> CSize -> MessageFlags -> Ptr (SocketAddress f) -> CInt -> IO CInt

-- | Like <a>receive</a>, but using <a>Ptr</a> and length instead of a
--   <tt>ByteString</tt>.
--   
--   This function is <i>unsafe</i>. <tt>bufPtr</tt> must refer to a buffer
--   which size is at least <tt>bufSize</tt> bytes.
unsafeReceive :: Socket a t p -> Ptr b -> CSize -> MessageFlags -> IO CInt

-- | Like <a>receiveFrom</a>, but using <a>Ptr</a> and length instead of a
--   <tt>ByteString</tt>.
--   
--   This function is <i>unsafe</i>. <tt>bufPtr</tt> must refer to a buffer
--   which size is at least <tt>bufSize</tt> bytes.
unsafeReceiveFrom :: Socket f t p -> Ptr b -> CSize -> MessageFlags -> Ptr (SocketAddress f) -> Ptr CInt -> IO CInt
unsafeGetSocketOption :: Storable a => Socket f t p -> CInt -> CInt -> IO a
unsafeSetSocketOption :: Storable a => Socket f t p -> CInt -> CInt -> a -> IO ()
waitRead :: Socket f t p -> Int -> IO ()
waitWrite :: Socket f t p -> Int -> IO ()
waitConnected :: Socket f t p -> IO ()
tryWaitRetryLoop :: Socket f t p -> (Socket f t p -> Int -> IO ()) -> (Fd -> Ptr CInt -> IO CInt) -> IO CInt


module System.Socket.Family.Inet6

-- | The <a>Internet Protocol version 6</a>.
data Inet6

-- | To avoid errors with endianess it was decided to keep this type
--   abstract.
--   
--   Use <a>inet6AddressFromTuple</a> and <a>inet6AddressToTuple</a> for
--   constructing and deconstructing custom addresses.
--   
--   Hint: Use the <a>Storable</a> instance. It exposes it exactly as found
--   within an IP packet (big endian if you insist on interpreting it as a
--   number).
--   
--   Another hint: Use <a>getAddressInfo</a> for parsing and suppress
--   nameserver lookups:
--   
--   <pre>
--   &gt; getAddressInfo (Just "::1") Nothing aiNumericHost :: IO [AddressInfo SocketAddressInet6 Stream TCP]
--   [AddressInfo {
--      addressInfoFlags = AddressInfoFlags 4,
--      socketAddress    = SocketAddressInet6 {inet6Address = Inet6Address 0000:0000:0000:0000:0000:0000:0000:0001, inet6Port = Inet6Port 0, inet6FlowInfo = Inet6FlowInfo 0, inet6ScopeId = Inet6ScopeId 0},
--      canonicalName    = Nothing }]
--   </pre>
data Inet6Address
data Inet6Port
data Inet6FlowInfo
data Inet6ScopeId

-- | Constructs a custom <a>Inet6Address</a>.
--   
--   <pre>
--   inet6AddressFromTuple (0,0,0,0,0,0,0,1) == inet6Loopback
--   </pre>
inet6AddressFromTuple :: (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16) -> Inet6Address

-- | Deconstructs an <a>Inet6Address</a>.
inet6AddressToTuple :: Inet6Address -> (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16)

-- | <pre>
--   ::
--   </pre>
inet6Any :: Inet6Address

-- | <pre>
--   ::1
--   </pre>
inet6Loopback :: Inet6Address

-- | <pre>
--   IPV6_V6ONLY
--   </pre>
data V6Only
V6Only :: Bool -> V6Only
instance GHC.Show.Show System.Socket.Family.Inet6.V6Only
instance GHC.Classes.Ord System.Socket.Family.Inet6.V6Only
instance GHC.Classes.Eq System.Socket.Family.Inet6.V6Only
instance GHC.Num.Num System.Socket.Family.Inet6.Inet6ScopeId
instance GHC.Show.Show System.Socket.Family.Inet6.Inet6ScopeId
instance GHC.Classes.Ord System.Socket.Family.Inet6.Inet6ScopeId
instance GHC.Classes.Eq System.Socket.Family.Inet6.Inet6ScopeId
instance GHC.Num.Num System.Socket.Family.Inet6.Inet6FlowInfo
instance GHC.Show.Show System.Socket.Family.Inet6.Inet6FlowInfo
instance GHC.Classes.Ord System.Socket.Family.Inet6.Inet6FlowInfo
instance GHC.Classes.Eq System.Socket.Family.Inet6.Inet6FlowInfo
instance GHC.Num.Num System.Socket.Family.Inet6.Inet6Port
instance GHC.Show.Show System.Socket.Family.Inet6.Inet6Port
instance GHC.Classes.Ord System.Socket.Family.Inet6.Inet6Port
instance GHC.Classes.Eq System.Socket.Family.Inet6.Inet6Port
instance GHC.Classes.Eq System.Socket.Family.Inet6.Inet6Address
instance GHC.Show.Show (System.Socket.Internal.Socket.SocketAddress System.Socket.Family.Inet6.Inet6)
instance GHC.Classes.Eq (System.Socket.Internal.Socket.SocketAddress System.Socket.Family.Inet6.Inet6)
instance System.Socket.Internal.Socket.Family System.Socket.Family.Inet6.Inet6
instance GHC.Show.Show System.Socket.Family.Inet6.Inet6Address
instance Foreign.Storable.Storable System.Socket.Family.Inet6.Inet6Address
instance Foreign.Storable.Storable System.Socket.Family.Inet6.Inet6Port
instance Foreign.Storable.Storable System.Socket.Family.Inet6.Inet6FlowInfo
instance Foreign.Storable.Storable System.Socket.Family.Inet6.Inet6ScopeId
instance Foreign.Storable.Storable (System.Socket.Internal.Socket.SocketAddress System.Socket.Family.Inet6.Inet6)
instance System.Socket.Internal.SocketOption.SocketOption System.Socket.Family.Inet6.V6Only


module System.Socket.Family.Inet

-- | The <a>Internet Protocol version 4</a>.
data Inet

-- | To avoid errors with endianess it was decided to keep this type
--   abstract.
--   
--   Use <a>inetAddressFromTuple</a> and <a>inetAddressToTuple</a> for
--   constructing and deconstructing custom addresses.
--   
--   Hint: Use the <a>Storable</a> instance. It exposes it exactly as found
--   within an IP packet (big endian if you insist on interpreting it as a
--   number).
--   
--   Another hint: Use <a>getAddressInfo</a> for parsing and suppress
--   nameserver lookups:
--   
--   <pre>
--   &gt; getAddressInfo (Just "127.0.0.1") Nothing aiNumericHost :: IO [AddressInfo Inet Stream TCP]
--   [AddressInfo {addressInfoFlags = AddressInfoFlags 4, socketAddress = SocketAddressInet {inetAddress = InetAddress 127.0.0.1, inetPort = InetPort 0}, canonicalName = Nothing}]
--   </pre>
data InetAddress
data InetPort

-- | Constructs a custom <a>InetAddress</a>.
--   
--   <pre>
--   inetAddressFromTuple (127,0,0,1) == inetLoopback
--   </pre>
inetAddressFromTuple :: (Word8, Word8, Word8, Word8) -> InetAddress

-- | Deconstructs an <a>InetAddress</a>.
inetAddressToTuple :: InetAddress -> (Word8, Word8, Word8, Word8)

-- | <pre>
--   224.0.0.1
--   </pre>
inetAllHostsGroup :: InetAddress

-- | <pre>
--   0.0.0.0
--   </pre>
inetAny :: InetAddress

-- | <pre>
--   255.255.255.255
--   </pre>
inetBroadcast :: InetAddress

-- | <pre>
--   127.0.0.1
--   </pre>
inetLoopback :: InetAddress

-- | <pre>
--   224.0.0.255
--   </pre>
inetMaxLocalGroup :: InetAddress

-- | <pre>
--   255.255.255.255
--   </pre>
inetNone :: InetAddress

-- | <pre>
--   224.0.0.0
--   </pre>
inetUnspecificGroup :: InetAddress
instance GHC.Num.Num System.Socket.Family.Inet.InetPort
instance GHC.Show.Show System.Socket.Family.Inet.InetPort
instance GHC.Classes.Ord System.Socket.Family.Inet.InetPort
instance GHC.Classes.Eq System.Socket.Family.Inet.InetPort
instance GHC.Classes.Eq System.Socket.Family.Inet.InetAddress
instance GHC.Show.Show (System.Socket.Internal.Socket.SocketAddress System.Socket.Family.Inet.Inet)
instance GHC.Classes.Eq (System.Socket.Internal.Socket.SocketAddress System.Socket.Family.Inet.Inet)
instance System.Socket.Internal.Socket.Family System.Socket.Family.Inet.Inet
instance GHC.Show.Show System.Socket.Family.Inet.InetAddress
instance Foreign.Storable.Storable System.Socket.Family.Inet.InetPort
instance Foreign.Storable.Storable System.Socket.Family.Inet.InetAddress
instance Foreign.Storable.Storable (System.Socket.Internal.Socket.SocketAddress System.Socket.Family.Inet.Inet)


-- | <pre>
--   {-# LANGUAGE OverloadedStrings #-}
--   module Main where
--   
--   import Control.Exception ( bracket, catch )
--   import Control.Monad ( forever )
--   
--   import System.Socket
--   import System.Socket.Family.Inet6
--   import System.Socket.Type.Stream
--   import System.Socket.Protocol.TCP
--   
--   main :: IO ()
--   main = bracket
--     ( socket :: IO (Socket Inet6 Stream TCP) )
--     ( \s-&gt; do
--       close s
--       putStrLn "Listening socket closed."
--     )
--     ( \s-&gt; do
--       setSocketOption s (ReuseAddress True)
--       setSocketOption s (V6Only False)
--       bind s (SocketAddressInet6 inet6Any 8080 0 0)
--       listen s 5
--       putStrLn "Listening socket ready..."
--       forever $ acceptAndHandle s `catch` \e-&gt; print (e :: SocketException)
--     )
--   
--   acceptAndHandle :: Socket Inet6 Stream TCP -&gt; IO ()
--   acceptAndHandle s = bracket
--     ( accept s )
--     ( \(p, addr)-&gt; do
--       close p
--       putStrLn $ "Closed connection to " ++ show addr
--     )
--     ( \(p, addr)-&gt; do
--       putStrLn $ "Accepted connection from " ++ show addr
--       sendAll p "Hello world!" msgNoSignal
--     )
--   </pre>
module System.Socket

-- | A generic socket type. Use <a>socket</a> to create a new socket.
--   
--   The socket is just an <a>MVar</a>-wrapped file descriptor. The
--   <a>Socket</a> constructor is exported trough the unsafe module in
--   order to make this library easily extensible, but it is usually not
--   necessary nor advised to work directly on the file descriptor. If you
--   do, the following rules must be obeyed:
--   
--   <ul>
--   <li>Make sure not to deadlock. Use <a>withMVar</a> or similar.</li>
--   <li>The lock <b>must not</b> be held during a blocking call. This
--   would make it impossible to send and receive simultaneously or to
--   close the socket.</li>
--   <li>The lock <b>must</b> be held when calling operations that use the
--   file descriptor. Otherwise the socket might get closed or even reused
--   by another thread/capability which might result in reading from or
--   writing on a totally different socket. This is a security
--   nightmare!</li>
--   <li>The socket is non-blocking and all the code relies on that
--   assumption. You need to use GHC's eventing mechanism primitives to
--   block until something happens. The former rules forbid to use
--   <a>threadWaitRead</a> as it does not separate between registering the
--   file descriptor (for which the lock <b>must</b> be held) and the
--   actual waiting (for which you must <b>not</b> hold the lock). Also see
--   <a>this</a> thread and read the library code to see how the problem is
--   currently circumvented.</li>
--   </ul>
data Socket f t p

-- | The address <a>Family</a> determines the network protocol to use.
--   
--   The most common address families are <a>Inet</a> (IPv4) and
--   <a>Inet6</a> (IPv6).
class Storable (SocketAddress f) => Family f where data SocketAddress f where {
    data family SocketAddress f;
}

-- | The number designating this <a>Family</a> on the specific platform.
--   This method is only exported for implementing extension libraries.
--   
--   This function shall yield the values of constants like
--   <tt>AF_INET</tt>, <tt>AF_INET6</tt> etc.
familyNumber :: Family f => f -> CInt

-- | The <a>Type</a> determines properties of the transport layer and the
--   semantics of basic socket operations.
--   
--   The instances supplied by this library are <a>Raw</a> (no transport
--   layer), <a>Stream</a> (for unframed binary streams, e.g. <a>TCP</a>),
--   <a>Datagram</a> (for datagrams of limited length, e.g. <a>UDP</a>) and
--   <a>SequentialPacket</a> (for framed messages of arbitrary length, e.g.
--   <a>SCTP</a>).
class Type t

-- | This number designates this <a>Type</a> on the specific platform. This
--   method is only exported for implementing extension libraries.
--   
--   The function shall yield the values of constants like
--   <tt>SOCK_STREAM</tt>, <tt>SOCK_DGRAM</tt> etc.
typeNumber :: Type t => t -> CInt

-- | The <a>Protocol</a> determines the transport protocol to use.
--   
--   Use <a>Default</a> to let the operating system choose a transport
--   protocol compatible with the socket's <a>Type</a>.
class Protocol p

-- | This number designates this <a>Protocol</a> on the specific platform.
--   This method is only exported for implementing extension libraries.
--   
--   The function shall yield the values of constants like
--   <tt>IPPROTO_TCP</tt>, <tt>IPPROTO_UDP</tt> etc.
protocolNumber :: Protocol p => p -> CInt

-- | Creates a new socket.
--   
--   Whereas the underlying POSIX socket operation takes 3 parameters, this
--   library encodes this information in the type variables. This rules out
--   several kinds of errors and especially simplifies the handling of
--   addresses (by using associated data families). Examples:
--   
--   <pre>
--   -- create an IPv4-UDP-datagram socket
--   sock &lt;- socket :: IO (Socket Inet Datagram UDP)
--   -- create an IPv6-TCP-streaming socket
--   sock6 &lt;- socket :: IO (Socket Inet6 Stream TCP)
--   -- create an IPv6-streaming socket with default protocol (usually TCP)
--   sock6 &lt;- socket :: IO (Socket Inet6 Strem Default)
--   </pre>
--   
--   <ul>
--   <li>This operation sets up a finalizer that automatically closes the
--   socket when the garbage collection decides to collect it. This is just
--   a fail-safe. You might still run out of file descriptors as there's no
--   guarantee about when the finalizer is run. You're advised to manually
--   <a>close</a> the socket when it's no longer needed. If possible, use
--   <a>bracket</a> to reliably close the socket descriptor on exception or
--   regular termination of your computation:</li>
--   </ul>
--   
--   <pre>
--   result &lt;- bracket (socket :: IO (Socket Inet6 Stream TCP)) close $ \sock-&gt; do
--     somethingWith sock -- your computation here
--     return somethingelse
--   </pre>
--   
--   <ul>
--   <li>This operation configures the socket non-blocking to work
--   seamlessly with the runtime system's event notification
--   mechanism.</li>
--   <li>This operation can safely deal with asynchronous exceptions
--   without leaking file descriptors.</li>
--   <li>This operation throws <a>SocketException</a>s. Consult your
--   <tt>man socket</tt> for details and specific errors.</li>
--   </ul>
socket :: (Family f, Type t, Protocol p) => IO (Socket f t p)

-- | Connects to a remote address.
--   
--   <ul>
--   <li>This operation returns as soon as a connection has been
--   established (as if the socket were blocking). The connection attempt
--   has either failed or succeeded after this operation threw an exception
--   or returned.</li>
--   <li>The operation throws <a>SocketException</a>s. Calling
--   <a>connect</a> on a <a>close</a>d socket throws
--   <a>eBadFileDescriptor</a> even if the former file descriptor has been
--   reassigned.</li>
--   </ul>
connect :: (Family f) => Socket f t p -> SocketAddress f -> IO ()

-- | Bind a socket to an address.
--   
--   <ul>
--   <li>Calling <a>bind</a> on a <a>close</a>d socket throws
--   <a>eBadFileDescriptor</a> even if the former file descriptor has been
--   reassigned.</li>
--   <li>It is assumed that <a>bind</a> never blocks and therefore
--   <a>eInProgress</a>, <a>eAlready</a> and <a>eInterrupted</a> don't
--   occur. This assumption is supported by the fact that the Linux manpage
--   doesn't mention any of these errors, the Posix manpage doesn't mention
--   the last one and even MacOS' implementation will never fail with any
--   of these when the socket is configured non-blocking as <a>argued
--   here</a>.</li>
--   <li>This operation throws <a>SocketException</a>s. Consult your
--   <tt>man</tt> page for details and specific <tt>errno</tt>s.</li>
--   </ul>
bind :: (Family f) => Socket f t p -> SocketAddress f -> IO ()

-- | Starts listening and queueing connection requests on a connection-mode
--   socket. The second parameter determines the backlog size.
--   
--   <ul>
--   <li>Calling <a>listen</a> on a <a>close</a>d socket throws
--   <a>eBadFileDescriptor</a> even if the former file descriptor has been
--   reassigned.</li>
--   <li>The second parameter is called <i>backlog</i> and sets a limit on
--   how many unaccepted connections the transport implementation shall
--   queue. A value of <tt>0</tt> leaves the decision to the
--   implementation.</li>
--   <li>This operation throws <a>SocketException</a>s. Consult your
--   <tt>man listen</tt> for details and specific errors.</li>
--   </ul>
listen :: Socket f t p -> Int -> IO ()

-- | Accept a new connection.
--   
--   <ul>
--   <li>Calling <a>accept</a> on a <a>close</a>d socket throws
--   <a>eBadFileDescriptor</a> even if the former file descriptor has been
--   reassigned.</li>
--   <li>This operation configures the new socket non-blocking. It uses
--   <tt>accept4</tt> (when available) in order to accept and set the
--   socket non-blocking with a single system call.</li>
--   <li>This operation sets up a finalizer for the new socket that
--   automatically closes the new socket when the garbage collection
--   decides to collect it. This is just a fail-safe. You might still run
--   out of file descriptors as there's no guarantee about when the
--   finalizer is run. You're advised to manually <a>close</a> the socket
--   when it's no longer needed.</li>
--   <li>This operation throws <a>SocketException</a>s.</li>
--   <li>This operation catches <a>eAgain</a>, <a>eWouldBlock</a> and
--   <a>eInterrupted</a> internally and retries automatically.</li>
--   </ul>
accept :: (Family f) => Socket f t p -> IO (Socket f t p, SocketAddress f)

-- | Send data.
--   
--   <ul>
--   <li>Calling <a>send</a> on a <a>close</a>d socket throws
--   <a>eBadFileDescriptor</a> even if the former file descriptor has been
--   reassigned.</li>
--   <li>The operation returns the number of bytes sent. On <a>Datagram</a>
--   and <a>SequentialPacket</a> sockets certain assurances on atomicity
--   exist and <a>eAgain</a> or <a>eWouldBlock</a> are thrown until the
--   whole message would fit into the send buffer.</li>
--   <li>This operation throws <a>SocketException</a>s. Consult <tt>man
--   send</tt> for details and specific errors.</li>
--   <li><a>eAgain</a>, <a>eWouldBlock</a> and <a>eInterrupted</a> and
--   handled internally and won't be thrown. For performance reasons the
--   operation first tries a write on the socket and then waits when it got
--   <a>eAgain</a> or <a>eWouldBlock</a>.</li>
--   </ul>
send :: Socket f t p -> ByteString -> MessageFlags -> IO Int

-- | Like <a>send</a>, but allows to specify a destination address.
sendTo :: (Family f) => Socket f t p -> ByteString -> MessageFlags -> SocketAddress f -> IO Int

-- | Receive data.
--   
--   <ul>
--   <li>The operation takes a buffer size in bytes a first parameter which
--   limits the maximum length of the returned <a>ByteString</a>.</li>
--   <li>When an empty <a>ByteString</a> is returned this usally (protocol
--   specific) means that the peer gracefully closed the connection. The
--   user is advised to check for and handle this case.</li>
--   <li>Calling <a>receive</a> on a <a>close</a>d socket throws
--   <a>eBadFileDescriptor</a> even if the former file descriptor has been
--   reassigned.</li>
--   <li>This operation throws <a>SocketException</a>s. Consult <tt>man
--   recv</tt> for details and specific errors.</li>
--   <li><a>eAgain</a>, <a>eWouldBlock</a> and <a>eInterrupted</a> and
--   handled internally and won't be thrown. For performance reasons the
--   operation first tries a read on the socket and then waits when it got
--   <a>eAgain</a> or <a>eWouldBlock</a> until the socket is signaled to be
--   readable.</li>
--   </ul>
receive :: Socket f t p -> Int -> MessageFlags -> IO ByteString

-- | Like <a>receive</a>, but additionally yields the peer address.
receiveFrom :: (Family f) => Socket f t p -> Int -> MessageFlags -> IO (ByteString, SocketAddress f)

-- | Closes a socket.
--   
--   <ul>
--   <li>This operation is idempotent and thus can be performed more than
--   once without throwing an exception. If it throws an exception it is
--   presumably a not recoverable situation and the process should
--   exit.</li>
--   <li>This operation does not block.</li>
--   <li>This operation wakes up all threads that are currently blocking on
--   this socket. All other threads are guaranteed to not block on
--   operations on this socket in the future. Threads that perform
--   operations other than <a>close</a> on this socket will fail with
--   <a>eBadFileDescriptor</a> after the socket has been closed
--   (<a>close</a> replaces the <a>Fd</a> in the <a>MVar</a> with
--   <tt>-1</tt> to reliably avoid use-after-free situations).</li>
--   <li>This operation potentially throws <a>SocketException</a>s (only
--   <tt>EIO</tt> is documented). <a>eInterrupted</a> is catched internally
--   and retried automatically, so won't be thrown.</li>
--   </ul>
close :: Socket f t p -> IO ()

-- | <a>SocketOption</a>s allow to read and write certain properties of a
--   socket.
--   
--   <ul>
--   <li>Each option shall have a corresponding data type that models the
--   data associated with the socket option.</li>
--   <li>Use <a>unsafeGetSocketOption</a> and <a>unsafeSetSocketOption</a>
--   in order to implement custom socket options.</li>
--   </ul>
class SocketOption o

-- | Get a specific <a>SocketOption</a>.
--   
--   <ul>
--   <li>This operation throws <a>SocketException</a>s. Consult <tt>man
--   getsockopt</tt> for details and specific errors.</li>
--   </ul>
getSocketOption :: SocketOption o => Socket f t p -> IO o

-- | Set a specific <a>SocketOption</a>.
--   
--   <ul>
--   <li>This operation throws <a>SocketException</a>s. Consult <tt>man
--   setsockopt</tt> for details and specific errors.</li>
--   </ul>
setSocketOption :: SocketOption o => Socket f t p -> o -> IO ()

-- | Reports the last error that occured on the socket.
--   
--   <ul>
--   <li>Also known as <tt>SO_ERROR</tt>.</li>
--   <li>The operation <a>setSocketOption</a> always throws <a>eInvalid</a>
--   for this option.</li>
--   <li>Use with care in the presence of concurrency!</li>
--   </ul>
data Error
Error :: SocketException -> Error

-- | Allows or disallows the reuse of a local address in a <a>bind</a>
--   call.
--   
--   <ul>
--   <li>Also known as <tt>SO_REUSEADDR</tt>.</li>
--   <li>This is particularly useful when experiencing <a>eAddressInUse</a>
--   exceptions.</li>
--   </ul>
data ReuseAddress
ReuseAddress :: Bool -> ReuseAddress

-- | When enabled the protocol checks in a protocol-specific manner if the
--   other end is still alive.
--   
--   <ul>
--   <li>Also known as <tt>SO_KEEPALIVE</tt>.</li>
--   </ul>
data KeepAlive
KeepAlive :: Bool -> KeepAlive
data AddressInfo f t p
AddressInfo :: AddressInfoFlags -> SocketAddress f -> Maybe ByteString -> AddressInfo f t p
[addressInfoFlags] :: AddressInfo f t p -> AddressInfoFlags
[socketAddress] :: AddressInfo f t p -> SocketAddress f
[canonicalName] :: AddressInfo f t p -> Maybe ByteString

-- | This class is for address families that support name resolution.
class (Family f) => HasAddressInfo f

-- | Maps names to addresses (i.e. by DNS lookup).
--   
--   The operation throws <a>AddressInfoException</a>s.
--   
--   Contrary to the underlying <tt>getaddrinfo</tt> operation this wrapper
--   is typesafe and thus only returns records that match the address, type
--   and protocol encoded in the type. This is the price we have to pay for
--   typesafe sockets and extensibility.
--   
--   If you need different types of records, you need to start several
--   queries. If you want to connect to both IPv4 and IPV6 addresses use
--   <a>aiV4Mapped</a> and use IPv6-sockets.
--   
--   <pre>
--   getAddressInfo (Just "www.haskell.org") (Just "https") mempty :: IO [AddressInfo Inet Stream TCP]
--   &gt; [AddressInfo {addressInfoFlags = AddressInfoFlags 0, socketAddress = SocketAddressInet {inetAddress = InetAddress 162.242.239.16, inetPort = InetPort 443}, canonicalName = Nothing}]
--   </pre>
--   
--   <pre>
--   &gt; getAddressInfo (Just "www.haskell.org") (Just "80") aiV4Mapped :: IO [AddressInfo Inet6 Stream TCP]
--   [AddressInfo {
--      addressInfoFlags = AddressInfoFlags 8,
--      socketAddress    = SocketAddressInet6 {inet6Address = Inet6Address 2400:cb00:2048:0001:0000:0000:6ca2:cc3c, inet6Port = Inet6Port 80, inet6FlowInfo = Inet6FlowInfo 0, inet6ScopeId = Inet6ScopeId 0},
--      canonicalName    = Nothing }]
--   </pre>
--   
--   <pre>
--   &gt; getAddressInfo (Just "darcs.haskell.org") Nothing aiV4Mapped :: IO [AddressInfo Inet6 Stream TCP]
--   [AddressInfo {
--      addressInfoFlags = AddressInfoFlags 8,
--      socketAddress    = SocketAddressInet6 {inet6Address = Inet6Address 0000:0000:0000:0000:0000:ffff:17fd:e1ad, inet6Port = Inet6Port 0, inet6FlowInfo = Inet6FlowInfo 0, inet6ScopeId = Inet6ScopeId 0},
--      canonicalName    = Nothing }]
--   &gt; getAddressInfo (Just "darcs.haskell.org") Nothing mempty :: IO [AddressInfo Inet6 Stream TCP]
--   *** Exception: AddressInfoException "Name or service not known"
--   </pre>
getAddressInfo :: (HasAddressInfo f, Type t, Protocol p) => Maybe ByteString -> Maybe ByteString -> AddressInfoFlags -> IO [AddressInfo f t p]

-- | A <a>NameInfo</a> consists of host and service name.
data NameInfo
NameInfo :: ByteString -> ByteString -> NameInfo
[hostName] :: NameInfo -> ByteString
[serviceName] :: NameInfo -> ByteString

-- | This class is for address families that support reverse name
--   resolution.
class (Family f) => HasNameInfo f

-- | (Reverse-)map an address back to a human-readable host- and service
--   name.
--   
--   The operation throws <a>AddressInfoException</a>s.
--   
--   <pre>
--   &gt; getNameInfo (SocketAddressInet inetLoopback 80) mempty
--   NameInfo {hostName = "localhost.localdomain", serviceName = "http"}
--   </pre>
getNameInfo :: HasNameInfo f => SocketAddress f -> NameInfoFlags -> IO NameInfo

-- | Use the <a>Monoid</a> instance to combine several flags:
--   
--   <pre>
--   mconcat [msgNoSignal, msgWaitAll]
--   </pre>
--   
--   Use the <a>Bits</a> instance to check whether a flag is set:
--   
--   <pre>
--   if flags .&amp;. msgEndOfRecord /= mempty then ...
--   </pre>
newtype MessageFlags
MessageFlags :: CInt -> MessageFlags

-- | <pre>
--   MSG_EOR
--   </pre>
msgEndOfRecord :: MessageFlags

-- | <pre>
--   MSG_NOSIGNAL
--   </pre>
--   
--   Suppresses the generation of <tt>PIPE</tt> signals when writing to a
--   socket that is no longer connected.
--   
--   Although this flag is POSIX, it is not available on all platforms. Try
--   
--   <pre>
--   msgNoSignal /= mempty
--   </pre>
--   
--   in order to check whether this flag is defined on a certain platform.
--   It is safe to just use this constant even if it might not have effect
--   on a certain target platform. The platform independence of this flag
--   is therefore fulfilled to some extent.
--   
--   Some more explanation on the platform specific behaviour:
--   
--   <ul>
--   <li>Linux defines and supports <tt>MSG_NOSIGNAL</tt> and properly
--   suppresses the generation of broken pipe-related signals.</li>
--   <li>Windows does not define it, but does not generate signals
--   either.</li>
--   <li>OSX does not define it, but generates <tt>PIPE</tt> signals. The
--   GHC runtime ignores them if you don't hook them explicitly. The
--   non-portable socket option <tt>SO_NOSIGPIPE</tt> may be used disable
--   signals on a per-socket basis.</li>
--   </ul>
msgNoSignal :: MessageFlags

-- | <pre>
--   MSG_OOB
--   </pre>
msgOutOfBand :: MessageFlags

-- | <pre>
--   MSG_WAITALL
--   </pre>
msgWaitAll :: MessageFlags

-- | Use the <a>Monoid</a> instance to combine several flags:
--   
--   <pre>
--   mconcat [aiAddressConfig, aiV4Mapped]
--   </pre>
data AddressInfoFlags

-- | <tt>AI_ADDRCONFIG</tt>:
aiAddressConfig :: AddressInfoFlags

-- | <tt>AI_ALL</tt>: Return both IPv4 (as v4-mapped IPv6 address) and IPv6
--   addresses when <a>aiV4Mapped</a> is set independent of whether IPv6
--   addresses exist for this name.
aiAll :: AddressInfoFlags

-- | <tt>AI_CANONNAME</tt>:
aiCanonicalName :: AddressInfoFlags

-- | <tt>AI_NUMERICHOST</tt>:
aiNumericHost :: AddressInfoFlags

-- | <tt>AI_NUMERICSERV</tt>:
aiNumericService :: AddressInfoFlags

-- | <tt>AI_PASSIVE</tt>:
aiPassive :: AddressInfoFlags

-- | <tt>AI_V4MAPPED</tt>: Return mapped IPv4 addresses if no IPv6
--   addresses could be found or if <a>aiAll</a> flag is set.
aiV4Mapped :: AddressInfoFlags

-- | Use the <a>Monoid</a> instance to combine several flags:
--   
--   <pre>
--   mconcat [niNameRequired, niNoFullyQualifiedDomainName]
--   </pre>
data NameInfoFlags

-- | <tt>NI_NAMEREQD</tt>: Throw an exception if the hostname cannot be
--   determined.
niNameRequired :: NameInfoFlags

-- | <tt>NI_DGRAM</tt>: Service is datagram based (i.e. <a>UDP</a>) rather
--   than stream based (i.e. <a>TCP</a>).
niDatagram :: NameInfoFlags

-- | <tt>NI_NOFQDN</tt>: Return only the hostname part of the fully
--   qualified domain name for local hosts.
niNoFullyQualifiedDomainName :: NameInfoFlags

-- | <tt>NI_NUMERICHOST</tt>: Return the numeric form of the host address.
niNumericHost :: NameInfoFlags

-- | <tt>NI_NUMERICSERV</tt>: Return the numeric form of the service
--   address.
niNumericService :: NameInfoFlags

-- | Contains the error code that can be matched against.
--   
--   Hint: Use guards or <tt>MultiWayIf</tt> to match against specific
--   exceptions:
--   
--   <pre>
--   if | e == eAddressInUse -&gt; ...
--      | e == eAddressNotAvailable -&gt; ...
--      | otherwise -&gt; ...
--   </pre>
newtype SocketException
SocketException :: CInt -> SocketException

-- | <pre>
--   SocketException "No error"
--   </pre>
eOk :: SocketException

-- | <pre>
--   SocketException "Interrupted system call"
--   </pre>
--   
--   NOTE: This exception shall not be thrown by any public operation in
--   this library, but is handled internally.
eInterrupted :: SocketException

-- | <pre>
--   SocketException "Bad file descriptor"
--   </pre>
eBadFileDescriptor :: SocketException

-- | <pre>
--   SocketException "Invalid argument"
--   </pre>
eInvalid :: SocketException

-- | <pre>
--   SocketException "Broken pipe"
--   </pre>
ePipe :: SocketException

-- | <pre>
--   SocketException "Resource temporarily unavailable"
--   </pre>
--   
--   NOTE: This exception shall not be thrown by any public operation in
--   this library, but is handled internally.
eWouldBlock :: SocketException

-- | <pre>
--   SocketException "Resource temporarily unavailable"
--   </pre>
eAgain :: SocketException

-- | <pre>
--   SocketException "Socket operation on non-socket"
--   </pre>
--   
--   NOTE: This should be ruled out by the type system.
eNotSocket :: SocketException

-- | <pre>
--   SocketException "Destination address required"
--   </pre>
eDestinationAddressRequired :: SocketException

-- | <pre>
--   SocketException "Message too long"
--   </pre>
eMessageSize :: SocketException

-- | <pre>
--   SocketException "Protocol wrong type for socket"
--   </pre>
eProtocolType :: SocketException

-- | <pre>
--   SocketException "Protocol not available"
--   </pre>
eNoProtocolOption :: SocketException

-- | <pre>
--   SocketException "Protocol not supported"
--   </pre>
eProtocolNotSupported :: SocketException

-- | <pre>
--   SocketException "Socket type not supported"
--   </pre>
eSocketTypeNotSupported :: SocketException

-- | <pre>
--   SocketException "Operation not supported"
--   </pre>
eOperationNotSupported :: SocketException

-- | <pre>
--   SocketException "Protocol family not supported"
--   </pre>
eProtocolFamilyNotSupported :: SocketException

-- | <pre>
--   SocketException "Address family not supported by protocol"
--   </pre>
eAddressFamilyNotSupported :: SocketException

-- | <pre>
--   SocketException "Address already in use"
--   </pre>
eAddressInUse :: SocketException

-- | <pre>
--   SocketException "Cannot assign requested address"
--   </pre>
eAddressNotAvailable :: SocketException

-- | <pre>
--   SocketException "Network is down"
--   </pre>
eNetworkDown :: SocketException

-- | <pre>
--   SocketException "Network is unreachable"
--   </pre>
eNetworkUnreachable :: SocketException

-- | <pre>
--   SocketException "Network dropped connection on reset"
--   </pre>
eNetworkReset :: SocketException

-- | <pre>
--   SocketException "Software caused connection abort"
--   </pre>
eConnectionAborted :: SocketException

-- | <pre>
--   SocketException "Connection reset by peer"
--   </pre>
eConnectionReset :: SocketException

-- | <pre>
--   SocketException "No buffer space available"
--   </pre>
eNoBufferSpace :: SocketException

-- | <pre>
--   SocketException "Transport endpoint is already connected"
--   </pre>
eIsConnected :: SocketException

-- | <pre>
--   SocketException "Transport endpoint is not connected"
--   </pre>
eNotConnected :: SocketException

-- | <pre>
--   SocketException "Cannot send after transport endpoint shutdown"
--   </pre>
eShutdown :: SocketException

-- | <pre>
--   SocketException "Too many references: cannot splice"
--   </pre>
eTooManyReferences :: SocketException

-- | <pre>
--   SocketException "Connection timed out"
--   </pre>
eTimedOut :: SocketException

-- | <pre>
--   SocketException "Connection refused"
--   </pre>
eConnectionRefused :: SocketException

-- | <pre>
--   SocketException "Host is down"
--   </pre>
eHostDown :: SocketException

-- | <pre>
--   SocketException "No route to host"
--   </pre>
eHostUnreachable :: SocketException

-- | <pre>
--   SocketException "Operation already in progress"
--   </pre>
--   
--   NOTE: This exception shall not be thrown by any public operation in
--   this library, but is handled internally.
eAlready :: SocketException

-- | <pre>
--   SocketException "Operation now in progress"
--   </pre>
eInProgress :: SocketException

-- | Contains the error code that can be matched against.
--   
--   Hint: Use guards or <tt>MultiWayIf</tt> to match against specific
--   exceptions:
--   
--   <pre>
--   if | e == eaiFail -&gt; ...
--      | e == eaiNoName -&gt; ...
--      | otherwise -&gt; ...
--   </pre>
newtype AddressInfoException
AddressInfoException :: CInt -> AddressInfoException

-- | <pre>
--   AddressInfoException "Temporary failure in name resolution"
--   </pre>
eaiAgain :: AddressInfoException

-- | <pre>
--   AddressInfoException "Bad value for ai_flags"
--   </pre>
eaiBadFlags :: AddressInfoException

-- | <pre>
--   AddressInfoException "Non-recoverable failure in name resolution"
--   </pre>
eaiFail :: AddressInfoException

-- | <pre>
--   AddressInfoException "ai_family not supported"
--   </pre>
eaiFamily :: AddressInfoException

-- | <pre>
--   AddressInfoException "Memory allocation failure"
--   </pre>
eaiMemory :: AddressInfoException

-- | <pre>
--   AddressInfoException "No such host is known"
--   </pre>
eaiNoName :: AddressInfoException

-- | <pre>
--   AddressInfoException "ai_socktype not supported"
--   </pre>
eaiSocketType :: AddressInfoException

-- | <pre>
--   AddressInfoException "Servname not supported for ai_socktype"
--   </pre>
eaiService :: AddressInfoException

-- | <pre>
--   AddressInfoException "System error"
--   </pre>
eaiSystem :: AddressInfoException


module System.Socket.Type.Stream
data Stream

-- | Sends a whole <a>ByteString</a> with as many system calls as necessary
--   and returns the bytes sent (in this case just the <a>ByteString</a>s
--   <a>length</a>).
sendAll :: Socket f Stream p -> ByteString -> MessageFlags -> IO Int

-- | Like <a>sendAll</a>, but operates on lazy <a>ByteString</a>s.
--   
--   It uses <a>sendAll</a> internally to send all chunks sequentially. The
--   lock on the socket is acquired for each chunk separately, so the
--   socket can be read from in an interleaving fashion.
sendAllLazy :: Socket f Stream p -> ByteString -> MessageFlags -> IO Int64

-- | Sends a whole <a>Builder</a> without allocating <a>ByteString</a>s. If
--   performance is an issue, this operation should be preferred over all
--   other solutions for sending stream data.
--   
--   The operation <a>alloca</a>tes a single buffer of the given size on
--   entry and reuses this buffer until the whole <a>Builder</a> has been
--   sent. The count of all bytes sent is returned as there is no other
--   efficient way to determine a <a>Builder</a>s size without actually
--   building it.
sendAllBuilder :: Socket f Stream p -> Int -> Builder -> MessageFlags -> IO Int64

-- | Like <a>receive</a>, but operates on lazy <a>ByteString</a>s and
--   continues until either an empty part has been received (peer closed
--   the connection) or given buffer limit has been exceeded or an
--   exception occured.
--   
--   <ul>
--   <li>The <a>Int64</a> parameter is a soft limit on how many bytes to
--   receive. Collection is stopped if the limit has been exceeded. The
--   result might be up to one internal buffer size longer than the given
--   limit. If the returned <a>ByteString</a>s length is lower or eqal than
--   the limit, the data has not been truncated and the transmission is
--   complete.</li>
--   </ul>
receiveAll :: Socket f Stream p -> Int64 -> MessageFlags -> IO ByteString
instance System.Socket.Internal.Socket.Type System.Socket.Type.Stream.Stream
