| Haskell Core Libraries (network package) | Contents | Index

Network

Portability | portable
Stability | provisional
Maintainer | libraries@haskell.org

Contents

Basic data types
Initialisation
Server-side connections
Client-side connections
Simple sending and receiving
Miscellaneous
Networking Issues
  Buffering
  Improving I/O Performance over sockets
  `SIGPIPE`

Description
The Network interface is a "higher-level" interface to networking facilities, and it is recommended unless you need the lower-level interface in Network.Socket.
Synopsis

data Socket

data PortID

= Service String
| PortNumber PortNumber
| UnixSocket String

type HostName = String
data PortNumber
withSocketsDo :: IO a -> IO a
listenOn :: PortID -> IO Socket
accept :: Socket -> IO (Handle, HostName, PortNumber)
sClose :: Socket -> IO ()
connectTo :: HostName -> PortID -> IO Handle
sendTo :: HostName -> PortID -> String -> IO ()
recvFrom :: HostName -> PortID -> IO String
socketPort :: Socket -> IO PortID

Basic data types
data Socket

Instances

Eq Socket
Show Socket
Typeable Socket

data PortID

Constructors

Service String |
PortNumber PortNumber |
UnixSocket String |

type HostName = String
data PortNumber

Instances

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

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

Server-side connections
listenOn

:: PortID | Port Identifier
-> IO Socket | Connected Socket
Creates the server side socket which has been bound to the specified port. NOTE: To avoid the "Address already in use" problems popped up several times on the GHC-Users mailing list we set the `ReuseAddr` socket option on the listening socket. If you don't want this behaviour, please use the lower level `listen` instead.

accept

:: Socket | Listening Socket
-> IO (Handle, HostName, PortNumber) | Triple of: read/write `Handle` for communicating with the client, the `HostName` of the peer socket, and the `PortNumber` of the remote connection.

Accept a connection on a socket created by `listenOn`. Normal I/O opertaions (see System.IO) can be used on the `Handle` returned to communicate with the client. Notice that although you can pass any Socket to Network.accept, only sockets of either AF_UNIX or AF_INET will work (this shouldn't be a problem, though). When using AF_UNIX, HostName will be set to the path of the socket and PortNumber to -1.

sClose :: Socket -> IO ()
Closes a socket
Client-side connections
connectTo :: HostName -> PortID -> IO Handle
Calling `connectTo` creates a client side socket which is connected to the given host and port. The Protocol and socket type is derived from the given port identifier. If a port number is given then the result is always an internet family `Stream` socket.
Simple sending and receiving

Send and receive data from/to the given host and port number. These should normally only be used where the socket will not be required for further calls. Also, note that due to the use of `hGetContents` in `recvFrom` the socket will remain open (i.e. not available) even if the function already returned. Their use is strongly discouraged except for small test-applications or invocations from the command line.

sendTo :: HostName -> PortID -> String -> IO ()
recvFrom :: HostName -> PortID -> IO String
Miscellaneous
socketPort :: Socket -> IO PortID
Returns the `PortID` associated with a given socket.
Networking Issues
Buffering

The `Handle` returned by `connectTo` and `accept` is block-buffered by default. For an interactive application you may want to set the buffering mode on the `Handle` to `LineBuffering` or `NoBuffering`, like so:

     h <- connectTo host port
     hSetBuffering h LineBuffering

Improving I/O Performance over sockets
For really fast I/O, it might be worth looking at the `hGetBuf` and `hPutBuf` family of functions in System.IO.
`SIGPIPE`

On Unix, when writing to a socket and the reading end is closed by the remote client, the program is normally sent a `SIGPIPE` signal by the operating system. The default behaviour when a `SIGPIPE` is received is to terminate the program silently, which can be somewhat confusing if you haven't encountered this before. The solution is to specify that `SIGPIPE` is to be ignored, using the POSIX library:

      import Posix
      main = do installHandler sigPIPE Ignore Nothing; ...

Produced by Haddock version 0.7