# nativesockets

Dark Mode

- Manual
- Standard library
- Index
- devel, stable

Search:
Group by:

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

# Imports

os, options, winlean

# Types

    Port = distinct uint16

  port type Source Edit

    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. Source Edit

    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 Edit

    Protocol = enum
      IPPROTO_TCP = 6,          ## Transmission control protocol.
      IPPROTO_UDP = 17,         ## User datagram protocol.
      IPPROTO_IP,               ## Internet protocol.
      IPPROTO_IPV6,             ## Internet Protocol Version 6.
      IPPROTO_RAW,              ## Raw IP Packets Protocol. Unsupported on Windows.
      IPPROTO_ICMP,             ## Internet Control message protocol.
      IPPROTO_ICMPV6             ## Internet Control message protocol for IPv6.

  third argument to `socket` proc Source Edit

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

  information about a service Source Edit

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

  information about a given host Source Edit

# Lets

    osInvalidSocket = INVALID_SOCKET

  Source Edit

# Consts

    IOCPARM_MASK = 127

  Source Edit

    IOC_IN = -2147483648

  Source Edit

    FIONBIO = -2147195266'i32

  Source Edit

# Procs

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

  Source Edit

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

  `==` for ports. Source Edit

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

  Returns the port number as a string Source Edit

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

  Converts the Domain enum to a platform-dependent `cint`. Source Edit

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

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

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

  Converts the SockType enum to a platform-dependent `cint`. Source Edit

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

  Converts the Protocol enum to a platform-dependent `cint`. Source Edit

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

  Source Edit

    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. Source Edit

    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.

  Source Edit

    proc newNativeSocket(domain: Domain = AF_INET; sockType: SockType = SOCK_STREAM;
                         protocol: Protocol = IPPROTO_TCP): SocketHandle {...}{.
        deprecated: "deprecated since v0.18.0; use \'createNativeSocket\' instead",
        raises: [], tags: [].}

  Deprecated: deprecated since v0.18.0; use 'createNativeSocket' instead
  Creates a new socket; returns `osInvalidSocket` if an error occurs. Source Edit

    proc newNativeSocket(domain: cint; sockType: cint; protocol: cint): SocketHandle {...}{.
        deprecated: "deprecated since v0.18.0; use \'createNativeSocket\' instead",
        raises: [], tags: [].}

  Deprecated: deprecated since v0.18.0; use 'createNativeSocket' instead

  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.

  Source Edit

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

  closes a socket. Source Edit

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

  Source Edit

    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. Source Edit

    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`!

  Source Edit

    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. Source Edit

    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. Source Edit

    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 Edit

    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 Edit

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

  This function will lookup the hostname of an IP Address. Source Edit

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

  This function will lookup the IP address of a hostname. Source Edit

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

  Returns the local hostname (not the FQDN) Source Edit

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

  Returns the socket's domain (AF_INET or AF_INET6). Source Edit

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

  Returns the string representation of address within sockAddr Source Edit

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

  Returns the socket's associated port number. Source Edit

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

  Returns the socket's local address and port number.

  Similar to POSIX's getsockname.

  Source Edit

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

  Returns the socket's peer address and port number.

  Similar to POSIX's getpeername

  Source Edit

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

  getsockopt for integer options. Source Edit

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

  setsockopt for integer options. Source Edit

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

  Sets blocking mode on socket.

  Raises OSError on error.

  Source Edit

    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.

  Source Edit

    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.

  Source Edit

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

  Accepts a new client connection.

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

  Source Edit

# Templates

    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. Source Edit

    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. Source Edit

# 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