úÎ!„æ|âh      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg Safe "&'.9;Hd#] socketspRepresents any unexpected behaviors that a function working on a socket, connection, or listener can exhibit.sockets½The datagram did not fit in the buffer. This can happen while sending. The field is the size of the number of bytes in the datagram that were successfully copied into the send buffer.sockets¶The datagram did not fit in the buffer. This can happen while receiving. The field is the original size of the datagram that was was truncated while copying it into the buffer.socketsŒThe socket address was not the expected size. This exception indicates a bug in this library or (less likely) in the operating system.socketsÑThe socket address had an unexpected family. This exception indicates a bug in this library or (less likely) in the operating system. The int argument is the actual family found in the socket address.socketsŠThe option value was not the expected size. This exception indicates a bug in this library or (less likely) in the operating system.socketsQThe user requested a negative number of bytes in a call to a receive function.socketsThis happens when the Unless* variant of a function is used and the STM; action completes before the socket is ready for a read.socketsIThe remote end sent more data when it was expected to send a shutdown. socketsWThe remote end has shutdown its side of the full-duplex connection. This can happen receiveÿ is called on a stream socket. This is not necessarily a bad thing. Many protocols use shutdown to indicate that no more data is available. These protocols can be contrasted with protocols that send a length representing a number of expected bytes. sockets¥Any error code from the operating system that this library does not expect or recognize. Consult your operating system manual for details about the error code.'hijkl mno pqrstuvwxyz{|}~€Safe$0‚None "$&'.19;Hd= socketslRecoverable exceptions that happen when establishing an internet-domain stream listener or datagram socket. DiscussionJThe recoverable exceptions that we from stream sockets (established with socket-bind-listen*) and datagram sockets (established with socket-bind€) are the exact same exceptions. Consequently, we reuse the same type in both case. It is a little unfortunate since the name ListenException_ would be more appropriate for stream sockets. But the code reuse is worth the naming quibble.socketsŞThe address is protected, and the user is not the superuser. This most commonly happens when trying to bind to a port below 1024. On Linux, When it is necessary to bind to such a port on Linux, consider using the  8http://man7.org/linux/man-pages/man7/capabilities.7.htmlCAP_NET_BIND_SERVICE8 capability instead of running the process as root. (EACCES)sockets&The given address is already in use. ( EADDRINUSE with specified port)socketsÅThe port number was specified as zero, but upon attempting to bind to an ephemeral port, it was determined that all port numbers numbers in the ephemeral port range are currently in use. ( EADDRINUSE with unspecified port)socketsA limit on the number of open file descriptors has been reached. This could be the per-process limit or the system limit. (EMFILE and ENFILE)sockets An endpoint for an IPv4 socket, connection, or listener. Everything is in host byte order, and the user is not responisble for performing any conversions. ƒNone9;?zsocketsuA connectionless datagram socket that may communicate with many different endpoints on a datagram-by-datagram basis.None"$F_dNIsockets»Receive up to the specified number of datagrams into freshly allocated byte arrays. When there are many datagrams present on the receive buffer, this is more efficient than calling receiveE repeatedly. The array is guaranteed to have at least one message.<The byte arrays in the resulting messages are always pinned.socketsThis has the same behavior as . However, it also takes an „Ö action that it attempts to run while the event manager is waiting for the socket to be ready for a reads. If the supplied action finishes first, this abandons the attempt to receive datagrams and returns … .socketsSocketsockets&Maximum number of datagrams to receivesockets(Maximum size of each datagram to receivesockets'If this completes, give up on receivingsocketsSocketsockets&Maximum number of datagrams to receivesockets(Maximum size of each datagram to receive None&'.19;HWâ†socketsÇThe datagram did not fit in the buffer. The field is the original size of the datagram that was truncated. If this happens, the process probably needs to start using a larger receive buffer.‡sockets7STM-style interrupt (much safer than C-style interrupt) sockets¹The datagram did not fit in the buffer. The field is the number of bytes that were successfully copied into the send buffer. The datagram does still get sent when this happens.!sockets)Attempted to send to a broadcast address."sockets7STM-style interrupt (much safer than C-style interrupt) ˆ†‡ !"None "$.9;F_doş#socketsæOpen a socket and run the supplied callback on it. This closes the socket when the callback finishes or when an exception is thrown. Do not return the socket from the callback. This leads to undefined behavior. If the address 0.0.0.0ú is used, the socket receives on all network interfaces. If the port 0 is used, an unused port is chosen by the operating system. The callback provides the chosen port (or if the user specified a non-zero port, the chosen port will be that value).$sockets6Send a slice of a bytearray to the specified endpoint.%sockets6Send a slice of a bytearray to the specified endpoint.&sockets6Receive a datagram into a freshly allocated bytearray.'sockets®Receive a datagram into a mutable byte array, ignoring information about the remote endpoint. Returns the actual number of bytes present in the datagram. Precondition: -buffer_length - offset >= max_datagram_length.#socketsAddress and port to usesockets1Callback providing the socket and the chosen port$socketsSocketsocketsRemote IPv4 address and portsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLenth of slice into buffer%socketsSocketsocketsRemote IPv4 address and portsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLenth of slice into buffer&socketsSocketsockets#Maximum size of datagram to receive'socketsSocketsocketsBuffersocketsOffset into buffersockets#Maximum size of datagram to receive #$%&'#$%&' None"$&'.19;FH_d)socketsRPermission to create a raw socket was denied. The process needs the capability  CAP_NET_RAW, or it must be run as root.*socketsA limit on the number of open file descriptors has been reached. This could be the per-process limit or the system limit. (EMFILE and ENFILE)+sockets\A socket that send datagrams with spoofed source IP addresses. It cannot receive datagrams.-socketsÿ#Open a socket and run the supplied callback on it. This closes the socket when the callback finishes or when an exception is thrown. Do not return the socket from the callback. This leads to undefined behavior. The user cannot specify an endpoint since the socket cannot receive traffic..sockets6Send a slice of a bytearray to the specified endpoint.-socketsCallback providing the socket.socketsSocketsocketsSpoofed source address and portsocketsRemote IPv4 address and portsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLenth of slice into buffer !"()*+,-.+,-.()* !" None&'.19;H×(4socketsORecoverable exceptions that can occur while receiving data on a stream socket. DiscussionThe  0http://man7.org/linux/man-pages/man2/recv.2.html recv man page explicitly documents these: EAGAIN/EAGAIN1: Not possible after using event manager to wait.EBADF: Prevented by this library. ECONNREFUSEDS: Not sure if this is possible. Currently treated as an unrecoverable exception.EFAULT,: Not recoverable. API consumer has misused Addr.EINTR=: Prevented by this library. Unsafe FFI is not interruptible.EINVAL: Prevented by this library.ENOMEM: Not recoverable.ENOTCONN: Prevented by this library.ENOTSOCK: Prevented by this library.±The man page includes a disclaimer: "Additional errors may be generated and returned from the underlying protocol modules". One such error when dealing with stream sockets in  ECONNRESET¦. One scenario where this happens is when the process running on the peer terminates ungracefully and the operating system on the peer cleans up by sending a reset.5sockets:The peer shutdown its writing channel. (zero-length chunk)6sockets The peer reset the connection. ( ECONNRESET)7sockets7STM-style interrupt (much safer than C-style interrupt)9sockets›The local socket has already shutdown its writing channel. Consequently, sending is no longer possible. This can happen even if the process does not shutdown' the socket. If the peer decides to closee the connection, the local operating system will shutdown both the reading and writing channels. (EPIPE):socketsThe peer reset the connection.;sockets7STM-style interrupt (much safer than C-style interrupt)<socketsMRecoverable exceptions that can occur while accepting an inbound connection.=sockets¥The peer reset the connection before the running process accepted it. This is not typically treated as fatal. The process may continue accepting connections. ( ECONNABORTED)>socketsA limit on the number of open file descriptors has been reached. This could be the per-process limit or the system limit. (EMFILE and ENFILE)?sockets#Firewall rules forbid connection. (EPERM)@sockets7STM-style interrupt (much safer than C-style interrupt)BsocketsÿFAfter the local process shut down the writing channel, it was expecting the peer to do the same. However, the peer sent more data instead. If this happens, the local process does still close the socket. However, it must send a TCP reset to accomplish this since there is still unread data in the receive buffer.HThis can happen if the peer is misbehaving or if the consumer of the socketsU API has incorrectly implemented a protocol living above layer 4 of the OSI model.Csockets£Recoverable exceptions that can occur while connecting to a peer. This includes both failures while opening the socket and failures while connecting to the peer. DiscussionÿIn its API for connecting to a peer, this library combines the step of creating a socket with the step of connecting to the peer. In other words, the end user never gets access to an unconnected stream socket. Consequently, the connection exceptions correspond to the socket errors EMFILE and ENFILE as well as the connect errors  ECONNREFUSED, EACCES/EPERM,  ETIMEDOUT,  ENETUNREACH, and  EADDRNOTAVAIL.Somewhat surprisingly,  EADDRINUSE is not included in the list of connect0 error codes we recognize as recoverable. The  3http://man7.org/linux/man-pages/man2/connect.2.htmlaccept man page describes  EADDRINUSE^ as "Local address is already in use". However, it is unclear what this means. The caller of connectQ does not provide an internet socket address. If ephemeral ports are exhausted, connect will error with  EADDRNOTAVAIL. An unresolved  _https://stackoverflow.com/questions/43199021/how-could-connect-fail-and-set-errno-to-eaddrinuseStack Overflow questionä calls into question whether or not it is actually possible for this error to happen with an internet domain socket. The author has decided to omit any checks for it. This means that, if it does ever happen, it will cause a SocketUnrecoverableException¢ to be thrown. The Linux cognoscenti are encouraged to open an issue if they have more information about the circumstances under which this exception can occur.DsocketsÆEither the connection was blocked by a local firewall rule or it was blocked because it was to a broadcast address. Sadly, these two errors are not distinguished by the Linux sockets API. (EACCES/EPERM)EsocketsA limit on the number of open file descriptors has been reached. This could be the per-process limit or the system limit. (EMFILE and ENFILE)FsocketsThe network is unreachable. ( ENETUNREACH)GsocketsOAll port numbers numbers in the ephemeral port range are currently in use. ( EADDRNOTAVAIL)Hsockets,No one is listening on the remote address. ( ECONNREFUSED)Isockets˜Timeout while attempting connection. The server may be too busy to accept new connections. Note that stock Linux configuration has timeout at  ^http://willbryant.net/overriding_the_default_linux_kernel_20_second_tcp_socket_connect_timeoutappropriately 20 secondsJ. Users interested in timing out more quickly are encouraged to use  registerDelay with the  interruptible; variants of the connection functions in this library. ( ETIMEDOUT)Jsockets7STM-style interrupt (much safer than C-style interrupt)47568;9:<=>?@ABCDEFGHIJNone "$&'.FSX_dzŞKsockets$A connection-oriented stream socket.Lsockets0A socket that listens for incomming connections.MsocketsPOpen a socket that can be used to listen for inbound connections. Requirements:LThis function may only be called in contexts where exceptions are masked. The caller must be sure to call  unlistener on the resulting L2 exactly once to close underlying file descriptor.The L7 cannot be used after being given as an argument to  unlistener.GNoncompliant use of this function leads to undefined behavior. Prefer PK unless you are writing an integration with a resource-management library.Nsockets[Close a listener. This throws an unrecoverable exception if the socket cannot be closed.Osockets½Close a listener. This does not check to see whether or not the operating system successfully closed the socket. It never throws exceptions of any kind. This should only be preferred to  unlistenerv in exception-cleanup contexts where there is already an exception that will be rethrown. See the implementation of P, for an example of appropriate use of both  unlistener and  unlistener_.Qsockets!Listen for an inbound connection.RsocketsPListen for an inbound connection. Can be interrupted by an STM-style interrupt.SsocketsÿDAccept a connection on the listener and run the supplied callback on it. This closes the connection when the callback finishes or if an exception is thrown. Since this function blocks the thread until the callback finishes, it is only suitable for stream socket clients that handle one connection at a time. The variant U\ is preferrable for servers that need to handle connections concurrently (most use cases).Tsockets[Accept a connection on the listener and run the supplied callback in a new thread. Prefer Ur unless the masking state needs to be preserved for the callback. Such a situation seems unlikely to the author.UsocketspAccept a connection on the listener and run the supplied callback in a new thread. The masking state is set to Unmasked( when running the callback. Typically, a is instantiated to ().VsocketspAccept a connection on the listener and run the supplied callback in a new thread. The masking state is set to Unmasked( when running the callback. Typically, a is instantiated to (). Discussion Why is the counterÿH argument present? At first, it seems like this is something that the API consumer should implement on top of this library. The argument for the inclusion of the counter is has two parts: (1) clients supporting graceful termination always need these semantics and (2) these semantics cannot be provided without building in counter as a TVar. ÿ¢Clients supporting graceful termination always need these semantics. To gracefully bring down a server that has been accepting connections with a forking function, an application must wait for all active connections to finish. Since all connections run on separate threads, this can only be accomplished by a concurrency primitive. The straightforward solution is to wrap a counter with either MVar or TVarf. To complete graceful termination, the application must block until the counter reaches zero.;These semantics cannot be provided without building in counter as a TVar. When abandon becomes Trueÿ, graceful termination begins. From this point onward, if at any point the counter reaches zero, the application consuming this API will complete termination. Consequently, we need the guarantee that the counter does not increment after the abandonÿI transaction completes. If it did increment in this forbidden way (e.g. if it was incremented some unspecified amount of time after a connection was accepted), there would be a race condition in which the application may terminate without giving the newly accepted connection a chance to finish. Fortunately, STMv gives us the composable transaction we need to get this guarantee. To wait for an inbound connection, we use: Î(isReady,deregister) <- threadWaitReadSTM fd shouldReceive <- atomically $ do readTVar abandon >>= \case True -> do isReady modifyTVar' counter (+1) pure True False -> pure FalseThis eliminates the window for the race condition. If a connection is accepted, the counter is guaranteed to be incremented _before_ abandon becomes True{. However, this code would be more simple and would perform better if GHC's event manager used TVar instead of STM.Wsockets2Open a socket and connect to a peer. Requirements:LThis function may only be called in contexts where exceptions are masked. The caller must be sure to call X or Y on the resulting K5 exactly once to close underlying file descriptor.The K7 cannot be used after being given as an argument to X or Y.GNoncompliant use of this function leads to undefined behavior. Prefer ZK unless you are writing an integration with a resource-management library.Xsockets+Close a connection gracefully, reporting a A_ when the connection has to be terminated by sending a TCP reset. This uses a combination of shutdown, recv, close( to detect when resets need to be sent.YsocketsyClose a connection. This does not check to see whether or not the connection was brought down gracefully. It just calls closeb and is likely to cause a TCP reset to be sent. It never throws exceptions of any kind (even if close, fails). This should only be preferred to Xv in exception-cleanup contexts where there is already an exception that will be rethrown. See the implementation of Z, for an example of appropriate use of both X and Y.Zsockets#Establish a connection to a server.bsocketsªReceive exactly the given number of bytes. If the remote application shuts down its end of the connection before sending the required number of bytes, this returns … 5.csockets Variant of b# that support STM-style interrupts.dsocketsÑReceive a number of bytes exactly equal to the size of the mutable byte array. If the remote application shuts down its end of the connection before sending the required number of bytes, this returns … ( Receive RemoteShutdown).esocketscReceive up to the given number of bytes, using the given array and starting at the given offset.fsockets—Receive up to the given number of bytes, using the given array and starting at the given offset. This can be interrupted by the completion of an „ transaction.gsocketsœReceive up to the given number of bytes. If the remote application shuts down its end of the connection instead of sending any bytes, this returns … ( Receive RemoteShutdown).RsocketsInterrupted. If this becomes ‰ give up and return … @.Ssockets(Callback to handle an ungraceful close. sockets?Callback to consume connection. Must not return the connection.Tsockets(Callback to handle an ungraceful close. sockets?Callback to consume connection. Must not return the connection.Usockets(Callback to handle an ungraceful close. sockets?Callback to consume connection. Must not return the connection.VsocketsgConnection counter. Incremented when connection is accepted. Decremented after connection is closed.socketsInterrupted. If this becomes ‰ give up and return … @.socketsConnection listenersockets(Callback to handle an ungraceful close. sockets?Callback to consume connection. Must not return the connection.WsocketsRemote endpointZsocketsRemote endpointsockets(Callback to handle an ungraceful close. sockets?Callback to consume connection. Must not return the connection.[sockets ConnectionsocketsPayload\socketsInterrupted. If this becomes ‰, give up and return … @.sockets ConnectionsocketsPayload]sockets ConnectionsocketsPayload (will be sliced)socketsOffset into payloadsocketsLength of slice into buffer^socketsInterrupted. If this becomes ‰, give up and return … @.sockets ConnectionsocketsPayload (will be sliced)socketsOffset into payloadsocketsLength of slice into buffer_sockets ConnectionsocketsBuffer (will be sliced)`sockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into bufferasocketsInterrupted. If this becomes ‰ give up and return … @.sockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into bufferŠsocketsInterrupted. If this becomes ‰ give up and return … @.sockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into buffer‹sockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into bufferŒsockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into buffersockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into buffersockets Alivenesssockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into buffersockets ConnectionsocketsBuffer (will be sliced)socketsOffset into payloadsocketsLength of slice into buffersockets Connectionsockets"Maximum number of bytes to receivesocketsReceive buffersocketsOffset into buffer‘sockets'If this completes, give up on receivingsockets Connectionsockets"Maximum number of bytes to receivesocketsReceive buffersocketsOffset into bufferbsockets ConnectionsocketsNumber of bytes to receivecsocketsInterrupted. If this becomes ‰ give up and return … 7.sockets ConnectionsocketsNumber of bytes to receiveesockets Connectionsockets"Maximum number of bytes to receivesockets/Buffer in which the data are going to be storedsocketsOffset in the buffersockets5Either a socket exception or the number of bytes readfsocketsInterrupted. If this becomes ‰ give up and return … 7.sockets Connectionsockets"Maximum number of bytes to receivesockets/Buffer in which the data are going to be storedsocketsOffset in the buffersockets5Either a socket exception or the number of bytes readgsockets Connectionsockets"Maximum number of bytes to receive@ 47568;9:<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg@LKPSZTUV[]_`\^abgedcf8;9:4756CDEFGHIJ<=>?@AB MNOWXYQR’      !"#$ % & ' ()*+,- )./0123 4 5 6 7 % 8 9 ( : ; < = > ? @ A B C D E F G HIJKLMNOPQRSTUVWXYZ[\.+],^_`abccdefghijklmnopqrstuvwxyz{|}~€~‚ ƒ 7 4„…†‡ˆ‰Š‹Œ&sockets-0.3.0.0-Ggm3p1ojN4EAq7GgMQYSvySocket.Datagram.IPv4.UndestinedSocket.Stream.IPv4Socket.Datagram.IPv4.SpoofSocket Socket.Debug Socket.IPv4(Socket.Datagram.IPv4.Undestined.Internal(Socket.Datagram.IPv4.Undestined.MultipleSocket.Datagram Socket.StreamSocketExceptionSentMessageTruncatedReceivedMessageTruncatedSocketAddressSizeSocketAddressFamilyOptionValueSizeNegativeBytesRequestedReceptionAbandonedRemoteNotShutdownRemoteShutdown ErrorCodeInterruptibility InterruptibleUninterruptibleSocketPermissionDeniedSocketAddressInUseSocketEphemeralPortsExhaustedSocketFileDescriptorLimitEndpoint$sel:address:Endpoint$sel:port:EndpointMessageremotepayload receiveManyreceiveManyUnless SendException SendTruncatedSendBroadcastedSendInterrupted withSocketsendsendMutableByteArraySlicereceiveByteArrayreceiveMutableByteArraySlice_sendMutableByteArray $fEqSocket $fOrdSocket $fShowSocket$fExceptionSocketException$fShowSocketExceptionReceiveExceptionReceiveShutdown ReceiveResetReceiveInterrupted SendShutdown SendResetAcceptExceptionAcceptConnectionAbortedAcceptFileDescriptorLimitAcceptFirewalledAcceptInterruptedCloseExceptionClosePeerContinuedSendingConnectExceptionConnectFirewalledConnectFileDescriptorLimitConnectNetworkUnreachableConnectEphemeralPortsExhaustedConnectRefusedConnectTimeoutConnectInterrupted ConnectionListenerlistenunlisten unlisten_ withListeneracceptinterruptibleAccept withAccepted forkAcceptedforkAcceptedUnmasked!interruptibleForkAcceptedUnmaskedconnect disconnect disconnect_withConnection sendByteArrayinterruptibleSendByteArraysendByteArraySliceinterruptibleSendByteArraySlice&interruptibleSendMutableByteArraySliceinterruptibleReceiveByteArrayreceiveMutableByteArray#receiveBoundedMutableByteArraySlice0interruptibleReceiveBoundedMutableByteArraySlicereceiveBoundedByteArraySocketUnrecoverableException)$sel:modules:SocketUnrecoverableException*$sel:function:SocketUnrecoverableException-$sel:description:SocketUnrecoverableException ForkednessForkedUnforked DirectionSendReceive cgetsockname cgetsockoptcclosecrecv crecvfrom cshutdownfunctionGracefulClosenonInternetSocketFamilynegativeSliceLengthfunctionWithAcceptedfunctionWithConnectionfunctionWithListenerfunctionWithSocketsocketAddressSizedebug whenDebuggingdescribeEndpointbase GHC.Conc.SyncSTM Data.EitherLeftReceiveTruncatedghc-prim GHC.TypesTrue internalInterruptibleSendMutableinternalSendMutableveryInternalSendMutable internalSendinternalInterruptibleSendveryInternalSendinternalReceiveMaximally%internalInterruptibleReceiveMaximally