Module sockets

Warning: Since version 0.10.2 this module is deprecated. Use the net or the rawsockets module instead.

This module implements portable sockets, it supports a mix of different types of sockets. Sockets are buffered by default meaning that data will be received in BufferSize (4000) sized chunks, buffering behaviour can be disabled by setting the buffered parameter when calling the socket function to false. Be aware that some functions may not yet support buffered sockets (mainly the recvFrom function).

Most procedures raise OSError on error, but some may return -1 or a boolean false.

SSL is supported through the OpenSSL library. This support can be activated by compiling with the -d:ssl switch. When an SSL socket is used it will raise ESSL exceptions when SSL errors occur.

Asynchronous sockets are supported, however a better alternative is to use the asyncio module.

Types

Socket = ref TSocketImpl
  Source
Port = distinct uint16
port type   Source
Domain = enum 
  AF_UNIX,                    ## for local socket (using a file). Unsupported on Windows.
  AF_INET = 2,                ## for network protocol IPv4 or
  AF_INET6 = 23               ## for network protocol IPv6.
domain, which specifies the protocol family of the created socket. Other domains than those that are listed here are unsupported.   Source
SockType = enum 
  SOCK_STREAM = 1,            ## reliable stream-oriented service or Stream Sockets
  SOCK_DGRAM = 2,             ## datagram service or Datagram Sockets
  SOCK_RAW = 3,               ## raw protocols atop the network layer.
  SOCK_SEQPACKET = 5          ## reliable sequenced packet service
second argument to socket proc   Source
Protocol = enum 
  IPPROTO_TCP = 6,            ## Transmission control protocol. 
  IPPROTO_UDP = 17,           ## User datagram protocol.
  IPPROTO_IP,                 ## Internet protocol. Unsupported on Windows.
  IPPROTO_IPV6,               ## Internet Protocol Version 6. Unsupported on Windows.
  IPPROTO_RAW,                ## Raw IP Packets Protocol. Unsupported on Windows.
  IPPROTO_ICMP                ## Control message protocol. Unsupported on Windows.
third argument to socket proc   Source
Servent = object 
  name*: string
  aliases*: seq[string]
  port*: Port
  proto*: string
information about a service   Source
Hostent = object 
  name*: string
  aliases*: seq[string]
  addrtype*: Domain
  length*: int
  addrList*: seq[string]
information about a given host   Source
SOBool = enum 
  OptAcceptConn, OptBroadcast, OptDebug, OptDontRoute, OptKeepAlive, 
  OptOOBInline, OptReuseAddr
Boolean socket options.   Source
RecvLineResult = enum 
  RecvFullLine, RecvPartialLine, RecvDisconnected, RecvFail
result for recvLineAsync   Source
ReadLineResult = enum 
  ReadFullLine, ReadPartialLine, ReadDisconnected, ReadNone
result for readLineAsync   Source
TimeoutError = object of Exception
  Source

Consts

BufferSize: int = 4000
size of a buffered socket's buffer   Source
invalidSocket: Socket = nil
invalid socket   Source

Procs

proc `==`(a, b: Port): bool {.borrow.}
== for ports.   Source
proc `$`(p: Port): string {.borrow.}
returns the port number as a string   Source
proc ntohl(x: int32): int32 {.raises: [], tags: [].}
Converts 32-bit integers from network to host byte order. On machines where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 4-byte swap operation.   Source
proc ntohs(x: int16): int16 {.raises: [], tags: [].}
Converts 16-bit integers from network to host byte order. On machines where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 2-byte swap operation.   Source
proc htonl(x: int32): int32 {.raises: [], tags: [].}
Converts 32-bit integers from host to network byte order. On machines where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 4-byte swap operation.   Source
proc htons(x: int16): int16 {.raises: [], tags: [].}
Converts 16-bit positive integers from host to network byte order. On machines where the host byte order is the same as network byte order, this is a no-op; otherwise, it performs a 2-byte swap operation.   Source
proc socket(domain: Domain = AF_INET; typ: SockType = SOCK_STREAM; 
            protocol: Protocol = IPPROTO_TCP; buffered = true): Socket {.
    raises: [], tags: [].}
Creates a new socket; returns InvalidSocket if an error occurs.   Source
proc raiseSocketError(socket: Socket; err: int = - 1; async = false) {.
    raises: [OSError], tags: [].}

Raises proper errors based on return values of recv functions.

If async is True no error will be thrown in the case when the error was caused by no data being available to be read.

If err is not lower than 0 no exception will be raised.

  Source
proc listen(socket: Socket; backlog = SOMAXCONN) {.tags: [ReadIOEffect], 
    raises: [OSError].}
Marks socket as accepting connections. Backlog specifies the maximum length of the queue of pending connections.   Source
proc parseIp4(s: string): BiggestInt {.raises: [OverflowError, ValueError], 
                                       tags: [].}

