network-2.3.1.0: Low-level networking interface

Portability | portable
Stability | provisional
Maintainer | libraries@haskell.org
Safe Haskell | Safe-Infered

Network.Socket.Internal

Contents

- Socket addresses
- Protocol families
- Socket error functions
- Guards for socket operations that may fail
- Initialization
- Low-level helpers

Description

A module containing semi-public `Socket` internals. Modules which extend the `Socket` module will need to use this module while ideally most users will be able to make do with the public interface.

Synopsis

- type HostAddress = Word32
- type HostAddress6 = (Word32, Word32, Word32, Word32)
- type FlowInfo = Word32
- type ScopeID = Word32
- newtype PortNumber = PortNum Word16
- data SockAddr
  - = SockAddrInet PortNumber HostAddress
  - | SockAddrInet6 PortNumber FlowInfo HostAddress6 ScopeID
  - | SockAddrUnix String
- peekSockAddr :: Ptr SockAddr -> IO SockAddr
- pokeSockAddr :: Ptr a -> SockAddr -> IO ()
- sizeOfSockAddr :: SockAddr -> Int
- sizeOfSockAddrByFamily :: Family -> Int
- withSockAddr :: SockAddr -> (Ptr SockAddr -> Int -> IO a) -> IO a
- withNewSockAddr :: Family -> (Ptr SockAddr -> Int -> IO a) -> IO a
- data Family
  - = AF_UNSPEC
  - | AF_UNIX
  - | AF_INET
  - | AF_INET6
  - | AF_IMPLINK
  - | AF_PUP
  - | AF_CHAOS
  - | AF_NS
  - | AF_ECMA
  - | AF_DATAKIT
  - | AF_CCITT
  - | AF_SNA
  - | AF_DECnet
  - | AF_DLI
  - | AF_LAT
  - | AF_HYLINK
  - | AF_APPLETALK
  - | AF_ROUTE
  - | AF_ISO
  - | AF_OSI
  - | AF_IPX
  - | AF_COIP
  - | AF_CNT
  - | AF_SIP
  - | AF_ISDN
  - | AF_NATM
  - | AF_ENCAP
  - | AF_LINK
  - | AF_BLUETOOTH
- throwSocketError :: String -> IO a
- throwSocketErrorIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO ()
- throwSocketErrorIfMinus1Retry :: (Eq a, Num a) => String -> IO a -> IO a
- throwSocketErrorIfMinus1RetryMayBlock :: (Eq a, Num a) => String -> IO b -> IO a -> IO a
- withSocketsDo :: IO a -> IO a
- zeroMemory :: Ptr a -> CSize -> IO ()

# Socket addresses

type HostAddress = Word32

Network byte order.

type HostAddress6 = (Word32, Word32, Word32, Word32)

Host byte order.

type FlowInfo = Word32

type ScopeID = Word32

newtype PortNumber

Constructors

PortNum Word16 |

Instances

Enum PortNumber |
Eq PortNumber |
Integral PortNumber |
Num PortNumber |
Ord PortNumber |
Real PortNumber |
Show PortNumber |
Typeable PortNumber |
Storable PortNumber |

data SockAddr

Constructors

SockAddrInet PortNumber HostAddress |
SockAddrInet6 PortNumber FlowInfo HostAddress6 ScopeID |
SockAddrUnix String |

Instances

Eq SockAddr |
Show SockAddr |
Typeable SockAddr |

peekSockAddr :: Ptr SockAddr -> IO SockAddr

Read a `SockAddr` from the given memory location.

pokeSockAddr :: Ptr a -> SockAddr -> IO ()

Write the given `SockAddr` to the given memory location.

sizeOfSockAddr :: SockAddr -> Int

Computes the storage requirements (in bytes) of the given `SockAddr`. This function differs from `sizeOf` in that the value of the argument is used.

sizeOfSockAddrByFamily :: Family -> Int

Computes the storage requirements (in bytes) required for a `SockAddr` with the given `Family`.

withSockAddr :: SockAddr -> (Ptr SockAddr -> Int -> IO a) -> IO a

Use a `SockAddr` with a function requiring a pointer to a `SockAddr` and the length of that `SockAddr`.

withNewSockAddr :: Family -> (Ptr SockAddr -> Int -> IO a) -> IO a

Create a new `SockAddr` for use with a function requiring a pointer to a `SockAddr` and the length of that `SockAddr`.

# Protocol families

data Family

This data type might have different constructors depending on what is supported by the operating system.

Constructors

AF_UNSPEC |
AF_UNIX |
AF_INET |
AF_INET6 |
AF_IMPLINK |
AF_PUP |
AF_CHAOS |
AF_NS |
AF_ECMA |
AF_DATAKIT |
AF_CCITT |
AF_SNA |
AF_DECnet |
AF_DLI |
AF_LAT |
AF_HYLINK |
AF_APPLETALK |
AF_ROUTE |
AF_ISO |
AF_OSI |
AF_IPX |
AF_COIP |
AF_CNT |
AF_SIP |
AF_ISDN |
AF_NATM |
AF_ENCAP |
AF_LINK |
AF_BLUETOOTH |

Instances

Eq Family |
Ord Family |
Read Family |
Show Family |

# Socket error functions

throwSocketError

Arguments

:: String | textual description of the error location
-> IO a |

Throw an `IOError` corresponding to the current socket error.

# Guards for socket operations that may fail

throwSocketErrorIfMinus1_

Arguments

:: (Eq a, Num a) |
=> String | textual description of the location
-> IO a | the `IO` operation to be executed
-> IO () |

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.

throwSocketErrorIfMinus1Retry

Arguments

:: (Eq a, Num a) |
=> String | textual description of the location
-> IO a | the `IO` operation to be executed
-> 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.

throwSocketErrorIfMinus1RetryMayBlock

Arguments

:: (Eq a, Num a) |
=> String | textual description of the location
-> IO b | action to execute before retrying if an immediate retry would block
-> IO a | the `IO` operation to be executed
-> 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. Checks for operations that would block and executes an alternative action before retrying in that case.

# Initialization

withSocketsDo :: IO a -> IO a

On Windows operating systems, the networking subsystem has to be initialised using `withSocketsDo` before any networking operations can be used. eg.

     main = withSocketsDo $ do {...}

Although this is only strictly necessary on Windows platforms, it is harmless on other platforms, so for portability it is good practice to use it all the time.

# Low-level helpers

zeroMemory :: Ptr a -> CSize -> IO ()

Zero a structure.