socket-0.8.0.1: An extensible socket library.

Copyright(c) Lars Petersen 2015
LicenseMIT
Maintainerinfo@lars-petersen.net
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

System.Socket

Contents

Description

{-# 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-> do
    close s
    putStrLn "Listening socket closed."
  )
  ( \s-> 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-> print (e :: SocketException)
  )

acceptAndHandle :: Socket Inet6 Stream TCP -> IO ()
acceptAndHandle s = bracket
  ( accept s )
  ( \(p, addr)-> do
    close p
    putStrLn $ "Closed connection to " ++ show addr
  )
  ( \(p, addr)-> do
    putStrLn $ "Accepted connection from " ++ show addr
    sendAll p "Hello world!" msgNoSignal
  )

Synopsis

Socket

data Socket f t p #

A generic socket type. Use socket to create a new socket.

The socket is just an MVar-wrapped file descriptor. The Socket 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:

  • Make sure not to deadlock. Use withMVar or similar.
  • The lock must not be held during a blocking call. This would make it impossible to send and receive simultaneously or to close the socket.
  • The lock must 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!
  • 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 threadWaitRead as it does not separate between registering the file descriptor (for which the lock must be held) and the actual waiting (for which you must not hold the lock). Also see this thread and read the library code to see how the problem is currently circumvented.

Family

class Storable (SocketAddress f) => Family f where #

The address Family determines the network protocol to use.

The most common address families are Inet (IPv4) and Inet6 (IPv6).

Minimal complete definition

familyNumber

Associated Types

data SocketAddress f #

The SocketAddress type is a data family. This allows to provide different data constructors depending on the socket family without knowing all of them in advance or the need to extend this core library.

SocketAddressInet  inetLoopback  8080     :: SocketAddress Inet
SocketAddressInet6 inet6Loopback 8080 0 0 :: SocketAddress Inet6

Methods

familyNumber :: f -> CInt #

The number designating this Family on the specific platform. This method is only exported for implementing extension libraries.

This function shall yield the values of constants like AF_INET, AF_INET6 etc.

Instances

Family Inet6 # 

Associated Types

data SocketAddress Inet6 :: * #

Methods

familyNumber :: Inet6 -> CInt #

Family Inet # 

Associated Types

data SocketAddress Inet :: * #

Methods

familyNumber :: Inet -> CInt #

Type

class Type t where #

The Type determines properties of the transport layer and the semantics of basic socket operations.

The instances supplied by this library are Raw (no transport layer), Stream (for unframed binary streams, e.g. TCP), Datagram (for datagrams of limited length, e.g. UDP) and SequentialPacket (for framed messages of arbitrary length, e.g. SCTP).

Minimal complete definition

typeNumber

Methods

typeNumber :: t -> CInt #

This number designates this Type on the specific platform. This method is only exported for implementing extension libraries.

The function shall yield the values of constants like SOCK_STREAM, SOCK_DGRAM etc.

Protocol

class Protocol p where #

The Protocol determines the transport protocol to use.

Use Default to let the operating system choose a transport protocol compatible with the socket's Type.

Minimal complete definition

protocolNumber

Methods

protocolNumber :: p -> CInt #

This number designates this Protocol on the specific platform. This method is only exported for implementing extension libraries.

The function shall yield the values of constants like IPPROTO_TCP, IPPROTO_UDP etc.

Operations

socket

socket :: (Family f, Type t, Protocol p) => IO (Socket f t p) #

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:

-- create an IPv4-UDP-datagram socket
sock <- socket :: IO (Socket Inet Datagram UDP)
-- create an IPv6-TCP-streaming socket
sock6 <- socket :: IO (Socket Inet6 Stream TCP)
-- create an IPv6-streaming socket with default protocol (usually TCP)
sock6 <- socket :: IO (Socket Inet6 Strem Default)
  • 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 close the socket when it's no longer needed. If possible, use bracket to reliably close the socket descriptor on exception or regular termination of your computation:
result <- bracket (socket :: IO (Socket Inet6 Stream TCP)) close $ \sock-> do
  somethingWith sock -- your computation here
  return somethingelse
  • This operation configures the socket non-blocking to work seamlessly with the runtime system's event notification mechanism.
  • This operation can safely deal with asynchronous exceptions without leaking file descriptors.
  • This operation throws SocketExceptions. Consult your man socket for details and specific errors.

connect

connect :: Family f => Socket f t p -> SocketAddress f -> IO () #

Connects to a remote address.

  • 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.
  • The operation throws SocketExceptions. Calling connect on a closed socket throws eBadFileDescriptor even if the former file descriptor has been reassigned.

