|
| Network | | Portability | portable | | Stability | provisional | | Maintainer | libraries@haskell.org |
|
|
|
|
|
| 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 |
|
|
|
|
| Basic data types
|
|
| data Socket |
 Instances | |
|
|
| data PortID |
|
|
| type HostName = String |
|
| data PortNumber |
| Instances | |
|
|
| 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.8 |
