Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
SysSockets

NAME

SysSockets - BSD interprocess communication

SYNOPSIS

TYPE Socket = SysTypes.File;



(* protocol families *)
CONST pfUNSPEC    = 0;   (* unspecified *)
CONST pfUNIX      = 1;   (* local to host (pipes, portals) *)
CONST pfINET      = 2;   (* internetwork: UDP, TCP, etc. *)
CONST pfIMPLINK   = 3;   (* arpanet imp addresses *)
CONST pfPUP       = 4;   (* pup protocols: e.g. BSP *)
CONST pfCHAOS     = 5;   (* mit CHAOS protocols *)
CONST pfNS        = 6;   (* XEROX NS protocols *)
CONST pfNBS       = 7;   (* nbs protocols *)
CONST pfECMA      = 8;   (* european computer manufacturers *)
CONST pfDATAKIT   = 9;   (* datakit protocols *)
CONST pfCCITT     = 10;  (* CCITT protocols, X.25 etc *)
CONST pfSNA       = 11;  (* IBM SNA *)
CONST pfDECnet    = 12;  (* DECnet *)
CONST pfDLI       = 13;  (* Direct data link interface *)
CONST pfLAT       = 14;  (* LAT *)
CONST pfHYLINK    = 15;  (* NSC Hyperchannel *)
CONST pfAPPLETALK = 16;  (* Apple Talk *)
CONST pfNIT       = 17;  (* Network Interface Tap *)
CONST pf802       = 18;  (* IEEE 802.2, also ISO 8802 *)
CONST pfOSI       = 19;  (* umbrella for all families used by OSI *)
CONST pfX25       = 20;  (* CCITT X.25 in particular *)
CONST pfOSINET    = 21;  (* AFI = 47, IDI = 4 *)
CONST pfGOSIP     = 22;  (* U.S. Government OSI *)
CONST pfIPX       = 23;  (* Novell Internet Protocol *)
CONST pfROUTE     = 24;  (* Internal Routing Protocol *)
CONST pfLINK      = 25;  (* Link-layer interface *)
CONST pfINET6     = 26;  (* Internet Protocol, Version 6 *)
CONST pfKEY       = 27;  (* Security Association DB socket *)
CONST pfNCA       = 28;  (* NCA socket *)
CONST pfPOLICY    = 29;  (* Security Policy DB socket *)



(* socket types *)
CONST dgram     = 1;     (* datagram socket *)
CONST stream    = 2;     (* stream socket *)
CONST raw       = 4;     (* raw-protocol interface *)
CONST rdm       = 5;     (* reliably-delivered message *)
CONST seqpacket = 6;     (* sequenced packet stream *)



(* address families *)
CONST afUNSPEC    = pfUNSPEC;
CONST afUNIX      = pfUNIX;
CONST afINET      = pfINET;
CONST afIMPLINK   = pfIMPLINK;
CONST afPUP       = pfPUP;
CONST afCHAOS     = pfCHAOS;
CONST afNS        = pfNS;
CONST afNBS       = pfNBS;
CONST afECMA      = pfECMA;
CONST afDATAKIT   = pfDATAKIT;
CONST afCCITT     = pfCCITT;
CONST afSNA       = pfSNA;
CONST afDECnet    = pfDECnet;
CONST afDLI       = pfDLI;
CONST afLAT       = pfLAT;
CONST afHYLINK    = pfHYLINK;
CONST afAPPLETALK = pfAPPLETALK;
CONST afNIT       = pfNIT;
CONST af802       = pf802;
CONST afOSI       = pfOSI;
CONST afX25       = pfX25;
CONST afOSINET    = pfOSINET;
CONST afGOSIP     = pfGOSIP;
CONST afIPX       = pfIPX;
CONST afROUTE     = pfROUTE;
CONST afLINK      = pfLINK;
CONST afINET6     = pfINET6;
CONST afKEY       = pfKEY;
CONST afNCA       = pfNCA;
CONST afPOLICY    = pfPOLICY;



(* socket message flags *)
CONST msgOutOfBand = 1;  (* process out-of-band data *)
CONST msgPeek = 2;       (* peek at incoming message *)
CONST msgDontRoute = 4;  (* send without using routing tables *)