bind

bind :: Family f => Socket f t p -> SocketAddress f -> IO () #

Bind a socket to an address.

  • Calling bind on a closed socket throws eBadFileDescriptor even if the former file descriptor has been reassigned.
  • It is assumed that bind never blocks and therefore eInProgress, eAlready and eInterrupted 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 argued here.
  • This operation throws SocketExceptions. Consult your man page for details and specific errnos.

listen

listen :: Socket f t p -> Int -> IO () #

Starts listening and queueing connection requests on a connection-mode socket. The second parameter determines the backlog size.

  • Calling listen on a closed socket throws eBadFileDescriptor even if the former file descriptor has been reassigned.
  • The second parameter is called backlog and sets a limit on how many unaccepted connections the transport implementation shall queue. A value of 0 leaves the decision to the implementation.
  • This operation throws SocketExceptions. Consult your man listen for details and specific errors.

accept

accept :: Family f => Socket f t p -> IO (Socket f t p, SocketAddress f) #

Accept a new connection.

  • Calling accept on a closed socket throws eBadFileDescriptor even if the former file descriptor has been reassigned.
  • This operation configures the new socket non-blocking. It uses accept4 (when available) in order to accept and set the socket non-blocking with a single system call.
  • 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 close the socket when it's no longer needed.
  • This operation throws SocketExceptions.
  • This operation catches eAgain, eWouldBlock and eInterrupted internally and retries automatically.

send, sendTo

send :: Socket f t p -> ByteString -> MessageFlags -> IO Int #

Send data.

sendTo :: Family f => Socket f t p -> ByteString -> MessageFlags -> SocketAddress f -> IO Int #

Like send, but allows to specify a destination address.

receive, receiveFrom

receive :: Socket f t p -> Int -> MessageFlags -> IO ByteString #

Receive data.

  • The operation takes a buffer size in bytes a first parameter which limits the maximum length of the returned ByteString.
  • When an empty ByteString 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.
  • Calling receive on a closed socket throws eBadFileDescriptor even if the former file descriptor has been reassigned.
  • This operation throws SocketExceptions. Consult man recv for details and specific errors.
  • eAgain, eWouldBlock and eInterrupted 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 eAgain or eWouldBlock until the socket is signaled to be readable.

receiveFrom :: Family f => Socket f t p -> Int -> MessageFlags -> IO (ByteString, SocketAddress f) #

Like receive, but additionally yields the peer address.

close

close :: Socket f t p -> IO () #

Closes a socket.

  • 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.
  • This operation does not block.
  • 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 close on this socket will fail with eBadFileDescriptor after the socket has been closed (close replaces the Fd in the MVar with -1 to reliably avoid use-after-free situations).
  • This operation potentially throws SocketExceptions (only EIO is documented). eInterrupted is catched internally and retried automatically, so won't be thrown.

Options

class SocketOption o where #

SocketOptions allow to read and write certain properties of a socket.

Minimal complete definition

getSocketOption, setSocketOption

Methods

getSocketOption :: Socket f t p -> IO o #

Get a specific SocketOption.

  • This operation throws SocketExceptions. Consult man getsockopt for details and specific errors.

setSocketOption :: Socket f t p -> o -> IO () #

Set a specific SocketOption.

  • This operation throws SocketExceptions. Consult man setsockopt for details and specific errors.

Error

data Error #

Reports the last error that occured on the socket.

  • Also known as SO_ERROR.
  • The operation setSocketOption always throws eInvalid for this option.
  • Use with care in the presence of concurrency!

Constructors

Error SocketException 

Instances

Eq Error # 

Methods

(==) :: Error -> Error -> Bool #

(/=) :: Error -> Error -> Bool #

Ord Error # 

Methods

compare :: Error -> Error -> Ordering #

(<) :: Error -> Error -> Bool #

(<=) :: Error -> Error -> Bool #

(>) :: Error -> Error -> Bool #

(>=) :: Error -> Error -> Bool #

max :: Error -> Error -> Error #

min :: Error -> Error -> Error #

Show Error # 

Methods

showsPrec :: Int -> Error -> ShowS #

show :: Error -> String #

showList :: [Error] -> ShowS #

SocketOption Error # 

Methods

getSocketOption :: Socket f t p -> IO Error #

setSocketOption :: Socket f t p -> Error -> IO () #

ReuseAddress

data ReuseAddress #

Allows or disallows the reuse of a local address in a bind call.

  • Also known as SO_REUSEADDR.
  • This is particularly useful when experiencing eAddressInUse exceptions.

Constructors

ReuseAddress Bool 

