network-2.6.3.2: Low-level networking interface

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/network/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | None
Language | Haskell98

Network.Socket

Contents

- Types
- Address operations
- Socket operations
  - Sending and receiving data
    - Sending and receiving with String
    - Sending and receiving with a buffer
  - Misc
  - Predicates on sockets
- Socket options
- File descriptor transmission
- Special constants
- Initialisation
- Very low level operations
- Deprecated aliases
- Internal
- Orphan instances

Description

The Network.Socket module is for when you want full control over sockets. Essentially the entire C socket API is exposed through this module; in general the operations follow the behaviour of the C functions of the same name (consult your favourite Unix networking book).

A higher level interface to networking operations is provided through the module Network.

Synopsis

- data Socket = MkSocket CInt Family SocketType ProtocolNumber (MVar SocketStatus)
- data Family
  - = AF_UNSPEC
  - | AF_UNIX
  - | AF_INET
  - | AF_INET6
  - | AF_IMPLINK
  - | AF_PUP
  - | AF_CHAOS
  - | AF_NS
  - | AF_NBS
  - | AF_ECMA
  - | AF_DATAKIT
  - | AF_CCITT
  - | AF_SNA
  - | AF_DECnet
  - | AF_DLI
  - | AF_LAT
  - | AF_HYLINK
  - | AF_APPLETALK
  - | AF_ROUTE
  - | AF_NETBIOS
  - | AF_NIT
  - | AF_802
  - | AF_ISO
  - | AF_OSI
  - | AF_NETMAN
  - | AF_X25
  - | AF_AX25
  - | AF_OSINET
  - | AF_GOSSIP
  - | AF_IPX
  - | Pseudo_AF_XTP
  - | AF_CTF
  - | AF_WAN
  - | AF_SDL
  - | AF_NETWARE
  - | AF_NDD
  - | AF_INTF
  - | AF_COIP
  - | AF_CNT
  - | Pseudo_AF_RTIP
  - | Pseudo_AF_PIP
  - | AF_SIP
  - | AF_ISDN
  - | Pseudo_AF_KEY
  - | AF_NATM
  - | AF_ARP
  - | Pseudo_AF_HDRCMPLT
  - | AF_ENCAP
  - | AF_LINK
  - | AF_RAW
  - | AF_RIF
  - | AF_NETROM
  - | AF_BRIDGE
  - | AF_ATMPVC
  - | AF_ROSE
  - | AF_NETBEUI
  - | AF_SECURITY
  - | AF_PACKET
  - | AF_ASH
  - | AF_ECONET
  - | AF_ATMSVC
  - | AF_IRDA
  - | AF_PPPOX
  - | AF_WANPIPE
  - | AF_BLUETOOTH
  - | AF_CAN
- isSupportedFamily :: Family -> Bool
- data SocketType
  - = NoSocketType
  - | Stream
  - | Datagram
  - | Raw
  - | RDM
  - | SeqPacket
- isSupportedSocketType :: SocketType -> Bool
- data SockAddr
  - = SockAddrInet PortNumber HostAddress
  - | SockAddrInet6 PortNumber FlowInfo HostAddress6 ScopeID
  - | SockAddrUnix String
  - | SockAddrCan Int32
- isSupportedSockAddr :: SockAddr -> Bool
- data SocketStatus
  - = NotConnected
  - | Bound
  - | Listening
  - | Connected
  - | ConvertedToHandle
  - | Closed
- type HostAddress = Word32
- hostAddressToTuple :: HostAddress -> (Word8, Word8, Word8, Word8)
- tupleToHostAddress :: (Word8, Word8, Word8, Word8) -> HostAddress
- type HostAddress6 = (Word32, Word32, Word32, Word32)
- hostAddress6ToTuple :: HostAddress6 -> (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16)
- tupleToHostAddress6 :: (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16) -> HostAddress6
- type FlowInfo = Word32
- type ScopeID = Word32
- htonl :: Word32 -> Word32
- ntohl :: Word32 -> Word32
- data ShutdownCmd
  - = ShutdownReceive
  - | ShutdownSend
  - | ShutdownBoth
- type ProtocolNumber = CInt
- defaultProtocol :: ProtocolNumber
- newtype PortNumber = PortNum Word16
- type HostName = String
- type ServiceName = String
- data AddrInfo = AddrInfo {
  - addrFlags :: [AddrInfoFlag]
  - addrFamily :: Family
  - addrSocketType :: SocketType
  - addrProtocol :: ProtocolNumber
  - addrAddress :: SockAddr
  - addrCanonName :: Maybe String
  }
