Docs4dev
Docs
nim / latest / nativesockets.html

std/nativesockets

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, 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 = 23
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

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 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, recv, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, ==, connect, send, 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

© 2006–2024 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/nativesockets.html