network-2.6.3.5: Low-level networking interface

Copyright(c) The University of Glasgow 2001
LicenseBSD-style (see the file libraries/network/LICENSE)
Maintainerlibraries@haskell.org
Stabilityprovisional
Portabilityportable
Safe HaskellNone
LanguageHaskell98

Network

Contents

Description

This module is kept for backwards-compatibility. New users are encouraged to use Network.Socket instead.

Network was intended as a "higher-level" interface to networking facilities, and only supports TCP.

Synopsis

Basic data types

data Socket Source #

Represents a socket. The fields are, respectively:

  • File descriptor
  • Socket family
  • Socket type
  • Protocol number
  • Status flag

If you are calling the MkSocket constructor directly you should ensure you have called withSocketsDo and that the file descriptor is in non-blocking mode. See setNonBlockIfNeeded.

Sockets are not GCed unless they are closed by close.

Instances

type HostName = String Source #

Either a host name e.g., "haskell.org" or a numeric host address string consisting of a dotted decimal IPv4 address or an IPv6 address e.g., "192.168.0.1".

data 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

Instances

Enum PortNumber Source # 
Eq PortNumber Source # 
Integral PortNumber Source # 
Num PortNumber Source # 
Ord PortNumber Source # 
Read PortNumber Source # 
Real PortNumber Source # 
Show PortNumber Source # 
Storable PortNumber Source # 

Initialisation

withSocketsDo :: IO a -> IO a Source #

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.

In newer versions of the network library (version v2.6.1.0 or later) 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).

Server-side connections

listenOn Source #

Arguments

:: PortID

Port Identifier

-> IO Socket

Listening Socket

Creates the server side socket which has been bound to the specified port.

maxListenQueue (typically 128) is specified to the listen queue. This is good enough for normal network servers but is too small for high performance servers.

To avoid the "Address already in use" problems, the ReuseAddr socket option is set on the listening socket.

If available, the IPv6Only socket option is set to 0 so that both IPv4 and IPv6 can be accepted with this socket.

If you don't like the behavior above, please use the lower level listen instead.

accept Source #

Arguments

:: 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 operations (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, AF_INET, or AF_INET6 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 () Source #

Close the socket. Sending data to or receiving data from closed socket may lead to undefined behaviour.

Client-side connections

connectTo :: HostName -> PortID -> IO Handle Source #

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.

Miscellaneous

socketPort :: Socket -> IO PortID Source #

Returns the PortID associated with a given socket.

Networking Issues

Buffering

The Handle returned by connectTo and accept is NoBuffering by default. For an interactive application you may want to set the buffering mode on the Handle to LineBuffering or BlockBuffering, 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.