parses an IP version 4 in dotted decimal form like "a.b.c.d".

This is equivalent to inet_ntoa.

Raises EInvalidValue in case of an error.

  Source
proc bindAddr(socket: Socket; port = Port(0); address = "") {.
    tags: [ReadIOEffect], raises: [OSError].}
binds an address/port number to a socket. Use address string in dotted decimal form like "a.b.c.d" or leave "" for any address.   Source
proc getSockName(socket: Socket): Port {.raises: [OSError], tags: [].}
returns the socket's associated port number.   Source
proc acceptAddr(server: Socket; client: var Socket; address: var string) {.
    tags: [ReadIOEffect], raises: [OSError].}

Blocks until a connection is being made from a client. When a connection is made sets client to the client socket and address to the address of the connecting client. If server is non-blocking then this function returns immediately, and if there are no connections queued the returned socket will be InvalidSocket. This function will raise EOS if an error occurs.

The resulting client will inherit any properties of the server socket. For example: whether the socket is buffered or not.

Note: client must be initialised (with new), this function makes no effort to initialise the client variable.

Warning: When using SSL with non-blocking sockets, it is best to use the acceptAddrSSL procedure as this procedure will most likely block.

  Source
proc accept(server: Socket; client: var Socket) {.tags: [ReadIOEffect], 
    raises: [OSError].}

Equivalent to acceptAddr but doesn't return the address, only the socket.

Note: client must be initialised (with new), this function makes no effort to initialise the client variable.

  Source
proc acceptAddr(server: Socket): tuple[client: Socket, address: string] {.
    deprecated, tags: [ReadIOEffect], raises: [OSError].}

Slightly different version of acceptAddr.

Deprecated since version 0.9.0: Please use the function above.

  Source
proc accept(server: Socket): Socket {.deprecated, tags: [ReadIOEffect], 
                                      raises: [OSError].}
Deprecated since version 0.9.0: Please use the function above.   Source
proc close(socket: Socket) {.raises: [], tags: [].}
closes a socket.   Source
proc getServByName(name, proto: string): Servent {.tags: [ReadIOEffect], 
    raises: [OSError].}

Searches the database from the beginning and finds the first entry for which the service name specified by name matches the s_name member and the protocol name specified by proto matches the s_proto member.

On posix this will search through the /etc/services file.

  Source
proc getServByPort(port: Port; proto: string): Servent {.tags: [ReadIOEffect], 
    raises: [OSError].}

Searches the database from the beginning and finds the first entry for which the port specified by port matches the s_port member and the protocol name specified by proto matches the s_proto member.

On posix this will search through the /etc/services file.

  Source
proc getHostByAddr(ip: string): Hostent {.tags: [ReadIOEffect], 
    raises: [OSError].}
This function will lookup the hostname of an IP Address.   Source
proc getHostByName(name: string): Hostent {.tags: [ReadIOEffect], 
    raises: [OSError].}
This function will lookup the IP address of a hostname.   Source
proc getSockOptInt(socket: Socket; level, optname: int): int {.
    tags: [ReadIOEffect], raises: [OSError].}
getsockopt for integer options.   Source
proc setSockOptInt(socket: Socket; level, optname, optval: int) {.
    tags: [WriteIOEffect], raises: [OSError].}
setsockopt for integer options.   Source
proc getSockOpt(socket: Socket; opt: SOBool; level = SOL_SOCKET): bool {.
    tags: [ReadIOEffect], raises: [OSError].}
Retrieves option opt as a boolean value.   Source
proc setSockOpt(socket: Socket; opt: SOBool; value: bool; level = SOL_SOCKET) {.
    tags: [WriteIOEffect], raises: [OSError].}
Sets option opt to a boolean value specified by value.   Source
proc connect(socket: Socket; address: string; port = Port(0); 
             af: Domain = AF_INET) {.tags: [ReadIOEffect], raises: [OSError].}

Connects socket to address:port. Address can be an IP address or a host name. If address is a host name, this function will try each IP of that host name. htons is already performed on port so you must not do it.

If socket is an SSL socket a handshake will be automatically performed.

  Source
proc connectAsync(socket: Socket; name: string; port = Port(0); 
                  af: Domain = AF_INET) {.tags: [ReadIOEffect], 
    raises: [OSError].}

A variant of connect for non-blocking sockets.

This procedure will immediately return, it will not block until a connection is made. It is up to the caller to make sure the connection has been established by checking (using select) whether the socket is writeable.

Note: For SSL sockets, the handshake procedure must be called whenever the socket successfully connects to a server.

  Source
proc hasDataBuffered(s: Socket): bool {.raises: [], tags: [].}
Determines whether a socket has data buffered.   Source
proc select(readfds, writefds, exceptfds: var seq[Socket]; timeout = 500): int {.
    tags: [ReadIOEffect], raises: [].}