(* shutdown options *)
CONST shutReceive  = 0;
CONST shutSend = 1;
CONST shutBoth = 2;



(* socket options at socket level -- see <sys/socket.h> *)
CONST socketLevel = 0FFFFH;     (* options for socket level *)
CONST optDebug = 1;             (* turn on debugging info recording *)
CONST optAcceptConn = 2;        (* socket has had listen() *)
CONST optReuseAddr = 4;         (* allow local address reuse *)
CONST optKeepAlive = 8;         (* keep connections alive *)
CONST optDontRoute = 10H;       (* just use interface addresses *)
CONST optBroadcast = 20H;       (* permit sending of broadcast msgs *)
CONST optUseLoopBack = 40H;     (* bypass hardware when possible *)
CONST optLinger = 80H;          (* linger on close if data present *)
CONST optOOBinline = 100H;      (* leave received OOB data in line *)
CONST optSndBuf = 1001H;        (* send buffer size *)
CONST optRcvBuf = 1002H;        (* receive buffer size *)
CONST optSndLoWat = 1003H;      (* send low-water mark *)
CONST optRcvLoWat = 1004H;      (* receive low-water mark *)
CONST optSndTimeO = 1005H;      (* send timeout *)
CONST optRcvTimeO = 1006H;      (* receive timeout *)
CONST optError = 1007H;         (* get error status and clear *)
CONST optType = 1008H;          (* get socket type *)
CONST optProtocol = 1009H;      (* get/set protocol type *)



TYPE LingerVal =
   RECORD
      onoff: INTEGER;
      linger: SysTypes.Time;
   END;
TYPE BoolVal = RECORD bool: INTEGER END;