- data AddrInfoFlag
  - = AI_ADDRCONFIG
  - | AI_ALL
  - | AI_CANONNAME
  - | AI_NUMERICHOST
  - | AI_NUMERICSERV
  - | AI_PASSIVE
  - | AI_V4MAPPED
- addrInfoFlagImplemented :: AddrInfoFlag -> Bool
- defaultHints :: AddrInfo
- getAddrInfo :: Maybe AddrInfo -> Maybe HostName -> Maybe ServiceName -> IO [AddrInfo]
- data NameInfoFlag
  - = NI_DGRAM
  - | NI_NAMEREQD
  - | NI_NOFQDN
  - | NI_NUMERICHOST
  - | NI_NUMERICSERV
- getNameInfo :: [NameInfoFlag] -> Bool -> Bool -> SockAddr -> IO (Maybe HostName, Maybe ServiceName)
- socket :: Family -> SocketType -> ProtocolNumber -> IO Socket
- socketPair :: Family -> SocketType -> ProtocolNumber -> IO (Socket, Socket)
- connect :: Socket -> SockAddr -> IO ()
- bind :: Socket -> SockAddr -> IO ()
- listen :: Socket -> Int -> IO ()
- accept :: Socket -> IO (Socket, SockAddr)
- getPeerName :: Socket -> IO SockAddr
- getSocketName :: Socket -> IO SockAddr
- getPeerCred :: Socket -> IO (CUInt, CUInt, CUInt)
- socketPort :: Socket -> IO PortNumber
- socketToHandle :: Socket -> IOMode -> IO Handle
- send :: Socket -> String -> IO Int
- sendTo :: Socket -> String -> SockAddr -> IO Int
- recv :: Socket -> Int -> IO String
- recvFrom :: Socket -> Int -> IO (String, Int, SockAddr)
- recvLen :: Socket -> Int -> IO (String, Int)
- sendBuf :: Socket -> Ptr Word8 -> Int -> IO Int
- recvBuf :: Socket -> Ptr Word8 -> Int -> IO Int
- sendBufTo :: Socket -> Ptr a -> Int -> SockAddr -> IO Int
- recvBufFrom :: Socket -> Ptr a -> Int -> IO (Int, SockAddr)
- inet_addr :: String -> IO HostAddress
- inet_ntoa :: HostAddress -> IO String
- shutdown :: Socket -> ShutdownCmd -> IO ()
- close :: Socket -> IO ()
- isConnected :: Socket -> IO Bool
- isBound :: Socket -> IO Bool
- isListening :: Socket -> IO Bool
- isReadable :: Socket -> IO Bool
- isWritable :: Socket -> IO Bool
- data SocketOption
  - = Debug
  - | ReuseAddr
  - | Type
  - | SoError
  - | DontRoute
  - | Broadcast
  - | SendBuffer
  - | RecvBuffer
  - | KeepAlive
  - | OOBInline
  - | TimeToLive
  - | MaxSegment
  - | NoDelay
  - | Cork
  - | Linger
  - | ReusePort
  - | RecvLowWater
  - | SendLowWater
  - | RecvTimeOut
  - | SendTimeOut
  - | UseLoopBack
  - | UserTimeout
  - | IPv6Only
  - | CustomSockOpt (CInt, CInt)
- isSupportedSocketOption :: SocketOption -> Bool
- getSocketOption :: Socket -> SocketOption -> IO Int
- setSocketOption :: Socket -> SocketOption -> Int -> IO ()
- sendFd :: Socket -> CInt -> IO ()
- recvFd :: Socket -> IO CInt
- aNY_PORT :: PortNumber
- iNADDR_ANY :: HostAddress
- iN6ADDR_ANY :: HostAddress6
- sOMAXCONN :: Int
- sOL_SOCKET :: Int
- sCM_RIGHTS :: Int
- maxListenQueue :: Int
- withSocketsDo :: IO a -> IO a
- fdSocket :: Socket -> CInt
- mkSocket :: CInt -> Family -> SocketType -> ProtocolNumber -> SocketStatus -> IO Socket
- setNonBlockIfNeeded :: CInt -> IO ()
- bindSocket :: Socket -> SockAddr -> IO ()
- sClose :: Socket -> IO ()
- sIsConnected :: Socket -> IO Bool
- sIsBound :: Socket -> IO Bool
- sIsListening :: Socket -> IO Bool
- sIsReadable :: Socket -> IO Bool
- sIsWritable :: Socket -> IO Bool
- packFamily :: Family -> CInt
- unpackFamily :: CInt -> Family
- packSocketType :: SocketType -> CInt

# 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`.

Constructors

MkSocket CInt Family SocketType ProtocolNumber (MVar SocketStatus) |

Instances