Traditional select function. This function will return the number of sockets that are ready to be read from, written to, or which have errors. If there are none; 0 is returned. Timeout is in miliseconds and -1 can be specified for no timeout.

Sockets which are not ready for reading, writing or which don't have errors waiting on them are removed from the readfds, writefds, exceptfds sequences respectively.

  Source
proc select(readfds, writefds: var seq[Socket]; timeout = 500): int {.
    tags: [ReadIOEffect], raises: [].}
Variant of select with only a read and write list.   Source
proc selectWrite(writefds: var seq[Socket]; timeout = 500): int {.
    tags: [ReadIOEffect], raises: [].}

When a socket in writefds is ready to be written to then a non-zero value will be returned specifying the count of the sockets which can be written to. The sockets which cannot be written to will also be removed from writefds.

timeout is specified in miliseconds and -1 can be specified for an unlimited time.

  Source
proc select(readfds: var seq[Socket]; timeout = 500): int {.raises: [], tags: [].}
variant of select with a read list only   Source
proc recv(socket: Socket; data: pointer; size: int): int {.tags: [ReadIOEffect], 
    raises: [].}

Receives data from a socket.

Note: This is a low-level function, you may be interested in the higher level versions of this function which are also named recv.

  Source
proc recv(socket: Socket; data: pointer; size: int; timeout: int): int {.
    tags: [ReadIOEffect, TimeEffect], raises: [TimeoutError, OSError].}
overload with a timeout parameter in miliseconds.   Source
proc recv(socket: Socket; data: var string; size: int; timeout = - 1): int {.
    raises: [TimeoutError, OSError], tags: [ReadIOEffect, TimeEffect].}

Higher-level version of recv.

When 0 is returned the socket's connection has been closed.

This function will throw an EOS exception when an error occurs. A value lower than 0 is never returned.

A timeout may be specified in miliseconds, if enough data is not received within the time specified an ETimeout exception will be raised.

Note: data must be initialised.

  Source
proc recvAsync(socket: Socket; data: var string; size: int): int {.
    raises: [OSError], tags: [ReadIOEffect].}

Async version of recv.

When socket is non-blocking and no data is available on the socket, -1 will be returned and data will be "".

Note: data must be initialised.

  Source
proc recvLine(socket: Socket; line: var TaintedString; timeout = - 1): bool {.
    tags: [ReadIOEffect, TimeEffect], deprecated, 
    raises: [TimeoutError, OSError].}

Receive a line of data from socket.

If a full line is received \r\L is not added to line, however if solely \r\L is received then line will be set to it.

True is returned if data is available. False suggests an error, EOS exceptions are not raised and False is simply returned instead.

If the socket is disconnected, line will be set to "" and True will be returned.

A timeout can be specified in miliseconds, if data is not received within the specified time an ETimeout exception will be raised.

Deprecated since version 0.9.2: This function has been deprecated in favour of readLine.

  Source
proc readLine(socket: Socket; line: var TaintedString; timeout = - 1) {.
    tags: [ReadIOEffect, TimeEffect], raises: [TimeoutError, OSError].}

Reads a line of data from socket.

If a full line is read \r\L is not added to line, however if solely \r\L is read then line will be set to it.

If the socket is disconnected, line will be set to "".

An EOS exception will be raised in the case of a socket error.

A timeout can be specified in miliseconds, if data is not received within the specified time an ETimeout exception will be raised.

  Source
proc recvLineAsync(socket: Socket; line: var TaintedString): RecvLineResult {.
    tags: [ReadIOEffect], deprecated, raises: [].}

Similar to recvLine but designed for non-blocking sockets.

The values of the returned enum should be pretty self explanatory:

  • If a full line has been retrieved; RecvFullLine is returned.
  • If some data has been retrieved; RecvPartialLine is returned.
  • If the socket has been disconnected; RecvDisconnected is returned.
  • If call to recv failed; RecvFail is returned.

Deprecated since version 0.9.2: This function has been deprecated in favour of readLineAsync.

  Source
proc readLineAsync(socket: Socket; line: var TaintedString): ReadLineResult {.
    tags: [ReadIOEffect], raises: [OSError].}

Similar to recvLine but designed for non-blocking sockets.

The values of the returned enum should be pretty self explanatory:

  • If a full line has been retrieved; ReadFullLine is returned.
  • If some data has been retrieved; ReadPartialLine is returned.
  • If the socket has been disconnected; ReadDisconnected is returned.
  • If no data could be retrieved; ReadNone is returned.
  • If call to recv failed; an EOS exception is raised.

  Source
proc recv(socket: Socket): TaintedString {.tags: [ReadIOEffect], deprecated, 
    raises: [OSError].}

