This module implements a low-level cross-platform sockets interface. Look at the net module for the higher-level version.
Types
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
Procs
proc ioctlsocket(s: SocketHandle; cmd: clong; argptr: ptr clong): cint {. stdcall, importc: "ioctlsocket", dynlib: "ws2_32.dll".}
- Source
proc `==`(a, b: Port): bool {.borrow.}
- == for ports. Source
proc `$`(p: Port): string {.borrow.}
- returns the port number as a string Source
proc toInt(domain: Domain): cint {.raises: [], tags: [].}
- Converts the TDomain enum to a platform-dependent cint. Source
proc toInt(typ: SockType): cint {.raises: [], tags: [].}
- Converts the TType enum to a platform-dependent cint. Source
proc toInt(p: Protocol): cint {.raises: [], tags: [].}
- Converts the TProtocol enum to a platform-dependent cint. Source
proc newRawSocket(domain: Domain = AF_INET; typ: SockType = SOCK_STREAM; protocol: Protocol = IPPROTO_TCP): SocketHandle {.raises: [], tags: [].}
- Creates a new socket; returns InvalidSocket if an error occurs. Source
proc newRawSocket(domain: cint; typ: cint; protocol: cint): SocketHandle {. raises: [], tags: [].}
-
Creates a new socket; returns InvalidSocket if an error occurs.
Use this overload if one of the enums specified above does not contain what you need.
Source proc close(socket: SocketHandle) {.raises: [], tags: [].}
- closes a socket. Source
proc bindAddr(socket: SocketHandle; name: ptr SockAddr; namelen: SockLen): cint {. raises: [], tags: [].}
- Source
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
proc getAddrInfo(address: string; port: Port; af: Domain = AF_INET; typ: SockType = SOCK_STREAM; prot: Protocol = IPPROTO_TCP): ptr AddrInfo {. raises: [OSError], tags: [].}
-
SourceWarning: The resulting ptr TAddrInfo must be freed using dealloc!
proc dealloc(ai: ptr AddrInfo) {.raises: [], tags: [].}
- 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 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 getSockName(socket: SocketHandle): Port {.raises: [OSError], tags: [].}
- returns the socket's associated port number. Source
proc getSockOptInt(socket: SocketHandle; level, optname: int): int {. tags: [ReadIOEffect], raises: [OSError].}
- getsockopt for integer options. Source
proc setSockOptInt(socket: SocketHandle; level, optname, optval: int) {. tags: [WriteIOEffect], raises: [OSError].}
- setsockopt for integer options. Source
proc setBlocking(s: SocketHandle; blocking: bool) {.raises: [OSError], tags: [].}
-
Sets blocking mode on socket.
Raises EOS on error.
Source proc select(readfds: var seq[SocketHandle]; timeout = 500): int {.raises: [], tags: [].}
-
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.
A socket is removed from the specific seq when it has data waiting to be read/written to or has errors (exceptfds).
Source 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 miliseconds and -1 can be specified for an unlimited time.
Source