Network.Socket.Internal

network-2.6.2.1: Low-level networking interface

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/network/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | None
Language | Haskell98

Network.Socket.Internal

Contents

- Socket addresses
- Protocol families
- Socket error functions
- Guards for socket operations that may fail
  - Guards that wait and retry if the operation would block
- 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
  - | SockAddrCan Int32
- 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_NBS
  - | AF_ECMA
  - | AF_DATAKIT
  - | AF_CCITT
  - | AF_SNA
  - | AF_DECnet
  - | AF_DLI
  - | AF_LAT
  - | AF_HYLINK
  - | AF_APPLETALK
  - | AF_ROUTE
  - | AF_NETBIOS
  - | AF_NIT
  - | AF_802
  - | AF_ISO
  - | AF_OSI
  - | AF_NETMAN
  - | AF_X25
  - | AF_AX25
  - | AF_OSINET
  - | AF_GOSSIP
  - | AF_IPX
  - | Pseudo_AF_XTP
  - | AF_CTF
  - | AF_WAN
  - | AF_SDL
  - | AF_NETWARE
  - | AF_NDD
  - | AF_INTF
  - | AF_COIP
  - | AF_CNT
  - | Pseudo_AF_RTIP
  - | Pseudo_AF_PIP
  - | AF_SIP
  - | AF_ISDN
  - | Pseudo_AF_KEY
  - | AF_NATM
  - | AF_ARP
  - | Pseudo_AF_HDRCMPLT
  - | AF_ENCAP
  - | AF_LINK
  - | AF_RAW
  - | AF_RIF
  - | AF_NETROM
  - | AF_BRIDGE
  - | AF_ATMPVC
  - | AF_ROSE
  - | AF_NETBEUI
  - | AF_SECURITY
  - | AF_PACKET
  - | AF_ASH
  - | AF_ECONET
  - | AF_ATMSVC
  - | AF_IRDA
  - | AF_PPPOX
  - | AF_WANPIPE
  - | AF_BLUETOOTH
  - | AF_CAN
- throwSocketError :: String -> IO a
- throwSocketErrorCode :: String -> CInt -> IO a
- throwSocketErrorIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO ()
- throwSocketErrorIfMinus1Retry :: (Eq a, Num a) => String -> IO a -> IO a
- throwSocketErrorIfMinus1Retry_ :: (Eq a, Num a) => String -> IO a -> IO ()
- throwSocketErrorIfMinus1RetryMayBlock :: (Eq a, Num a) => String -> IO b -> IO a -> IO a
- throwSocketErrorWaitRead :: (Eq a, Num a) => Socket -> String -> IO a -> IO a
- throwSocketErrorWaitWrite :: (Eq a, Num a) => Socket -> String -> 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

Use the `Num` instance (i.e. use a literal) to create a `PortNumber` value with the correct network-byte-ordering. You should not use the PortNum constructor. It will be removed in the next release.

Constructors

PortNum Word16 | Deprecated: Do not use the PortNum constructor. Use the Num instance. PortNum will be removed in the next release.

Instances

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

data SockAddr

The existence of a constructor does not necessarily imply that that socket address type is supported on your system: see `isSupportedSockAddr`.

Constructors

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

Instances

Eq SockAddr |
Ord 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

Address families.

A constructor being present here does not mean it is supported by the operating system: see `isSupportedFamily`.

Constructors

AF_UNSPEC |
AF_UNIX |
AF_INET |
AF_INET6 |
AF_IMPLINK |
AF_PUP |
AF_CHAOS |
AF_NS |
AF_NBS |
AF_ECMA |
AF_DATAKIT |
AF_CCITT |
AF_SNA |
AF_DECnet |
AF_DLI |
AF_LAT |
AF_HYLINK |
AF_APPLETALK |
AF_ROUTE |
AF_NETBIOS |
AF_NIT |
AF_802 |
AF_ISO |
AF_OSI |
AF_NETMAN |
AF_X25 |
AF_AX25 |
AF_OSINET |
AF_GOSSIP |
AF_IPX |
Pseudo_AF_XTP |
AF_CTF |
AF_WAN |
AF_SDL |
AF_NETWARE |
AF_NDD |
AF_INTF |
AF_COIP |
AF_CNT |
Pseudo_AF_RTIP |
Pseudo_AF_PIP |
AF_SIP |
AF_ISDN |
Pseudo_AF_KEY |
AF_NATM |
AF_ARP |
Pseudo_AF_HDRCMPLT |
AF_ENCAP |
AF_LINK |
AF_RAW |
AF_RIF |
AF_NETROM |
AF_BRIDGE |
AF_ATMPVC |
AF_ROSE |
AF_NETBEUI |
AF_SECURITY |
AF_PACKET |
AF_ASH |
AF_ECONET |
AF_ATMSVC |
AF_IRDA |
AF_PPPOX |
AF_WANPIPE |
AF_BLUETOOTH |
AF_CAN |

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.

throwSocketErrorCode :: String -> CInt -> 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.

# 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.

throwSocketErrorIfMinus1Retry_

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`, but retries in case of an interrupted operation. Discards the result of the IO action after error handling.

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.

## Guards that wait and retry if the operation would block

These guards are based on `throwSocketErrorIfMinus1RetryMayBlock`. They wait for socket readiness if the action fails with `EWOULDBLOCK` or similar.

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.

throwSocketErrorWaitWrite :: (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 write-ready, and try again.

# Initialization

withSocketsDo :: IO a -> IO a

With older versions of the `network` library 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.

In newer versions of the `network` library it is only necessary to call `withSocketsDo` if you are calling the `MkSocket` constructor directly. However, for compatibility with older versions on Windows, it is good practice to always call `withSocketsDo` (it's very cheap).

# Low-level helpers

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

Zero a structure.