Eq Socket Source # |
Methods (==) :: Socket -> Socket -> Bool # (/=) :: Socket -> Socket -> Bool #
Show Socket Source # |
Methods showsPrec :: Int -> Socket -> ShowS # show :: Socket -> String # showList :: [Socket] -> ShowS #

data Family Source #

Address families.

A constructor being present here does not mean it is supported by the operating system: see `isSupportedFamily`.

Constructors

AF_UNSPEC |
AF_UNIX |
AF_INET |
AF_INET6 |
AF_IMPLINK |
AF_PUP |
AF_CHAOS |
AF_NS |
AF_NBS |
AF_ECMA |
AF_DATAKIT |
AF_CCITT |
AF_SNA |
AF_DECnet |
AF_DLI |
AF_LAT |
AF_HYLINK |
AF_APPLETALK |
AF_ROUTE |
AF_NETBIOS |
AF_NIT |
AF_802 |
AF_ISO |
AF_OSI |
AF_NETMAN |
AF_X25 |
AF_AX25 |
AF_OSINET |
AF_GOSSIP |
AF_IPX |
Pseudo_AF_XTP |
AF_CTF |
AF_WAN |
AF_SDL |
AF_NETWARE |
AF_NDD |
AF_INTF |
AF_COIP |
AF_CNT |
Pseudo_AF_RTIP |
Pseudo_AF_PIP |
AF_SIP |
AF_ISDN |
Pseudo_AF_KEY |
AF_NATM |
AF_ARP |
Pseudo_AF_HDRCMPLT |
AF_ENCAP |
AF_LINK |
AF_RAW |
AF_RIF |
AF_NETROM |
AF_BRIDGE |
AF_ATMPVC |
AF_ROSE |
AF_NETBEUI |
AF_SECURITY |
AF_PACKET |
AF_ASH |
AF_ECONET |
AF_ATMSVC |
AF_IRDA |
AF_PPPOX |
AF_WANPIPE |
AF_BLUETOOTH |
AF_CAN |

Instances

Eq Family Source # |
Methods (==) :: Family -> Family -> Bool # (/=) :: Family -> Family -> Bool #
Ord Family Source # |
Methods compare :: Family -> Family -> Ordering # (<) :: Family -> Family -> Bool # (<=) :: Family -> Family -> Bool # (>) :: Family -> Family -> Bool # (>=) :: Family -> Family -> Bool # max :: Family -> Family -> Family # min :: Family -> Family -> Family #
Read Family Source # |
Methods readsPrec :: Int -> ReadS Family # readList :: ReadS [Family] # readPrec :: ReadPrec Family # readListPrec :: ReadPrec [Family] #
Show Family Source # |
Methods showsPrec :: Int -> Family -> ShowS # show :: Family -> String # showList :: [Family] -> ShowS #

isSupportedFamily :: Family -> Bool Source #

Does the AF_ constant corresponding to the given family exist on this system?

data SocketType Source #

Socket Types.

The existence of a constructor does not necessarily imply that that socket type is supported on your system: see `isSupportedSocketType`.

Constructors

NoSocketType | 0, used in getAddrInfo hints, for example
Stream | SOCK_STREAM
Datagram | SOCK_DGRAM
Raw | SOCK_RAW
RDM | SOCK_RDM
SeqPacket | SOCK_SEQPACKET

Instances

Eq SocketType Source # |
Methods (==) :: SocketType -> SocketType -> Bool # (/=) :: SocketType -> SocketType -> Bool #
Ord SocketType Source # |
Methods compare :: SocketType -> SocketType -> Ordering # (<) :: SocketType -> SocketType -> Bool # (<=) :: SocketType -> SocketType -> Bool # (>) :: SocketType -> SocketType -> Bool # (>=) :: SocketType -> SocketType -> Bool # max :: SocketType -> SocketType -> SocketType # min :: SocketType -> SocketType -> SocketType #
Read SocketType Source # |
Methods readsPrec :: Int -> ReadS SocketType # readList :: ReadS [SocketType] # readPrec :: ReadPrec SocketType # readListPrec :: ReadPrec [SocketType] #
Show SocketType Source # |
Methods showsPrec :: Int -> SocketType -> ShowS # show :: SocketType -> String # showList :: [SocketType] -> ShowS #

isSupportedSocketType :: SocketType -> Bool Source #

Does the SOCK_ constant corresponding to the given SocketType exist on this system?

data SockAddr Source #

The existence of a constructor does not necessarily imply that that socket address type is supported on your system: see `isSupportedSockAddr`.

Constructors

SockAddrInet PortNumber HostAddress |
SockAddrInet6 PortNumber FlowInfo HostAddress6 ScopeID |
SockAddrUnix String |
SockAddrCan Int32 |

Instances