KeepAlive

data KeepAlive #

When enabled the protocol checks in a protocol-specific manner if the other end is still alive.

  • Also known as SO_KEEPALIVE.

Constructors

KeepAlive Bool 

Name Resolution

getAddressInfo

data AddressInfo f t p #

Instances

Eq (SocketAddress f) => Eq (AddressInfo f t p) # 

Methods

(==) :: AddressInfo f t p -> AddressInfo f t p -> Bool #

(/=) :: AddressInfo f t p -> AddressInfo f t p -> Bool #

Show (SocketAddress f) => Show (AddressInfo f t p) # 

Methods

showsPrec :: Int -> AddressInfo f t p -> ShowS #

show :: AddressInfo f t p -> String #

showList :: [AddressInfo f t p] -> ShowS #

class Family f => HasAddressInfo f where #

This class is for address families that support name resolution.

Minimal complete definition

getAddressInfo

Methods

getAddressInfo :: (Type t, Protocol p) => Maybe ByteString -> Maybe ByteString -> AddressInfoFlags -> IO [AddressInfo f t p] #

Maps names to addresses (i.e. by DNS lookup).

The operation throws AddressInfoExceptions.

Contrary to the underlying getaddrinfo 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 aiV4Mapped and use IPv6-sockets.

getAddressInfo (Just "www.haskell.org") (Just "https") mempty :: IO [AddressInfo Inet Stream TCP]
> [AddressInfo {addressInfoFlags = AddressInfoFlags 0, socketAddress = SocketAddressInet {inetAddress = InetAddress 162.242.239.16, inetPort = InetPort 443}, canonicalName = Nothing}]
> 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 }]
> 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 }]
> getAddressInfo (Just "darcs.haskell.org") Nothing mempty :: IO [AddressInfo Inet6 Stream TCP]
*** Exception: AddressInfoException "Name or service not known"

getNameInfo

data NameInfo #

A NameInfo consists of host and service name.

Constructors

NameInfo 

class Family f => HasNameInfo f where #

This class is for address families that support reverse name resolution.

Minimal complete definition

getNameInfo

Methods

getNameInfo :: SocketAddress f -> NameInfoFlags -> IO NameInfo #

(Reverse-)map an address back to a human-readable host- and service name.

The operation throws AddressInfoExceptions.

> getNameInfo (SocketAddressInet inetLoopback 80) mempty
NameInfo {hostName = "localhost.localdomain", serviceName = "http"}

Flags

MessageFlags

newtype MessageFlags #

Use the Monoid instance to combine several flags:

mconcat [msgNoSignal, msgWaitAll]

Use the Bits instance to check whether a flag is set:

if flags .&. msgEndOfRecord /= mempty then ...

Constructors

MessageFlags CInt 

Instances

Eq MessageFlags # 
Show MessageFlags # 
Monoid MessageFlags # 
Storable MessageFlags # 
Bits MessageFlags # 

msgNoSignal :: MessageFlags #

MSG_NOSIGNAL

Suppresses the generation of PIPE signals when writing to a socket that is no longer connected.

Although this flag is POSIX, it is not available on all platforms. Try

msgNoSignal /= mempty

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:

  • Linux defines and supports MSG_NOSIGNAL and properly suppresses the generation of broken pipe-related signals.
  • Windows does not define it, but does not generate signals either.
  • OSX does not define it, but generates PIPE signals. The GHC runtime ignores them if you don't hook them explicitly. The non-portable socket option SO_NOSIGPIPE may be used disable signals on a per-socket basis.

msgWaitAll :: MessageFlags #

MSG_WAITALL

AddressInfoFlags

data AddressInfoFlags #

Use the Monoid instance to combine several flags:

mconcat [aiAddressConfig, aiV4Mapped]

Instances

Eq AddressInfoFlags # 
Show AddressInfoFlags # 
Monoid AddressInfoFlags # 
Bits AddressInfoFlags # 

aiAll :: AddressInfoFlags #

AI_ALL: Return both IPv4 (as v4-mapped IPv6 address) and IPv6 addresses when aiV4Mapped is set independent of whether IPv6 addresses exist for this name.

aiNumericHost :: AddressInfoFlags #

AI_NUMERICHOST:

aiV4Mapped :: AddressInfoFlags #

AI_V4MAPPED: Return mapped IPv4 addresses if no IPv6 addresses could be found or if aiAll flag is set.

NameInfoFlags

data NameInfoFlags #

Use the Monoid instance to combine several flags:

mconcat [niNameRequired, niNoFullyQualifiedDomainName]

niNameRequired :: NameInfoFlags #