receives all the available data from the socket. Socket errors will result in an EOS error. If socket is not a connectionless socket and socket is not connected "" will be returned.

Deprecated since version 0.9.2: This function is not safe for use.

  Source
proc recvTimeout(socket: Socket; timeout: int): TaintedString {.
    tags: [ReadIOEffect], deprecated, raises: [TimeoutError, OSError].}

overloaded variant to support a timeout parameter, the timeout parameter specifies the amount of miliseconds to wait for data on the socket.

Deprecated since version 0.9.2: This function is not safe for use.

  Source
proc recvAsync(socket: Socket; s: var TaintedString): bool {.
    tags: [ReadIOEffect], deprecated, raises: [OSError].}

receives all the data from a non-blocking socket. If socket is non-blocking and there are no messages available, False will be returned. Other socket errors will result in an EOS error. If socket is not a connectionless socket and socket is not connected s will be set to "".

Deprecated since version 0.9.2: This function is not safe for use.

  Source
proc recvFrom(socket: Socket; data: var string; length: int; 
              address: var string; port: var Port; flags = 0'i32): int {.
    tags: [ReadIOEffect], raises: [].}

Receives data from socket. This function should normally be used with connection-less sockets (UDP sockets).

If an error occurs the return value will be -1. Otherwise the return value will be the length of data received.

Warning: This function does not yet have a buffered implementation, so when socket is buffered the non-buffered implementation will be used. Therefore if socket contains something in its buffer this function will make no effort to return it.

  Source
proc recvFromAsync(socket: Socket; data: var string; length: int; 
                   address: var string; port: var Port; flags = 0'i32): bool {.
    tags: [ReadIOEffect], raises: [OSError].}

Variant of recvFrom for non-blocking sockets. Unlike recvFrom, this function will raise an EOS error whenever a socket error occurs.

If there is no data to be read from the socket False will be returned.

  Source
proc skip(socket: Socket) {.tags: [ReadIOEffect], deprecated, 
                            raises: [Exception].}

skips all the data that is pending for the socket

Deprecated since version 0.9.2: This function is not safe for use.

  Source
proc skip(socket: Socket; size: int; timeout = - 1) {.
    raises: [Exception, TimeoutError, OSError], tags: [TimeEffect, ReadIOEffect].}

Skips size amount of bytes.

An optional timeout can be specified in miliseconds, if skipping the bytes takes longer than specified an ETimeout exception will be raised.

Returns the number of skipped bytes.

  Source
proc send(socket: Socket; data: pointer; size: int): int {.
    tags: [WriteIOEffect], raises: [].}
sends data to a socket.   Source
proc send(socket: Socket; data: string) {.tags: [WriteIOEffect], 
    raises: [ValueError, OSError].}
sends data to a socket.   Source
proc sendAsync(socket: Socket; data: string): int {.tags: [WriteIOEffect], 
    raises: [OSError].}

sends data to a non-blocking socket. Returns 0 if no data could be sent, if data has been sent returns the amount of bytes of data that was successfully sent. This number may not always be the length of data but typically is.

An EOS (or ESSL if socket is an SSL socket) exception is raised if an error occurs.

  Source
proc trySend(socket: Socket; data: string): bool {.tags: [WriteIOEffect], 
    raises: [].}
safe alternative to send. Does not raise an EOS when an error occurs, and instead returns false on failure.   Source
proc sendTo(socket: Socket; address: string; port: Port; data: pointer; 
            size: int; af: Domain = AF_INET; flags = 0'i32): int {.
    tags: [WriteIOEffect], raises: [OSError].}

low-level sendTo proc. This proc sends data to the specified address, which may be an IP address or a hostname, if a hostname is specified this function will try each IP of that hostname.

Note: This proc is not available for SSL sockets.

  Source
proc sendTo(socket: Socket; address: string; port: Port; data: string): int {.
    tags: [WriteIOEffect], raises: [OSError].}
Friendlier version of the low-level sendTo.   Source
proc setBlocking(s: Socket; blocking: bool) {.tags: [], gcsafe, 
    raises: [OSError].}
Sets blocking mode on socket   Source
proc connect(socket: Socket; address: string; port = Port(0); timeout: int; 
             af: Domain = AF_INET) {.tags: [ReadIOEffect, WriteIOEffect], 
                                     raises: [OSError, TimeoutError].}

Connects to server as specified by address on port specified by port.

The timeout paremeter specifies the time in miliseconds to allow for the connection to the server to be made.

  Source
proc isSSL(socket: Socket): bool {.raises: [], tags: [].}
Determines whether socket is a SSL socket.   Source
proc getFD(socket: Socket): SocketHandle {.raises: [], tags: [].}
Returns the socket's file descriptor   Source
proc isBlocking(socket: Socket): bool {.raises: [], tags: [].}
Determines whether socket is blocking.   Source