Eq SockAddr Source # |
Methods (==) :: SockAddr -> SockAddr -> Bool # (/=) :: SockAddr -> SockAddr -> Bool #
Ord SockAddr Source # |
Methods compare :: SockAddr -> SockAddr -> Ordering # (<) :: SockAddr -> SockAddr -> Bool # (<=) :: SockAddr -> SockAddr -> Bool # (>) :: SockAddr -> SockAddr -> Bool # (>=) :: SockAddr -> SockAddr -> Bool # max :: SockAddr -> SockAddr -> SockAddr # min :: SockAddr -> SockAddr -> SockAddr #

isSupportedSockAddr :: SockAddr -> Bool Source #

Is the socket address type supported on this system?

data SocketStatus Source #

The status of the socket as determined by this library, not necessarily reflecting the state of the connection itself.

For example, the `Closed` status is applied when the `close` function is called.

Constructors

NotConnected | Newly created, unconnected socket
Bound | Bound, via `bind`
Listening | Listening, via `listen`
Connected | Connected or accepted, via `connect` or `accept`
ConvertedToHandle | Is now a `Handle` (via `socketToHandle`), don't touch
Closed | Closed was closed by `close`

Instances

Eq SocketStatus Source # |
Methods (==) :: SocketStatus -> SocketStatus -> Bool # (/=) :: SocketStatus -> SocketStatus -> Bool #
Show SocketStatus Source # |
Methods showsPrec :: Int -> SocketStatus -> ShowS # show :: SocketStatus -> String # showList :: [SocketStatus] -> ShowS #

type HostAddress = Word32 Source #

The raw network byte order number is read using host byte order. Therefore on little-endian architectures the byte order is swapped. For example `127.0.0.1` is represented as `0x0100007f` on little-endian hosts and as `0x7f000001` on big-endian hosts.

For direct manipulation prefer `hostAddressToTuple` and `tupleToHostAddress`.

hostAddressToTuple :: HostAddress -> (Word8, Word8, Word8, Word8) Source #

Converts `HostAddress` to representation-independent IPv4 quadruple. For example for `127.0.0.1` the function will return `(0x7f, 0, 0, 1)` regardless of host endianness.

tupleToHostAddress :: (Word8, Word8, Word8, Word8) -> HostAddress Source #

Converts IPv4 quadruple to `HostAddress`.

type HostAddress6 = (Word32, Word32, Word32, Word32) Source #

Independent of endianness. For example `::1` is stored as `(0, 0, 0, 1)`.

For direct manipulation prefer `hostAddress6ToTuple` and `tupleToHostAddress6`.

hostAddress6ToTuple :: HostAddress6 -> (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16) Source #

tupleToHostAddress6 :: (Word16, Word16, Word16, Word16, Word16, Word16, Word16, Word16) -> HostAddress6 Source #

type FlowInfo = Word32 Source #

type ScopeID = Word32 Source #

htonl :: Word32 -> Word32 Source #

Converts the from host byte order to network byte order.

ntohl :: Word32 -> Word32 Source #

Converts the from network byte order to host byte order.

data ShutdownCmd Source #

Constructors

ShutdownReceive |
ShutdownSend |
ShutdownBoth |

type ProtocolNumber = CInt Source #

defaultProtocol :: ProtocolNumber Source #

This is the default protocol for a given service.

newtype 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

Constructors

PortNum Word16 | Deprecated: Do not use the PortNum constructor. Use the Num instance. PortNum will be removed in the next release.

Instances

