</head></meta>

Haskell Core Libraries (network package)

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)

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

data PortID

Constructors

Service String
PortNumber PortNumber
UnixSocket String

type HostName = String

data PortNumber

Instances

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.

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

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 reading from a socket and the writing 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.4