NI_NAMEREQD: Throw an exception if the hostname cannot be determined.

niDatagram :: NameInfoFlags #

NI_DGRAM: Service is datagram based (i.e. UDP) rather than stream based (i.e. TCP).

niNoFullyQualifiedDomainName :: NameInfoFlags #

NI_NOFQDN: Return only the hostname part of the fully qualified domain name for local hosts.

niNumericHost :: NameInfoFlags #

NI_NUMERICHOST: Return the numeric form of the host address.

niNumericService :: NameInfoFlags #

NI_NUMERICSERV: Return the numeric form of the service address.

Exceptions

SocketException

eOk :: SocketException #

SocketException "No error"

eInterrupted :: SocketException #

SocketException "Interrupted system call"

NOTE: This exception shall not be thrown by any public operation in this library, but is handled internally.

eBadFileDescriptor :: SocketException #

SocketException "Bad file descriptor"

eInvalid :: SocketException #

SocketException "Invalid argument"

ePipe :: SocketException #

SocketException "Broken pipe"

eWouldBlock :: SocketException #

SocketException "Resource temporarily unavailable"

NOTE: This exception shall not be thrown by any public operation in this library, but is handled internally.

eAgain :: SocketException #

SocketException "Resource temporarily unavailable"

eNotSocket :: SocketException #

SocketException "Socket operation on non-socket"

NOTE: This should be ruled out by the type system.

eDestinationAddressRequired :: SocketException #

SocketException "Destination address required"

eMessageSize :: SocketException #

SocketException "Message too long"

eProtocolType :: SocketException #

SocketException "Protocol wrong type for socket"

eNoProtocolOption :: SocketException #

SocketException "Protocol not available"

eProtocolNotSupported :: SocketException #

SocketException "Protocol not supported"

eSocketTypeNotSupported :: SocketException #

SocketException "Socket type not supported"

eOperationNotSupported :: SocketException #

SocketException "Operation not supported"

eProtocolFamilyNotSupported :: SocketException #

SocketException "Protocol family not supported"

eAddressFamilyNotSupported :: SocketException #

SocketException "Address family not supported by protocol"

eAddressInUse :: SocketException #

SocketException "Address already in use"

eAddressNotAvailable :: SocketException #

SocketException "Cannot assign requested address"

eNetworkDown :: SocketException #

SocketException "Network is down"

eNetworkUnreachable :: SocketException #

SocketException "Network is unreachable"

eNetworkReset :: SocketException #

SocketException "Network dropped connection on reset"

eConnectionAborted :: SocketException #

SocketException "Software caused connection abort"

eConnectionReset :: SocketException #

SocketException "Connection reset by peer"

eNoBufferSpace :: SocketException #

SocketException "No buffer space available"

eIsConnected :: SocketException #

SocketException "Transport endpoint is already connected"

eNotConnected :: SocketException #

SocketException "Transport endpoint is not connected"

eShutdown :: SocketException #

SocketException "Cannot send after transport endpoint shutdown"

eTooManyReferences :: SocketException #

SocketException "Too many references: cannot splice"

eTimedOut :: SocketException #

SocketException "Connection timed out"

eConnectionRefused :: SocketException #

SocketException "Connection refused"

eHostDown :: SocketException #

SocketException "Host is down"

eHostUnreachable :: SocketException #

SocketException "No route to host"

eAlready :: SocketException #

SocketException "Operation already in progress"

NOTE: This exception shall not be thrown by any public operation in this library, but is handled internally.

eInProgress :: SocketException #

SocketException "Operation now in progress"

AddressInfoException

newtype AddressInfoException #

Contains the error code that can be matched against.

Hint: Use guards or MultiWayIf to match against specific exceptions:

if | e == eaiFail -> ...
   | e == eaiNoName -> ...
   | otherwise -> ...

eaiAgain :: AddressInfoException #

AddressInfoException "Temporary failure in name resolution"

eaiBadFlags :: AddressInfoException #

AddressInfoException "Bad value for ai_flags"

eaiFail :: AddressInfoException #

AddressInfoException "Non-recoverable failure in name resolution"

eaiFamily :: AddressInfoException #

AddressInfoException "ai_family not supported"

eaiMemory :: AddressInfoException #

AddressInfoException "Memory allocation failure"

eaiNoName :: AddressInfoException #

AddressInfoException "No such host is known"

eaiSocketType :: AddressInfoException #

AddressInfoException "ai_socktype not supported"

eaiService :: AddressInfoException #

AddressInfoException "Servname not supported for ai_socktype"

eaiSystem :: AddressInfoException #

AddressInfoException "System error"