Enum PortNumber Source # |
Methods succ :: PortNumber -> PortNumber # pred :: PortNumber -> PortNumber # toEnum :: Int -> PortNumber # fromEnum :: PortNumber -> Int # enumFrom :: PortNumber -> [PortNumber] # enumFromThen :: PortNumber -> PortNumber -> [PortNumber] # enumFromTo :: PortNumber -> PortNumber -> [PortNumber] # enumFromThenTo :: PortNumber -> PortNumber -> PortNumber -> [PortNumber] #
Eq PortNumber Source # |
Methods (==) :: PortNumber -> PortNumber -> Bool # (/=) :: PortNumber -> PortNumber -> Bool #
Integral PortNumber Source # |
Methods quot :: PortNumber -> PortNumber -> PortNumber # rem :: PortNumber -> PortNumber -> PortNumber # div :: PortNumber -> PortNumber -> PortNumber # mod :: PortNumber -> PortNumber -> PortNumber # quotRem :: PortNumber -> PortNumber -> (PortNumber, PortNumber) # divMod :: PortNumber -> PortNumber -> (PortNumber, PortNumber) # toInteger :: PortNumber -> Integer #
Num PortNumber Source # |
Methods (+) :: PortNumber -> PortNumber -> PortNumber # (-) :: PortNumber -> PortNumber -> PortNumber # (*) :: PortNumber -> PortNumber -> PortNumber # negate :: PortNumber -> PortNumber # abs :: PortNumber -> PortNumber # signum :: PortNumber -> PortNumber # fromInteger :: Integer -> PortNumber #
Ord PortNumber Source # |
Methods compare :: PortNumber -> PortNumber -> Ordering # (<) :: PortNumber -> PortNumber -> Bool # (<=) :: PortNumber -> PortNumber -> Bool # (>) :: PortNumber -> PortNumber -> Bool # (>=) :: PortNumber -> PortNumber -> Bool # max :: PortNumber -> PortNumber -> PortNumber # min :: PortNumber -> PortNumber -> PortNumber #
Read PortNumber Source # |
Methods readsPrec :: Int -> ReadS PortNumber # readList :: ReadS [PortNumber] # readPrec :: ReadPrec PortNumber # readListPrec :: ReadPrec [PortNumber] #
Real PortNumber Source # |
Methods toRational :: PortNumber -> Rational #
Show PortNumber Source # |
Methods showsPrec :: Int -> PortNumber -> ShowS # show :: PortNumber -> String # showList :: [PortNumber] -> ShowS #
Storable PortNumber Source # |
Methods sizeOf :: PortNumber -> Int # alignment :: PortNumber -> Int # peekElemOff :: Ptr PortNumber -> Int -> IO PortNumber # pokeElemOff :: Ptr PortNumber -> Int -> PortNumber -> IO () # peekByteOff :: Ptr b -> Int -> IO PortNumber # pokeByteOff :: Ptr b -> Int -> PortNumber -> IO () # peek :: Ptr PortNumber -> IO PortNumber # poke :: Ptr PortNumber -> PortNumber -> IO () #

# Address operations

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"`.

type ServiceName = String Source #

data AddrInfo Source #

Constructors

AddrInfo |

Fields

- addrFlags :: [AddrInfoFlag]
- addrFamily :: Family
- addrSocketType :: SocketType
- addrProtocol :: ProtocolNumber
- addrAddress :: SockAddr
- addrCanonName :: Maybe String

Instances

Eq AddrInfo Source # |
Methods (==) :: AddrInfo -> AddrInfo -> Bool # (/=) :: AddrInfo -> AddrInfo -> Bool #
Show AddrInfo Source # |
Methods showsPrec :: Int -> AddrInfo -> ShowS # show :: AddrInfo -> String # showList :: [AddrInfo] -> ShowS #
Storable AddrInfo Source # |
Methods sizeOf :: AddrInfo -> Int # alignment :: AddrInfo -> Int # peekElemOff :: Ptr AddrInfo -> Int -> IO AddrInfo # pokeElemOff :: Ptr AddrInfo -> Int -> AddrInfo -> IO () # peekByteOff :: Ptr b -> Int -> IO AddrInfo # pokeByteOff :: Ptr b -> Int -> AddrInfo -> IO () # peek :: Ptr AddrInfo -> IO AddrInfo # poke :: Ptr AddrInfo -> AddrInfo -> IO () #

data AddrInfoFlag Source #

Flags that control the querying behaviour of `getAddrInfo`. For more information, see https://tools.ietf.org/html/rfc3493#page-25

Constructors

AI_ADDRCONFIG | The list of returned `AddrInfo` values will only contain IPv4 addresses if the local system has at least one IPv4 interface configured, and likewise for IPv6. (Only some platforms support this.)
AI_ALL | If `AI_ALL` is specified, return all matching IPv6 and IPv4 addresses. Otherwise, this flag has no effect. (Only some platforms support this.)
AI_CANONNAME | The `addrCanonName` field of the first returned `AddrInfo` will contain the "canonical name" of the host.
AI_NUMERICHOST | The `HostName` argument must be a numeric address in string form, and network name lookups will not be attempted.
AI_NUMERICSERV | The `ServiceName` argument must be a port number in string form, and service name lookups will not be attempted. (Only some platforms support this.)
AI_PASSIVE | If no `HostName` value is provided, the network address in each `SockAddr` will be left as a "wild card", i.e. as either `iNADDR_ANY` or `iN6ADDR_ANY`. This is useful for server applications that will accept connections from any client.
AI_V4MAPPED | If an IPv6 lookup is performed, and no IPv6 addresses are found, IPv6-mapped IPv4 addresses will be returned. (Only some platforms support this.)

Instances

