Module nativesockets

This module implements a low-level cross-platform sockets interface. Look at the net module for the higher-level version.

Exports

WSAEWOULDBLOCK, WSAECONNRESET, WSAECONNABORTED, WSAENETRESET, WSANOTINITIALISED, WSAENOTSOCK, WSAEINPROGRESS, WSAEINTR, WSAEDISCON, ERROR_NETNAME_DELETED, SocketHandle, Sockaddr_in, AddrInfo, INADDR_ANY, SockAddr, SockLen, Sockaddr_in6, Sockaddr_storage, inet_ntoa, recv, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, connect, send, accept, recvfrom, sendto, freeaddrinfo, SO_ERROR, SOL_SOCKET, SOMAXCONN, SO_ACCEPTCONN, SO_BROADCAST, SO_DEBUG, SO_DONTROUTE, SO_KEEPALIVE, SO_OOBINLINE, SO_REUSEADDR, SO_REUSEPORT, MSG_PEEK

Imports

os, options, winlean

Types

Port = distinct uint16

port type

Domain = enum
  AF_UNSPEC = 0, ## unspecified domain (can be detected automatically by
              ## some procedures, such as getaddrinfo)
  AF_UNIX = 1,                  ## for local socket (using a file). Unsupported on Windows.
  AF_INET = 2,                  ## for network protocol IPv4 or
  AF_INET6 = when defined(macosx):
    30
   else:
    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.

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

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

Servent = object
  name*: string
  aliases*: seq[string]
  port*: Port
  proto*: string

information about a service

Hostent = object
  name*: string
  aliases*: seq[string]
  addrtype*: Domain
  length*: int
  addrList*: seq[string]

information about a given host

Lets

osInvalidSocket = INVALID_SOCKET

Consts

IOCPARM_MASK = 127

IOC_IN = -2147483648

FIONBIO = -2147195266

Procs

proc ioctlsocket(s: SocketHandle; cmd: clong; argptr: ptr clong): cint {...}{.stdcall,
    importc: "ioctlsocket", dynlib: "ws2_32.dll".}

proc `==`(a, b: Port): bool {...}{.borrow.}

== for ports.

proc `$`(p: Port): string {...}{.borrow.}

returns the port number as a string

proc toInt(domain: Domain): cint {...}{.raises: [], tags: [].}

Converts the Domain enum to a platform-dependent cint.

proc toKnownDomain(family: cint): Option[Domain] {...}{.raises: [], tags: [].}

Converts the platform-dependent cint to the Domain or none(), if the cint is not known.

proc toInt(typ: SockType): cint {...}{.raises: [], tags: [].}

Converts the SockType enum to a platform-dependent cint.

proc toInt(p: Protocol): cint {...}{.raises: [], tags: [].}

Converts the Protocol enum to a platform-dependent cint.

proc toSockType(protocol: Protocol): SockType {...}{.raises: [], tags: [].}

proc createNativeSocket(domain: Domain = AF_INET; sockType: SockType = SOCK_STREAM;
                       protocol: Protocol = IPPROTO_TCP): SocketHandle {...}{.raises: [],
    tags: [].}

Creates a new socket; returns osInvalidSocket if an error occurs.

proc createNativeSocket(domain: cint; sockType: cint; protocol: cint): SocketHandle {...}{.
    raises: [], tags: [].}

Creates a new socket; returns osInvalidSocket if an error occurs.

Use this overload if one of the enums specified above does not contain what you need.

proc newNativeSocket(domain: Domain = AF_INET; sockType: SockType = SOCK_STREAM;
                    protocol: Protocol = IPPROTO_TCP): SocketHandle {...}{.deprecated,
    raises: [], tags: [].}

Creates a new socket; returns osInvalidSocket if an error occurs.

Deprecated since v0.18.0: Use createNativeSocket instead.

proc newNativeSocket(domain: cint; sockType: cint; protocol: cint): SocketHandle {...}{.
    deprecated, raises: [], tags: [].}

Creates a new socket; returns osInvalidSocket if an error occurs.

Use this overload if one of the enums specified above does not contain what you need.

Deprecated since v0.18.0: Use createNativeSocket instead.

proc close(socket: SocketHandle) {...}{.raises: [], tags: [].}

closes a socket.

proc bindAddr(socket: SocketHandle; name: ptr SockAddr; namelen: SockLen): cint {...}{.
    raises: [], tags: [].}

proc listen(socket: SocketHandle; backlog = SOMAXCONN): cint {...}{.tags: [ReadIOEffect],
    raises: [].}

