This module provides an interface to the POSIX socket functions. Use
require("socket") to load it.
Create a communications socket
FD_Type socket (domain, type, protocol)
The socket function creates a communications socket of the
specified domain, type, and protocol. Currently supported domains
include PF_UNIX and PF_INET. The various socket types
may be specified by the symbolic constants
SOCK_STREAM
SOCK_DGRAM
SOCK_SEQPACKET
SOCK_RAW
SOCK_RDM
protocol parameter specifies the protocol to be used.
Normally only one protocol is support for a particular domain. For
such cases, 0 should be passed for the protocol parameter.
If successful, the socket function will return a
file-descriptor that may be used with the read and
write function, or passed to other socket related functions.
Upon error, a SocketError exception will be thrown and
errno set accordingly.
When finished with the socket, it should be passed to the
close function.
The following example illustrates the creation of a socket for use in the internet domain:
try {
s = socket (PF_INET, SOCK_STREAM, 0);
}
catch SocketError: {
() = fprintf (stderr, "socket failed: %s", errno_string(errno));
exit (1);
}
accept, bind, connect, listen, setsockopt, getsockopt
Make a connection to a socket
connect (FD_Type s, address-args)
The connect function may be used to connect a socket s
to the address specified by the address-arguments. The type and
number of the address arguments must be consistent with the domain
of the socket. For example, if the socket is in the Unix domain
(PF_UNIX), then a single string giving a filename must be passed as
the address-argument. Sockets in the internet domain (PF_INET) take two
address arguments: a hostname and a port.
Upon failure, the function may throw a SocketError exception and set
errno, or throw a SocketHError and set h_error.
It should be noted that SocketHError is a subclass of
SocketError.
The following example creates an internet domain socket and connects it to port 32100 of a specified host:
try {
s = socket (PF_INET, SOCK_STREAM, 0);
connect (s, "some.host.com", 32100);
}
catch SocketHError: {...}
catch SocketError: {...}
accept, bind, listen, socket, setsockopt, getsockopt
Bind a local address-name to a socket
bind (FD_Type s, address-args)
The bind function may be used to assign a name to a specified
socket. The address-args parameters specify the name in a
domain-specific manner. For Unix domain sockets, the address is the
name of a file. For sockets in the internet domain, the address is
given by a hostname and port number.
Upon failure, the function will throw a SocketError or
SocketHError exception.
The following example creates a PF_UNIX domain socket and
binds it to "/tmp/mysock":
s = socket (PF_UNIX, SOCK_STREAM, 0);
bind (s, "/tmp/mysock");
The next example creates a PF_INET domain socket and binds it
to port 32000 of the local host my.host.com:
s = socket (PF_INET, SOCK_STREAM, 0);
bind (s, "my.host.com", 32000);
accept, connect, listen, socket, setsockopt, getsockopt
Accept a connection on a socket
FD_Type accept (FD_Type s [,&address-args...]
The accept function accepts a connection on the specified
socket and returns a new socket that may be used to communicate with
the remote end. It can optionally return the address of the remote
end through reference arguments.
Upon error, accept will throw a SocketError exception.
The following example accepts a remote connection on PF_INET
socket and returns the hostname and port used by the connected party:
s1 = accept (s, &hostip, &port);
vmessage ("Accepted connection from %s on port %d", hostip, port);
bind, connect, listen, socket, setsockopt, getsockopt
Listen for connections on a socket
listen (FD_Type s, Int_Type max_pending)
The listen function may be used to wait for a connection to a
socket s. The second argument specified the maximum number
of pending connections to allow before refusing more. Upon error, a
SocketError exception will be thrown.
accept, bind, connect, socket, setsockopt, getsockopt
Get a socket option
option = getsockopt (FD_Type s, Int_Type level, Int_Type optname)
The getsockopt function returns the value of the option
specified by the integer optname residing at the specified
level. The actual object returned depends upon the option
requested. Upon error, a SocketError exception will be
generated.
The following example returns the SO_LINGER option of a socket. In this case, the value returned will be a structure:
s = socket (PF_INET, SOCK_STREAM, 0);
linger = getsockopt (s, SOL_SOCKET, SO_LINGER);
accept, bind, connect, listen, socket, getsockopt
Set an option on a socket
setsockopt (FD_Type s, Int_Type level, Int_Type optname, value)
The setsockopt function sets the value of the option
specified by the integer optname residing at the specified
level. The value of the last parameter will vary with the option to
be set. Upon error, a SocketError exception will be
generated.
The following example sets the SO_LINGER option of a socket. In this case, the value is a structure:
s = socket (PF_INET, SOCK_STREAM, 0);
linger = struct { l_onoff, l_linger };
linger.l_onoff = 1; linger.l_linger = 10;
setsockopt (s, SOL_SOCKET, SO_LINGER, linger);
accept, bind, connect, listen, socket, getsockopt