Eq AddrInfoFlag Source # |
Methods (==) :: AddrInfoFlag -> AddrInfoFlag -> Bool # (/=) :: AddrInfoFlag -> AddrInfoFlag -> Bool #
Read AddrInfoFlag Source # |
Methods readsPrec :: Int -> ReadS AddrInfoFlag # readList :: ReadS [AddrInfoFlag] # readPrec :: ReadPrec AddrInfoFlag # readListPrec :: ReadPrec [AddrInfoFlag] #
Show AddrInfoFlag Source # |
Methods showsPrec :: Int -> AddrInfoFlag -> ShowS # show :: AddrInfoFlag -> String # showList :: [AddrInfoFlag] -> ShowS #

addrInfoFlagImplemented :: AddrInfoFlag -> Bool Source #

Indicate whether the given `AddrInfoFlag` will have any effect on this system.

defaultHints :: AddrInfo Source #

Default hints for address lookup with `getAddrInfo`. The values of the `addrAddress` and `addrCanonName` fields are `undefined`, and are never inspected by `getAddrInfo`.

    >>> addrFlags defaultHints
    []
    >>> addrFamily defaultHints
    AF_UNSPEC
    >>> addrSocketType defaultHints
    NoSocketType
    >>> addrProtocol defaultHints
    0

getAddrInfo Source #

Arguments

:: Maybe AddrInfo | preferred socket type or protocol
-> Maybe HostName | host name to look up
-> Maybe ServiceName | service name to look up
-> IO [AddrInfo] | resolved addresses, with "best" first

Resolve a host or service name to one or more addresses. The `AddrInfo` values that this function returns contain `SockAddr` values that you can pass directly to `connect` or `bind`.

This function is protocol independent. It can return both IPv4 and IPv6 address information.

The `AddrInfo` argument specifies the preferred query behaviour, socket options, or protocol. You can override these conveniently using Haskell's record update syntax on `defaultHints`, for example as follows:

    >>> let hints = defaultHints { addrFlags = [AI_NUMERICHOST], addrSocketType = Stream }

You must provide a `Just` value for at least one of the `HostName` or `ServiceName` arguments. `HostName` can be either a numeric network address (dotted quad for IPv4, colon-separated hex for IPv6) or a hostname. In the latter case, its addresses will be looked up unless `AI_NUMERICHOST` is specified as a hint. If you do not provide a `HostName` value and do not set `AI_PASSIVE` as a hint, network addresses in the result will contain the address of the loopback interface.

If the query fails, this function throws an IO exception instead of returning an empty list. Otherwise, it returns a non-empty list of `AddrInfo` values.

There are several reasons why a query might result in several values. For example, the queried-for host could be multihomed, or the service might be available via several protocols.

Note: the order of arguments is slightly different to that defined for `getaddrinfo` in RFC 2553. The `AddrInfo` parameter comes first to make partial application easier.

    >>> addr:_ <- getAddrInfo (Just hints) (Just "127.0.0.1") (Just "http")
    >>> addrAddress addr
    127.0.0.1:80

data NameInfoFlag Source #

Flags that control the querying behaviour of `getNameInfo`. For more information, see https://tools.ietf.org/html/rfc3493#page-30

Constructors

NI_DGRAM | Resolve a datagram-based service name. This is required only for the few protocols that have different port numbers for their datagram-based versions than for their stream-based versions.
NI_NAMEREQD | If the hostname cannot be looked up, an IO error is thrown.
NI_NOFQDN | If a host is local, return only the hostname part of the FQDN.
NI_NUMERICHOST | The name of the host is not looked up. Instead, a numeric representation of the host's address is returned. For an IPv4 address, this will be a dotted-quad string. For IPv6, it will be colon-separated hexadecimal.
NI_NUMERICSERV | The name of the service is not looked up. Instead, a numeric representation of the service is returned.

Instances

Eq NameInfoFlag Source # |
Methods (==) :: NameInfoFlag -> NameInfoFlag -> Bool # (/=) :: NameInfoFlag -> NameInfoFlag -> Bool #
Read NameInfoFlag Source # |
Methods readsPrec :: Int -> ReadS NameInfoFlag # readList :: ReadS [NameInfoFlag] # readPrec :: ReadPrec NameInfoFlag # readListPrec :: ReadPrec [NameInfoFlag] #
Show NameInfoFlag Source # |
Methods showsPrec :: Int -> NameInfoFlag -> ShowS # show :: NameInfoFlag -> String # showList :: [NameInfoFlag] -> ShowS #

getNameInfo Source #

Arguments

:: [NameInfoFlag] | flags to control lookup behaviour
-> Bool | whether to look up a hostname
-> Bool | whether to look up a service name
-> SockAddr | the address to look up
-> IO (Maybe HostName, Maybe ServiceName) |

Resolve an address to a host or service name. This function is protocol independent. The list of `NameInfoFlag` values controls query behaviour.

If a host or service's name cannot be looked up, then the numeric form of the address or service will be returned.

