# std/nativesockets

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

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

# Imports

os, options, since, strbasics, assertions, syncio, winlean

# Types

    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 = 10

  domain, which specifies the protocol family of the created socket. Other domains than those that are listed here are unsupported. Source Edit

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

  information about a given host Source Edit

    Port = distinct uint16

  port type 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

    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

# Lets

    osInvalidSocket = INVALID_SOCKET

  Source Edit

# Consts

    FIONBIO = -2147195266'i32

  Source Edit

    IOC_IN = -2147483648

  Source Edit

    IOCPARM_MASK = 127

  Source Edit

    IPPROTO_NONE = IPPROTO_IP

  Use this if your socket type requires a protocol value of zero (e.g. Unix sockets). Source Edit

# Procs

    proc `$`(p: Port): string {.borrow, ...raises: [], tags: [], forbids: [].}

  Returns the port number as a string Source Edit

    proc `==`(a, b: Port): bool {.borrow, ...raises: [], tags: [], forbids: [].}

  `==` for ports. Source Edit

    proc accept(fd: SocketHandle; inheritable = defined(nimInheritHandles)): (
        SocketHandle, string) {....raises: [], tags: [], forbids: [].}

  Accepts a new client connection.

  `inheritable` decides if the resulting SocketHandle can be inherited by child processes.

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

  Source Edit

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

  Source Edit

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

  Closes a socket. Source Edit

    proc createNativeSocket(domain: cint; sockType: cint; protocol: cint;
                            inheritable: bool = defined(nimInheritHandles)): SocketHandle {.
        ...raises: [], tags: [], forbids: [].}

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

  `inheritable` decides if the resulting SocketHandle can be inherited by child processes.

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

  Source Edit

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

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

  `inheritable` decides if the resulting SocketHandle can be inherited by child processes.

  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: [], forbids: [].}

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

    proc getAddrInfo(address: string; port: Port; hints: AddrInfo): ptr AddrInfo {.
        ...raises: [OSError], tags: [], forbids: [].}

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

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

  Returns the string representation of address within sockAddr Source Edit

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

  Stores in `strAddress` the string representation of the address inside `sockAddr`

  Note

  - `strAddress` must be initialized to 46 in length.
  Source Edit

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

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

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

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

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

  Returns the local hostname (not the FQDN) Source Edit

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

  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: [], forbids: [].}

  Returns the socket's peer address and port number.

  Similar to POSIX's getpeername

  Source Edit

    proc getProtoByName(name: string): int {....raises: [OSError], tags: [],
        forbids: [].}

  Returns a protocol code from the database that matches the protocol `name`. Source Edit

    proc getServByName(name, proto: string): Servent {....tags: [ReadIOEffect],
        raises: [OSError], forbids: [].}

  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], forbids: [].}

  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 getSockDomain(socket: SocketHandle): Domain {....raises: [OSError, IOError],
        tags: [], forbids: [].}

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

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

  Returns the socket's associated port number. Source Edit

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

  getsockopt for integer options. Source Edit

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

  Source Edit

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

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

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

  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: [], forbids: [].}

  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 selectRead(readfds: var seq[SocketHandle]; timeout = 500): int {.
        ...raises: [], tags: [], forbids: [].}

  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 cannot 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: [], forbids: [].}

  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 milliseconds and `-1` can be specified for an unlimited time.

  Source Edit

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

  Sets blocking mode on socket.

  Raises OSError on error.

  Source Edit

    proc setInheritable(s: SocketHandle; inheritable: bool): bool {.inline,
        ...raises: [], tags: [], forbids: [].}

  Set whether a socket is inheritable by child processes. Returns `true` on success.

  This function is not implemented on all platform, test for availability with `declared() <system.html#declared,untyped>`.

  Source Edit

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

  setsockopt for integer options. Source Edit

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

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

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

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

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

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

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

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

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

  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, recv, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, connect, send, accept, recvfrom, sendto, freeAddrInfo, inet_ntoa, SO_ERROR, SOL_SOCKET, SOMAXCONN, SO_ACCEPTCONN, SO_BROADCAST, SO_DEBUG, SO_DONTROUTE, SO_KEEPALIVE, SO_OOBINLINE, SO_REUSEADDR, SO_REUSEPORT, MSG_PEEK