network-2.6.3.2: 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 Source #

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 HostAddress6 = (Word32, Word32, Word32, Word32) Source #

Independent of endianness. For example `::1` is stored as `(0, 0, 0, 1)`.

For direct manipulation prefer `hostAddress6ToTuple` and `tupleToHostAddress6`.

type FlowInfo = Word32 Source #

type ScopeID = Word32 Source #

newtype PortNumber Source #

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.

    >>> 1 :: PortNumber
    1
    >>> read "1" :: PortNumber
    1

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 Source # |
Methods succ :: PortNumber -> PortNumber # pred :: PortNumber -> PortNumber # toEnum :: Int -> PortNumber # fromEnum :: PortNumber -> Int # enumFrom :: PortNumber -> [PortNumber] # enumFromThen :: PortNumber -> PortNumber -> [PortNumber] # enumFromTo :: PortNumber -> PortNumber -> [PortNumber] # enumFromThenTo :: PortNumber -> PortNumber -> PortNumber -> [PortNumber] #
Eq PortNumber Source # |
Methods (==) :: PortNumber -> PortNumber -> Bool # (/=) :: PortNumber -> PortNumber -> Bool #
Integral PortNumber Source # |
Methods quot :: PortNumber -> PortNumber -> PortNumber # rem :: PortNumber -> PortNumber -> PortNumber # div :: PortNumber -> PortNumber -> PortNumber # mod :: PortNumber -> PortNumber -> PortNumber # quotRem :: PortNumber -> PortNumber -> (PortNumber, PortNumber) # divMod :: PortNumber -> PortNumber -> (PortNumber, PortNumber) # toInteger :: PortNumber -> Integer #
Num PortNumber Source # |
Methods (+) :: PortNumber -> PortNumber -> PortNumber # (-) :: PortNumber -> PortNumber -> PortNumber # (*) :: PortNumber -> PortNumber -> PortNumber # negate :: PortNumber -> PortNumber # abs :: PortNumber -> PortNumber # signum :: PortNumber -> PortNumber # fromInteger :: Integer -> PortNumber #
Ord PortNumber Source # |
Methods compare :: PortNumber -> PortNumber -> Ordering # (<) :: PortNumber -> PortNumber -> Bool # (<=) :: PortNumber -> PortNumber -> Bool # (>) :: PortNumber -> PortNumber -> Bool # (>=) :: PortNumber -> PortNumber -> Bool # max :: PortNumber -> PortNumber -> PortNumber # min :: PortNumber -> PortNumber -> PortNumber #
Read PortNumber Source # |
Methods readsPrec :: Int -> ReadS PortNumber # readList :: ReadS [PortNumber] # readPrec :: ReadPrec PortNumber # readListPrec :: ReadPrec [PortNumber] #
Real PortNumber Source # |
Methods toRational :: PortNumber -> Rational #
Show PortNumber Source # |
Methods showsPrec :: Int -> PortNumber -> ShowS # show :: PortNumber -> String # showList :: [PortNumber] -> ShowS #
Storable PortNumber Source # |
Methods sizeOf :: PortNumber -> Int # alignment :: PortNumber -> Int # peekElemOff :: Ptr PortNumber -> Int -> IO PortNumber # pokeElemOff :: Ptr PortNumber -> Int -> PortNumber -> IO () # peekByteOff :: Ptr b -> Int -> IO PortNumber # pokeByteOff :: Ptr b -> Int -> PortNumber -> IO () # peek :: Ptr PortNumber -> IO PortNumber # poke :: Ptr PortNumber -> PortNumber -> IO () #

data SockAddr Source #

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 Source # |
Methods (==) :: SockAddr -> SockAddr -> Bool # (/=) :: SockAddr -> SockAddr -> Bool #
Ord SockAddr Source # |
Methods compare :: SockAddr -> SockAddr -> Ordering # (<) :: SockAddr -> SockAddr -> Bool # (<=) :: SockAddr -> SockAddr -> Bool # (>) :: SockAddr -> SockAddr -> Bool # (>=) :: SockAddr -> SockAddr -> Bool # max :: SockAddr -> SockAddr -> SockAddr # min :: SockAddr -> SockAddr -> SockAddr #

peekSockAddr :: Ptr SockAddr -> IO SockAddr Source #

Read a `SockAddr` from the given memory location.

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

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

sizeOfSockAddr :: SockAddr -> Int Source #

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

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

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

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

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

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 Source # |
Methods (==) :: Family -> Family -> Bool # (/=) :: Family -> Family -> Bool #
Ord Family Source # |
Methods compare :: Family -> Family -> Ordering # (<) :: Family -> Family -> Bool # (<=) :: Family -> Family -> Bool # (>) :: Family -> Family -> Bool # (>=) :: Family -> Family -> Bool # max :: Family -> Family -> Family # min :: Family -> Family -> Family #
Read Family Source # |
Methods readsPrec :: Int -> ReadS Family # readList :: ReadS [Family] # readPrec :: ReadPrec Family # readListPrec :: ReadPrec [Family] #
Show Family Source # |
Methods showsPrec :: Int -> Family -> ShowS # show :: Family -> String # showList :: [Family] -> ShowS #

# Socket error functions

throwSocketError Source #

Arguments

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

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

throwSocketErrorCode :: String -> CInt -> IO a Source #

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_ Source #

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

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_ Source #

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

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

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

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

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 () Source #

Zero a structure.