PROCEDURE Create(VAR socket: Socket;
                 domain, type, protocol: INTEGER;
                 errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Bind(s: Socket; name: ARRAY OF BYTE;
               errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Bind3(s: Socket; name: ARRAY OF BYTE;
                namelen: LONGINT;
                errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Listen(s: Socket; backlog: INTEGER;
                 errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Accept(VAR fd: SysTypes.File;
                 s: Socket; VAR addr: ARRAY OF BYTE;
                 errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Connect(s: Socket; name: ARRAY OF BYTE;
                  errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Connect3(s: Socket; name: ARRAY OF BYTE;
                   namelen: LONGINT;
                   errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE GetName(s: Socket; VAR name: ARRAY OF BYTE;
                  errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE GetPeerName(s: Socket; VAR name: ARRAY OF BYTE;
                      errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE GetSockOpt(s: Socket; level, optname: INTEGER;
                     VAR optval: ARRAY OF BYTE;
                     errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE SetSockOpt(s: Socket; level, optname: INTEGER;
                     optval: ARRAY OF BYTE;
                     errors: RelatedEvents.Object) : BOOLEAN;
PROCEDURE Shutdown(s: Socket; how: INTEGER;
                   errors: RelatedEvents.Object) : BOOLEAN;
   (* how = shutReceive, shutSend or shutBoth *)



(* message operations for sockets *)
PROCEDURE Receive(s: Socket;
                  buf: SysTypes.Address; buflen: SysTypes.Count;
                  flags: INTEGER;
                  errors: RelatedEvents.Object;
                  retry: BOOLEAN; VAR interrupted: BOOLEAN) : SysTypes.Count;
PROCEDURE ReceiveFrom(s: Socket;
                      buf: SysTypes.Address; buflen: SysTypes.Count;
                      flags: INTEGER;
                      VAR from: ARRAY OF BYTE;
                      VAR fromlen: LONGINT;
                      errors: RelatedEvents.Object;
                      retry: BOOLEAN; VAR interrupted: BOOLEAN) : LONGINT;
PROCEDURE Send(s: Socket;
               buf: SysTypes.Address; buflen: SysTypes.Count;
               flags: INTEGER;
               errors: RelatedEvents.Object;
               retry: BOOLEAN; VAR interrupted: BOOLEAN) : BOOLEAN;
PROCEDURE SendTo(s: Socket;
                 buf: SysTypes.Address; buflen: SysTypes.Count;
                 flags: INTEGER;
                 name: ARRAY OF BYTE; namelen: LONGINT;
                 errors: RelatedEvents.Object;
                 retry: BOOLEAN; VAR interrupted: BOOLEAN) : BOOLEAN;

DESCRIPTION

SysSockets interfaces the system calls which are related to sockets. Sockets are endpoints of interprocess communication.

Many different communication protocols and networks are accessible as sockets. The main differences between them are the parameters and addresses which are necessary to establish a connection. Once a connection has been established, sockets behave like other file descriptors and are opened for reading and writing.

SysSockets provides a raw access to the system calls. There exist other modules which offers more convenient ways to establish connections for specific protocols and networks, e.g. IPv4TCPSockets and InetTCP.

A domain specifies a communication domain which uses a common protocol family which shares a address family. Until now, all implementations restrict protocol families to one member which uses one unique address type. Protocol families and address types are given by integer constants: pfXXX specifies a protocol family and aFXXX the corresponding address family. Currently, both values are equal for all protocols.

In widespread use are three protocols only:

pfUNIX
local connection on one UNIX-machine
pfINET
IPv4 protocol
pfINET6
IPv6 protocol

There exist different types of sockets, the most important are stream which provides a reliable and sequenced two-way connection and dgram which allows to send unreliable messages (datagrams). seqpacket works like stream but preserves packet boundaries.

Create creates a new socket for the communication domain domain (e.g. pfINET) which is of type type (e.g. stream). If the communication domain supports more than one protocol, the protocol may be selected by protocol. Normally, only one protocol is available which can be specified as 0. Sockets which have been just created by Create are unnamed and unconnected. Consequently, they are not ready for any input or output operation. Newly created sockets should be either prepared to accept connections (Bind, Listen and Accept) or being connected (Connect) to another socket by giving the address of a peer (the other socket we want to communicate with).

Bind assigns name to an unnamed socket. name should be of the appropiate address type. Usually, address types have a length of 16 bytes (some bytes may be unused) where the first 2 bytes are used select the address family (e.g. afINET). Bind3 works like Bind but namelen overrides LEN(name).

Listen prepares a socket for the acceptance of connections. Connection requests are queued and backlog allows to specify the maximal queue length. Accept waits for an incoming connection related to the given socket. The socket must have been named by Bind and prepared by Listen. If successful, a file descriptor is returned together with the address of the peer. Typically, Accept is executed in a loop which forks for every incoming connection.

Connect tries to establish a connection to a peer with the given name. Connect3 works like Connect but namelen overrides LEN(name).

GetName returns the current name of the given socket. GetPeerName returns the name of the peer connected to socket s.

GetSockOpt and SetSockOpt allow to retrieve and modify socket options at various levels of the protocol hierarchy. Some of the options at the socket level (level = socketLevel) may be useful in some applications:

optKeepAlive
asks the system to periodically check the connection for being alive even when no data is exchanged. A record of type BoolVal has to be given as optval.
optLinger
some applications produce output data for other processes without waiting for confirmation. In this case it may be useful to increase the linger time to assure that the system still tries to transmit the yet not received data even after SysIO.Close or Shutdown. A record of type LingerVal has to be given as optval.

Shutdown allows to partially shut down a connection.

Receive, ReceiveFrom, Send and SendTo interface UDP, the unreliable datagram transmission protocol (socket type dgram).

DIAGNOSTICS

System call failures lead to events of SysErrors. The errors parameter is passed to SysErrors.Raise. All procedures return FALSE in error case.

SEE ALSO

accept(2)
Accept
bind(2)
Bind
connect(2)
Connect
getpeername(2)
GetPeerName
getsockname(2)
GetName
getsockopt(2)
GetSockOpt and SetSockOpt
listen(2)
Listen
receive(2)
Receive and ReceiveFrom
send(2)
Send and SendTo
shutdown(2)
Shutdown
socket(2)
Create
SysErrors
error handling
SysIO
input and output operations
Edited by: borchert, last change: 2005/02/24, revision: 1.10, converted to HTML: 2005/02/24

Oberon || Library || Module Index || Search Engine || Definition || Module