network 2.2.1.8 → 2.2.1.9
raw patch · 2 files changed
+88/−70 lines, 2 files
Files
- Network/Socket.hsc +87/−69
- network.cabal +1/−1
Network/Socket.hsc view
@@ -83,7 +83,7 @@ getNameInfo, -- :: [NameInfoFlag] -> Bool -> Bool -> SockAddr -> IO (Maybe HostName, Maybe ServiceName) #endif - -- * Socket Operations+ -- * Socket operations socket, -- :: Family -> SocketType -> ProtocolNumber -> IO Socket #if defined(DOMAIN_SOCKET_SUPPORT) socketPair, -- :: Family -> SocketType -> ProtocolNumber -> IO (Socket, Socket)@@ -143,7 +143,7 @@ #endif - -- * Special Constants+ -- * Special constants aNY_PORT, -- :: PortNumber iNADDR_ANY, -- :: HostAddress #if defined(IPV6_SOCKET_SUPPORT)@@ -239,6 +239,9 @@ import Network.Socket.Internal +-- | 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\"@. type HostName = String type ServiceName = String @@ -414,17 +417,14 @@ -- programmers and have thus been renamed by appending the prefix -- Socket. --- Create an unconnected socket of the given family, type and--- protocol. The most common invocation of $socket$ is the following:--- ...--- my_socket <- socket AF_INET Stream 6--- ...-+-- | Create a new socket using the given address family, socket type+-- and protocol number. The address family is usually 'AF_INET',+-- 'AF_INET6', or 'AF_UNIX'. The socket type is usually 'Stream' or+-- 'Datagram'. The protocol number is usually 'defaultProtocol'. socket :: Family -- Family Name (usually AF_INET) -> SocketType -- Socket Type (usually Stream) -> ProtocolNumber -- Protocol Number (getProtocolByName to find value) -> IO Socket -- Unconnected Socket- socket family stype protocol = do fd <- throwSocketErrorIfMinus1Retry "socket" $ c_socket (packFamily family) (packSocketType stype) protocol@@ -438,10 +438,10 @@ socket_status <- newMVar NotConnected return (MkSocket fd family stype protocol socket_status) --- Create an unnamed pair of connected sockets, given family, type and--- protocol. Differs from a normal pipe in being a bi-directional channel--- of communication.-+-- | Build a pair of connected socket objects using the given address+-- family, socket type, and protocol number. Address family, socket+-- type, and protocol number are as for the 'socket' function above.+-- Availability: Unix. #if defined(DOMAIN_SOCKET_SUPPORT) socketPair :: Family -- Family Name (usually AF_INET or AF_INET6) -> SocketType -- Socket Type (usually Stream)@@ -475,26 +475,15 @@ ----------------------------------------------------------------------------- -- Binding a socket------ Given a port number this {\em binds} the socket to that port. This--- means that the programmer is only interested in data being sent to--- that port number. The $Family$ passed to $bindSocket$ must--- be the same as that passed to $socket$. If the special port--- number $aNY\_PORT$ is passed then the system assigns the next--- available use port.--- --- Port numbers for standard unix services can be found by calling--- $getServiceEntry$. These are traditionally port numbers below--- 1000; although there are afew, namely NFS and IRC, which used higher--- numbered ports.--- --- The port number allocated to a socket bound by using $aNY\_PORT$ can be--- found by calling $port$ +-- | Bind the socket to an address. The socket must not already be+-- bound. The 'Family' passed to @bindSocket@ must be the+-- same as that passed to 'socket'. If the special port number+-- 'aNY_PORT' is passed then the system assigns the next available+-- use port. bindSocket :: Socket -- Unconnected Socket- -> SockAddr -- Address to Bind to- -> IO ()-+ -> SockAddr -- Address to Bind to+ -> IO () bindSocket (MkSocket s _family _stype _protocol socketStatus) addr = do modifyMVar_ socketStatus $ \ status -> do if status /= NotConnected @@ -508,22 +497,11 @@ ----------------------------------------------------------------------------- -- Connecting a socket------ Make a connection to an already opened socket on a given machine--- and port. assumes that we have already called createSocket,--- otherwise it will fail.------ This is the dual to $bindSocket$. The {\em server} process will--- usually bind to a port number, the {\em client} will then connect--- to the same port number. Port numbers of user applications are--- normally agreed in advance, otherwise we must rely on some meta--- protocol for telling the other side what port number we have been--- allocated. -connect :: Socket -- Unconnected Socket- -> SockAddr -- Socket address stuff- -> IO ()-+-- | Connect to a remote socket at address.+connect :: Socket -- Unconnected Socket+ -> SockAddr -- Socket address stuff+ -> IO () connect sock@(MkSocket s _family _stype _protocol socketStatus) addr = do modifyMVar_ socketStatus $ \currentStatus -> do if currentStatus /= NotConnected && currentStatus /= Bound@@ -573,21 +551,13 @@ ----------------------------------------------------------------------------- -- Listen------ The programmer must call $listen$ to tell the system software that--- they are now interested in receiving data on this port. This must--- be called on the bound socket before any calls to read or write--- data are made. --- The programmer also gives a number which indicates the length of--- the incoming queue of unread messages for this socket. On most--- systems the maximum queue length is around 5. To remove a message--- from the queue for processing a call to $accept$ should be made.-+-- | Listen for connections made to the socket. The second argument+-- specifies the maximum number of queued connections and should be at+-- least 1; the maximum value is system-dependent (usually 5). listen :: Socket -- Connected & Bound Socket -> Int -- Queue Length -> IO ()- listen (MkSocket s _family _stype _protocol socketStatus) backlog = do modifyMVar_ socketStatus $ \ status -> do if status /= Bound @@ -607,6 +577,11 @@ -- should then be closed. Using the socket returned by `accept' allows -- incoming requests to be queued on the original socket. +-- | Accept a connection. The socket must be bound to an address and+-- listening for connections. The return value is a pair @(conn,+-- address)@ where @conn@ is a new socket object usable to send and+-- receive data on the connection, and @address@ is the address bound+-- to the socket on the other end of the connection. accept :: Socket -- Queue Socket -> IO (Socket, -- Readable Socket SockAddr) -- Peer details@@ -669,22 +644,29 @@ ----------------------------------------------------------------------------- -- sendTo & recvFrom --- | NOTE: blocking on Windows unless you compile with -threaded (see+-- | Send data to the socket. The recipient can be specified+-- explicitly, so the socket need not be in a connected state.+-- Returns the number of bytes sent. Applications are responsible for+-- ensuring that all data has been sent.+--+-- NOTE: blocking on Windows unless you compile with -threaded (see -- GHC ticket #1129) sendTo :: Socket -- (possibly) bound/connected Socket -> String -- Data to send -> SockAddr -> IO Int -- Number of Bytes sent- sendTo sock xs addr = do withCString xs $ \str -> do sendBufTo sock str (length xs) addr -sendBufTo :: Socket -- (possibly) bound/connected Socket- -> Ptr a -> Int -- Data to send+-- | Send data to the socket. The recipient can be specified+-- explicitly, so the socket need not be in a connected state.+-- Returns the number of bytes sent. Applications are responsible for+-- ensuring that all data has been sent.+sendBufTo :: Socket -- (possibly) bound/connected Socket+ -> Ptr a -> Int -- Data to send -> SockAddr- -> IO Int -- Number of Bytes sent-+ -> IO Int -- Number of Bytes sent sendBufTo (MkSocket s _family _stype _protocol status) ptr nbytes addr = do withSockAddr addr $ \p_addr sz -> do liftM fromIntegral $@@ -695,7 +677,13 @@ c_sendto s ptr (fromIntegral $ nbytes) 0{-flags-} p_addr (fromIntegral sz) --- | NOTE: blocking on Windows unless you compile with -threaded (see+-- | Receive data from the socket. The socket need not be in a+-- connected state. Returns @(bytes, nbytes, address)@ where @bytes@+-- is a @String@ of length @nbytes@ representing the data received and+-- @address@ is a 'SockAddr' representing the address of the sending+-- socket.+--+-- NOTE: blocking on Windows unless you compile with -threaded (see -- GHC ticket #1129) recvFrom :: Socket -> Int -> IO (String, Int, SockAddr) recvFrom sock nbytes =@@ -704,6 +692,14 @@ str <- peekCStringLen (ptr, len) return (str, len, sockaddr) +-- | Receive data from the socket, writing it into buffer instead of+-- creating a new string. The socket need not be in a connected+-- state. Returns @(nbytes, address)@ where @nbytes@ is the number of+-- bytes received and @address@ is a 'SockAddr' representing the+-- address of the sending socket.+--+-- NOTE: blocking on Windows unless you compile with -threaded (see+-- GHC ticket #1129) recvBufFrom :: Socket -> Ptr a -> Int -> IO (Int, SockAddr) recvBufFrom sock@(MkSocket s family _stype _protocol status) ptr nbytes | nbytes <= 0 = ioError (mkInvalidRecvArgError "Network.Socket.recvFrom")@@ -736,6 +732,9 @@ ----------------------------------------------------------------------------- -- send & recv +-- | Send data to the socket. The socket must be connected to a remote+-- socket. Returns the number of bytes sent. Applications are+-- responsible for ensuring that all data has been sent. send :: Socket -- Bound/Connected Socket -> String -- Data to send -> IO Int -- Number of Bytes sent@@ -769,6 +768,17 @@ c_send s str (fromIntegral len) 0{-flags-} #endif +-- | Receive data from the socket. The socket must be in a connected+-- state. This function may return fewer bytes than specified. If the+-- message is longer than the specified length, it may be discarded+-- depending on the type of socket. This function may block until a+-- message arrives.+--+-- Considering hardware and network realities, the maximum number of+-- bytes to receive should be a small power of 2, e.g., 4096.+--+-- For TCP sockets, a zero length return value means the peer has+-- closed its half side of the connection. recv :: Socket -> Int -> IO String recv sock l = recvLen sock l >>= \ (s,_) -> return s @@ -1663,6 +1673,11 @@ sdownCmdToInt ShutdownSend = 1 sdownCmdToInt ShutdownBoth = 2 +-- | Shut down one or both halves of the connection, depending on the+-- second argument to the function. If the second argument is+-- 'ShutdownReceive', further receives are disallowed. If it is+-- 'ShutdownSend', further sends are disallowed. If it is+-- 'ShutdownBoth', further sends and receives are disallowed. shutdown :: Socket -> ShutdownCmd -> IO () shutdown (MkSocket s _ _ _ _) stype = do throwSocketErrorIfMinus1Retry "shutdown" (c_shutdown s (sdownCmdToInt stype))@@ -1670,7 +1685,9 @@ -- ----------------------------------------------------------------------------- --- | Closes a socket+-- | Close the socket. All future operations on the socket object+-- will fail. The remote end will receive no more data (after queued+-- data is flushed). sClose :: Socket -> IO () sClose (MkSocket s _ _ _ socketStatus) = do modifyMVar_ socketStatus $ \ status ->@@ -1711,9 +1728,10 @@ sIsAcceptable :: Socket -> IO Bool #if defined(DOMAIN_SOCKET_SUPPORT)-sIsAcceptable (MkSocket _ AF_UNIX Stream _ status) = do- value <- readMVar status- return (value == Connected || value == Bound || value == Listening)+sIsAcceptable (MkSocket _ AF_UNIX x _ status)+ | x == Stream || x == SeqPacket = do+ value <- readMVar status+ return (value == Connected || value == Bound || value == Listening) sIsAcceptable (MkSocket _ AF_UNIX _ _ _) = return False #endif sIsAcceptable (MkSocket _ _ _ _ status) = do@@ -1736,7 +1754,7 @@ pstr <- c_inet_ntoa haddr peekCString pstr --- | turns a Socket into an 'Handle'. By default, the new handle is+-- | Turns a Socket into an 'Handle'. By default, the new handle is -- unbuffered. Use 'System.IO.hSetBuffering' to change the buffering. -- -- Note that since a 'Handle' is automatically closed by a finalizer
network.cabal view
@@ -1,5 +1,5 @@ name: network-version: 2.2.1.8+version: 2.2.1.9 license: BSD3 license-file: LICENSE maintainer: Johan Tibell <johan.tibell@gmail.com>