If the query fails, this function throws an IO exception.

Example: `(hostName, _) <- getNameInfo [] True False myAddress`

# Socket operations

socket :: Family -> SocketType -> ProtocolNumber -> IO Socket Source #

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`. If `AF_INET6` is used and the socket type is `Stream` or `Datagram`, the `IPv6Only` socket option is set to 0 so that both IPv4 and IPv6 can be handled with one socket.

    >>> let hints = defaultHints { addrFlags = [AI_NUMERICHOST, AI_NUMERICSERV], addrSocketType = Stream }
    >>> addr:_ <- getAddrInfo (Just hints) (Just "127.0.0.1") (Just "5000")
    >>> sock@(MkSocket _ fam stype _ _) <- socket (addrFamily addr) (addrSocketType addr) (addrProtocol addr)
    >>> fam
    AF_INET
    >>> stype
    Stream
    >>> bind sock (addrAddress addr)
    >>> getSocketName sock
    127.0.0.1:5000

socketPair :: Family -> SocketType -> ProtocolNumber -> IO (Socket, Socket) Source #

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.

connect :: Socket -> SockAddr -> IO () Source #

Connect to a remote socket at address.

bind :: Socket -> SockAddr -> IO () Source #

Bind the socket to an address. The socket must not already be bound. The `Family` passed to `bind` 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.

listen :: Socket -> Int -> IO () Source #

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

accept :: Socket -> IO (Socket, SockAddr) Source #

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.

getPeerName :: Socket -> IO SockAddr Source #

getSocketName :: Socket -> IO SockAddr Source #

getPeerCred :: Socket -> IO (CUInt, CUInt, CUInt) Source #

Returns the processID, userID and groupID of the socket's peer.

Only available on platforms that support SO_PEERCRED or GETPEEREID(3) on domain sockets. GETPEEREID(3) returns userID and groupID. processID is always 0.

socketPort :: Socket -> IO PortNumber Source #

socketToHandle :: Socket -> IOMode -> IO Handle Source #

Turns a Socket into an `Handle`. By default, the new handle is unbuffered. Use `hSetBuffering` to change the buffering.

Note that since a `Handle` is automatically closed by a finalizer when it is no longer referenced, you should avoid doing any more operations on the `Socket` after calling `socketToHandle`. To close the `Socket` after `socketToHandle`, call `hClose` on the `Handle`.

## Sending and receiving data

### Sending and receiving with String

Do not use the `send` and `recv` functions defined in this section in new code, as they incorrectly represent binary data as a Unicode string. As a result, these functions are inefficient and may lead to bugs in the program. Instead use the `send` and `recv` functions defined in the Network.Socket.ByteString module.

send :: Socket -> String -> IO Int Source #

Warning: Use send defined in Network.Socket.ByteString

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.

Sending data to closed socket may lead to undefined behaviour.

sendTo :: Socket -> String -> SockAddr -> IO Int Source #

Warning: Use sendTo defined in Network.Socket.ByteString

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)

recv :: Socket -> Int -> IO String Source #

Warning: Use recv defined in Network.Socket.ByteString

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.

Receiving data from closed socket may lead to undefined behaviour.

recvFrom :: Socket -> Int -> IO (String, Int, SockAddr) Source #

Warning: Use recvFrom defined in Network.Socket.ByteString

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)

recvLen :: Socket -> Int -> IO (String, Int) Source #

Warning: Use recvLen defined in Network.Socket.ByteString

### Sending and receiving with a buffer

sendBuf :: Socket -> Ptr Word8 -> Int -> IO Int Source #

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.

Sending data to closed socket may lead to undefined behaviour.

recvBuf :: Socket -> Ptr Word8 -> Int -> IO Int Source #

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.

Receiving data from closed socket may lead to undefined behaviour.

sendBufTo :: Socket -> Ptr a -> Int -> SockAddr -> IO Int Source #

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.

recvBufFrom :: Socket -> Ptr a -> Int -> IO (Int, SockAddr) Source #

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)

## Misc

inet_addr :: String -> IO HostAddress Source #

inet_ntoa :: HostAddress -> IO String Source #

shutdown :: Socket -> ShutdownCmd -> IO () Source #

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.

close :: Socket -> IO () Source #

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

## Predicates on sockets

isConnected :: Socket -> IO Bool Source #

Determines whether `close` has been used on the `Socket`. This does not indicate any status about the socket beyond this. If the socket has been closed remotely, this function can still return `True`.

isBound :: Socket -> IO Bool Source #

isListening :: Socket -> IO Bool Source #

isReadable :: Socket -> IO Bool Source #

isWritable :: Socket -> IO Bool Source #

# Socket options

data SocketOption Source #

Socket options for use with `setSocketOption` and `getSocketOption`.

The existence of a constructor does not imply that the relevant option is supported on your system: see `isSupportedSocketOption`

Constructors

Debug | SO_DEBUG
ReuseAddr | SO_REUSEADDR
Type | SO_TYPE
SoError | SO_ERROR
DontRoute | SO_DONTROUTE
Broadcast | SO_BROADCAST
SendBuffer | SO_SNDBUF
RecvBuffer | SO_RCVBUF
KeepAlive | SO_KEEPALIVE
OOBInline | SO_OOBINLINE
TimeToLive | IP_TTL
MaxSegment | TCP_MAXSEG
NoDelay | TCP_NODELAY
Cork | TCP_CORK
Linger | SO_LINGER
ReusePort | SO_REUSEPORT
RecvLowWater | SO_RCVLOWAT
SendLowWater | SO_SNDLOWAT
RecvTimeOut | SO_RCVTIMEO
SendTimeOut | SO_SNDTIMEO
UseLoopBack | SO_USELOOPBACK
UserTimeout | TCP_USER_TIMEOUT
IPv6Only | IPV6_V6ONLY
CustomSockOpt (CInt, CInt) |

Instances

Show SocketOption Source # |
Methods showsPrec :: Int -> SocketOption -> ShowS # show :: SocketOption -> String # showList :: [SocketOption] -> ShowS #

isSupportedSocketOption :: SocketOption -> Bool Source #

Does the `SocketOption` exist on this system?

getSocketOption :: Socket -> SocketOption -> IO Int Source #

Get a socket option that gives an Int value. There is currently no API to get e.g. the timeval socket options

setSocketOption :: Socket -> SocketOption -> Int -> IO () Source #

Set a socket option that expects an Int value. There is currently no API to set e.g. the timeval socket options

# File descriptor transmission

sendFd :: Socket -> CInt -> IO () Source #

recvFd :: Socket -> IO CInt Source #

Receive a file descriptor over a domain socket. Note that the resulting file descriptor may have to be put into non-blocking mode in order to be used safely. See `setNonBlockIfNeeded`.

# Special constants

aNY_PORT :: PortNumber Source #

iNADDR_ANY :: HostAddress Source #

The IPv4 wild card address.

iN6ADDR_ANY :: HostAddress6 Source #

The IPv6 wild card address.

sOMAXCONN :: Int Source #

sOL_SOCKET :: Int Source #

sCM_RIGHTS :: Int Source #

maxListenQueue :: Int Source #

This is the value of SOMAXCONN, typically 128. 128 is good enough for normal network servers but is too small for high performance servers.

# Initialisation

withSocketsDo :: IO a -> IO a Source #

With older versions of the `network` library 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 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).

# Very low level operations

fdSocket :: Socket -> CInt Source #

mkSocket :: CInt -> Family -> SocketType -> ProtocolNumber -> SocketStatus -> IO Socket Source #

Smart constructor for constructing a `Socket`. It should only be called once for every new file descriptor. The caller must make sure that the socket is in non-blocking mode. See `setNonBlockIfNeeded`.

setNonBlockIfNeeded :: CInt -> IO () Source #

Set the socket to nonblocking, if applicable to this platform.

Depending on the platform this is required when using sockets from file descriptors that are passed in through `recvFd` or other means.

# Deprecated aliases

These aliases are deprecated and should not be used in new code. They will be removed in some future version of the package.

bindSocket :: Socket -> SockAddr -> IO () Source #

Deprecated: use `bind`

Deprecated alias for `bind`.

sClose :: Socket -> IO () Source #

Deprecated: use `close`

Deprecated alias for `close`.

sIsConnected :: Socket -> IO Bool Source #

Deprecated: use `isConnected`

Deprecated alias for `isConnected`.

sIsBound :: Socket -> IO Bool Source #

Deprecated: use `isBound`

Deprecated alias for `isBound`.

sIsListening :: Socket -> IO Bool Source #

Deprecated: use `isListening`

Deprecated alias for `isListening`.

sIsReadable :: Socket -> IO Bool Source #

Deprecated: use `isReadable`

Deprecated alias for `isReadable`.

sIsWritable :: Socket -> IO Bool Source #

Deprecated: use `isWritable`

Deprecated alias for `isWritable`.

# Internal

The following are exported ONLY for use in the BSD module and should not be used anywhere else.

packFamily :: Family -> CInt Source #

unpackFamily :: CInt -> Family Source #

packSocketType :: SocketType -> CInt Source #

# Orphan instances

Show SockAddr Source # |
Methods showsPrec :: Int -> SockAddr -> ShowS # show :: SockAddr -> String # showList :: [SockAddr] -> ShowS #