Network.Socket.Internal

network-3.1.2.7: 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 | Safe-Inferred
Language | Haskell2010

Network.Socket.Internal

Contents

- 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 Network.Socket internals. Modules which extend the Network.Socket module will need to use this module while ideally most users will be able to make do with the public interface.

Synopsis

- 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
- throwSocketErrorWaitReadBut :: (Eq a, Num a) => (CInt -> Bool) -> 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 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.

throwSocketErrorWaitReadBut :: (Eq a, Num a) => (CInt -> Bool) -> 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. If it fails with the error the user was expecting then ignore the error

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 (version 2.6.0.2 or earlier) 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.

`withSocketsDo` is not necessary for the current network library. 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.