Marks socket as accepting connections. Backlog specifies the maximum length of the queue of pending connections.

proc getAddrInfo(address: string; port: Port; domain: Domain = AF_INET;
                sockType: SockType = SOCK_STREAM; protocol: Protocol = IPPROTO_TCP): ptr AddrInfo {...}{.
    raises: [OSError], tags: [].}

Warning: The resulting ptr AddrInfo must be freed using freeAddrInfo!

proc dealloc(ai: ptr AddrInfo) {...}{.deprecated, raises: [], tags: [].}

Deprecated since 0.16.2. Use freeAddrInfo instead.

proc ntohl(x: uint32): uint32 {...}{.raises: [], tags: [].}

Converts 32-bit unsigned 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.

proc ntohs(x: uint16): uint16 {...}{.raises: [], tags: [].}

Converts 16-bit unsigned 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.

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.

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.

proc getHostByAddr(ip: string): Hostent {...}{.tags: [ReadIOEffect], raises: [OSError].}

This function will lookup the hostname of an IP Address.

proc getHostByName(name: string): Hostent {...}{.tags: [ReadIOEffect], raises: [OSError].}

This function will lookup the IP address of a hostname.

proc getHostname(): string {...}{.tags: [ReadIOEffect], raises: [OSError].}

Returns the local hostname (not the FQDN)

proc getSockDomain(socket: SocketHandle): Domain {...}{.raises: [OSError, IOError], tags: [].}

returns the socket's domain (AF_INET or AF_INET6).

proc getAddrString(sockAddr: ptr SockAddr): string {...}{.
    raises: [Exception, OSError, IOError], tags: [RootEffect].}

return the string representation of address within sockAddr

proc getSockName(socket: SocketHandle): Port {...}{.raises: [OSError], tags: [].}

returns the socket's associated port number.

proc getLocalAddr(socket: SocketHandle; domain: Domain): (string, Port) {...}{.
    raises: [OSError, Exception], tags: [RootEffect].}

returns the socket's local address and port number.

Similar to POSIX's getsockname.

proc getPeerAddr(socket: SocketHandle; domain: Domain): (string, Port) {...}{.
    raises: [OSError, Exception], tags: [RootEffect].}

returns the socket's peer address and port number.

Similar to POSIX's getpeername

proc getSockOptInt(socket: SocketHandle; level, optname: int): int {...}{.
    tags: [ReadIOEffect], raises: [OSError].}

getsockopt for integer options.

proc setSockOptInt(socket: SocketHandle; level, optname, optval: int) {...}{.
    tags: [WriteIOEffect], raises: [OSError].}

setsockopt for integer options.

proc setBlocking(s: SocketHandle; blocking: bool) {...}{.raises: [OSError], tags: [].}

Sets blocking mode on socket.

Raises EOS on error.

proc select(readfds: var seq[SocketHandle]; timeout = 500): int {...}{.
    deprecated: "use selectRead instead", raises: [], tags: [].}

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

timeout is specified in milliseconds and -1 can be specified for an unlimited time. Warning: This is deprecated since version 0.16.2. Use the selectRead procedure instead.

proc selectRead(readfds: var seq[SocketHandle]; timeout = 500): int {...}{.raises: [], tags: [].}

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

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

proc selectWrite(writefds: var seq[SocketHandle]; 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 can be written to will also be removed from writefds.

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

proc accept(fd: SocketHandle): (SocketHandle, string) {...}{.raises: [], tags: [].}

Accepts a new client connection.

Returns (osInvalidSocket, "") if an error occurred.

Templates

template ntohl(x: int32): untyped {...}{.deprecated.}

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. Warning: This template is deprecated since 0.14.0, IPv4 addresses are now treated as unsigned integers. Please use the unsigned version of this template.

template ntohs(x: int16): untyped {...}{.deprecated.}

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. Warning: This template is deprecated since 0.14.0, where port numbers became unsigned integers. Please use the unsigned version of this template.

template htonl(x: int32): untyped {...}{.deprecated.}

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. Warning: This template is deprecated since 0.14.0, IPv4 addresses are now treated as unsigned integers. Please use the unsigned version of this template.

template htonl(x: uint32): untyped

Converts 32-bit unsigned 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.

template htons(x: int16): untyped {...}{.deprecated.}

Converts 16-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 2-byte swap operation. Warning: This template is deprecated since 0.14.0, where port numbers became unsigned integers. Please use the unsigned version of this template.

template htons(x: uint16): untyped

Converts 16-bit unsigned 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.