Next Previous Contents

13. Socket Module

This module provides an interface to the POSIX socket functions. Use require("socket") to load it.

13.1 socket

Synopsis

Create a communications socket

Usage

FD_Type socket (domain, type, protocol)

Description

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
The 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.

Example

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);
     }

See Also

accept, bind, connect, listen, setsockopt, getsockopt

13.2 connect

Synopsis

Make a connection to a socket

Usage

connect (FD_Type s, address-args)

Description

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.

Example

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: {...}

See Also

accept, bind, listen, socket, setsockopt, getsockopt

13.3 bind

Synopsis

Bind a local address-name to a socket

Usage

bind (FD_Type s, address-args)

Description

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.

Example

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);

See Also

accept, connect, listen, socket, setsockopt, getsockopt

13.4 accept

Synopsis

Accept a connection on a socket

Usage

FD_Type accept (FD_Type s [,&address-args...]

Description

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.

Example

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);

See Also

bind, connect, listen, socket, setsockopt, getsockopt

13.5 listen

Synopsis

Listen for connections on a socket

Usage

listen (FD_Type s, Int_Type max_pending)

Description

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.

See Also

accept, bind, connect, socket, setsockopt, getsockopt

See Also

13.6 getsockopt

Synopsis

Get a socket option

Usage

option = getsockopt (FD_Type s, Int_Type level, Int_Type optname)

Description

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.

Example

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);

See Also

accept, bind, connect, listen, socket, getsockopt

13.7 setsockopt

Synopsis

Set an option on a socket

Usage

setsockopt (FD_Type s, Int_Type level, Int_Type optname, value)

Description

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.

Example

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);

See Also

accept, bind, connect, listen, socket, getsockopt


Next Previous Contents