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); } NOTES SEE ALSO accept, bind, connect, listen, setsockopt, getsockopt -------------------------------------------------------------- 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: {...} NOTES SEE ALSO accept, bind, listen, socket, setsockopt, getsockopt -------------------------------------------------------------- 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 -------------------------------------------------------------- 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 -------------------------------------------------------------- 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 -------------------------------------------------------------- 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 -------------------------------------------------------------- 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 --------------------------------------------------------------