RingSockets Extension
In this chapter we will learn about using the RingSockets extension.
TCP Server
Example (TCP Server Code):
load "sockets.ring"
sock = socket(AF_INET,SOCK_STREAM,0)
setsockopt(sock,SOL_SOCKET,SO_REUSEADDR,1)
bind(sock,"127.0.0.1",5050)
listen(sock,5)
ns = accept(sock)
send(ns,"Hello Client")
msg = recv(ns,1024)
? "Client Say >> " + msg
close(ns)
close(sock)
? "socket connection closed"
TCP Client
Example (TCP Client Code):
load "sockets.ring"
sock = socket(AF_INET,SOCK_STREAM)
connect(sock,"127.0.0.1",5050)
send(sock,"Hello Server")
msg = recv(sock,1024)
? "Server Say >> " + msg
close(sock)
? "socket connection closed"
UDP Echo Server
recvfrom stores the sender address, so sendto can reply without
passing a destination.
Example (UDP Echo Server Code):
load "sockets.ring"
sock = socket(AF_INET,SOCK_DGRAM,0)
bind(sock,"127.0.0.1",9090)
while true
msg = recvfrom(sock,1024)
? "client >> " + msg
sendto(sock,"echo: " + msg)
end
close(sock)
UDP Client
connect on a UDP socket only sets the default destination, so
send/recv can be used instead of sendto/recvfrom.
Example (UDP Client Code):
load "sockets.ring"
sock = socket(AF_INET,SOCK_DGRAM,0)
if connect(sock,"127.0.0.1",9090) = 0
send(sock,"hello udp")
? "server >> " + recv(sock,1024)
ok
close(sock)
Non-blocking I/O and select()
A socket set non-blocking never blocks in send/recv/accept.
Use select() to wait until sockets are ready, and socklasterror()
to detect the temporary “would block” condition.
Example (using socketpair so no second process is needed):
load "sockets.ring"
sp = socketpair(AF_UNIX,SOCK_STREAM,0)
s1 = sp[1]
s2 = sp[2]
setnonblocking(s1,1)
setnonblocking(s2,1)
send(s1,"ping")
# wait (up to 1 second) until s2 is ready to read
r = []
add(r,s2)
ready = select(r,[],[],1)
? len(ready[1]) # 1
? recv(s2,100) # ping
d = recv(s2,100) # nothing left to read
? isnull(d) # 1 = would block
? socklasterror() = SOCK_EWOULDBLOCK # 1
close(s1)
close(s2)
Utility Functions
Example (byte order, address conversion, getsockopt, getpeername, shutdownsocket):
load "sockets.ring"
? htons(80) # host -> network byte order
? ntohs(htons(80)) # back -> 80
packed = inet_addr("127.0.0.1") # 4 binary bytes
? inet_ntoa(packed) # 127.0.0.1
server = socket(AF_INET,SOCK_STREAM,0)
setsockopt(server,SOL_SOCKET,SO_REUSEADDR,1)
? getsockopt(server,SOL_SOCKET,SO_TYPE) # 1 = SOCK_STREAM
bind(server,"127.0.0.1",5060)
listen(server,1)
client = socket(AF_INET,SOCK_STREAM,0)
connect(client,"127.0.0.1",5060)
conn = accept(server)
? getpeername(client) # 127.0.0.1 , 5060
shutdownsocket(client,SHUT_RDWR)
? recv(conn,100) # "" = peer closed
close(conn)
close(client)
close(server)
socketsCleanup()
Functions
The next functions are provided by this extension
socket(nAddressFamily, nConnectionType [, nProtocol]) -> SocketHandle
socketfd(pSocketHandle) -> nFileDescriptor
setsockopt(pSocketHandle, nLevel, nOptionName, nValue)
getsockopt(pSocketHandle, nLevel, nOptionName) -> nOptionValue
bind(pSocketHandle, cHost , nPort)
listen(pSocketHandle [, nBacklog]) # nBacklog default = 5
accept(pSocketHandle) -> pConnectionHandle
send(pConnectionHandle|pSocketHandle, cMessage [, nFlags]) -> nBytesSent
sendto(pSocketHandle, cMessage [, nFlags] | cHost, nPort [, nFlags]) -> nBytesSent
recv(pConnectionHandle|pSocketHandle, nBuffer [, nFlags]) -> cData
recvfrom(pSocketHandle, nBuffer [, nFlags]) -> cData
connect(pSocketHandle, cHost , nPort) -> return <0> if successful
close(pSocketHandle|pConnectionHandle)
shutdownsocket(pSocketHandle, nHow) -> nHow = SHUT_RD | SHUT_WR | SHUT_RDWR
setnonblocking(pSocketHandle, nFlag) -> nFlag = 1 (non-blocking) or 0 (blocking)
select(pReadList, pWriteList, pExceptList [, nTimeout]) -> list of 3 lists
socklasterror() -> nLastSocketErrorCode
getaddrinfo(cHost, cService [, nFamily]) -> list of {family, socktype, protocol, ip, port}
getsockname(pSocketHandle) -> list of {ip, port}
getpeername(pSocketHandle) -> list of {ip, port}
socketpair([nFamily, nType, nProtocol]) -> list of two SocketHandles (on Windows the arguments are ignored and a TCP loopback pair is returned)
getprotobyname(cName) -> nProtocolNumber
gethostbyname(cHostName) -> cIPAddress
gethostbyaddr(cIPAddress) -> aListOfHostInfo
gethostname() -> cHostName
getservbyname(cName) -> nPort
getservbyport(nPort) -> cName
ntohs(nNetshort) -> nHostshort
htons(nHostshort) -> nNetshort
htonl(nHostlong) -> nNetlong
ntohl(nNetlong) -> nHostlong
inet_addr(cIP) -> packed_address (4 binary bytes)
inet_ntoa(packed_address) -> cIP
inet_pton(AdressFamily, IP) -> packed_address
inet_ntop(AdressFamily, packed_address) -> IP
socketsCleanup()
Notes:
send/sendtoreturn the number of bytes sent and raise an error on failure.recv/recvfromreturn the received data and raise an error on failure.The optional
nFlagsparameter accepts theMSG_*constants (see below).sendtomay be called with an explicit destination (cHost, nPort); otherwise it replies to the lastrecvfromsource or aconnected socket.socketfdreturns the underlying operating-system file descriptor of the socket, useful when interoperating with other extensions.With
setnonblocking(sock, 1),send/recv/sendto/recvfrom/acceptdo not block. On a temporary “would block” condition they return without error; checksocklasterror():recv/recvfrom/acceptreturn NULL (nothing),send/sendtoreturn-2, andsocklasterror() == SOCK_EWOULDBLOCKmeans “retry afterselect()”. An empty string fromrecv/recvfrommeans the peer closed the connection.
Example:
load "sockets.ring"
host = gethostbyname("google.com")
? host
line()
? gethostbyaddr(host)
line()
? gethostname()
line()
? getservbyname("ftp")
line()
? getservbyport(21)
func line ? copy("=",30)
Constants
Protocol Families:
PF_UNSPEC
PF_UNIX
PF_INET
PF_INET6
Address Family:
AF_UNSPEC
AF_UNIX
AF_INET # mean use IPV4
AF_INET6 # ........ IPV6
Connection type:
SOCK_STREAM # mean use TCP Protocol
SOCK_DGRAM # ........ UDP ........
SOCK_RAW
SOCK_RDM
SOCK_SEQPACKET
Protocols:
IPPROTO_IP
IPPROTO_TCP
IPPROTO_UDP
IPPROTO_RAW
IPPROTO_ICMP
IPPROTO_IGMP
IPPROTO_SCTP # returns -1 on Windows
Levels (for setsockopt / getsockopt):
SOL_SOCKET
IPPROTO_IP
IPPROTO_TCP
IPPROTO_UDP
Socket Options (SOL_SOCKET level):
SO_DEBUG
SO_ACCEPTCONN
SO_BROADCAST
SO_DONTROUTE
SO_ERROR
SO_KEEPALIVE
SO_LINGER
SO_OOBINLINE
SO_RCVBUF
SO_REUSEADDR
SO_SNDBUF
SO_TYPE
SO_RCVLOWAT
SO_SNDLOWAT
SO_RCVTIMEO
SO_SNDTIMEO
SO_EXCLUSIVEADDRUSE # Windows only, -1 elsewhere
SO_NOSIGPIPE # macOS/BSD, -1 elsewhere
SO_REUSEPORT # Linux/BSD/macOS, -1 on Windows
IP Option Names (IPPROTO_IP level):
IP_ADD_MEMBERSHIP
IP_ADD_SOURCE_MEMBERSHIP
IP_BLOCK_SOURCE
IP_DROP_MEMBERSHIP
IP_DROP_SOURCE_MEMBERSHIP
IP_HDRINCL
IP_MULTICAST_LOOP
IP_MULTICAST_TTL
IP_OPTIONS
IP_RECVTOS
IP_RECVTTL
IP_TOS
IP_TTL
IP_UNBLOCK_SOURCE
TCP Socket Options (IPPROTO_TCP level):
TCP_NODELAY
TCP_KEEPIDLE # -1 where unsupported
TCP_KEEPINTVL # -1 where unsupported
TCP_KEEPCNT # -1 where unsupported
Message Flags (for send / recv / sendto / recvfrom):
MSG_OOB
MSG_PEEK
MSG_WAITALL
MSG_DONTWAIT # Linux/BSD/macOS, -1 on Windows
Shutdown Flags (for shutdownsocket):
SHUT_RD
SHUT_WR
SHUT_RDWR
Error Codes:
SOCK_EWOULDBLOCK # portable code for "try again" (EAGAIN / WSAEWOULDBLOCK)