IPC_$INTRO                        Domain/OS                         IPC_$INTRO


NAME
     intro - Domain/OS Interprocess Communication

SYNOPSIS (C)
     #include <apollo/base.h>
     #include <apollo/ipc.h>

SYNOPSIS (Pascal)
     %include '/sys/ins/base.ins.pas';
     %include '/sys/ins/ipc.ins.pas';

SYNOPSIS (FORTRAN)
     %include '/sys/ins/base.ins.ftn'
     %include '/sys/ins/ipc.ins.ftn'

DESCRIPTION
     The ipc_$ (Interprocess Communication) calls facilitate the creation of
     direct data connections between processes running anywhere in a network.

     The following is a list of the ipc_$ calls.

               ipc_$close     close an IPC socket
               ipc_$create    create an IPC socket
               ipc_$delete    delete an IPC socket
               ipc_$get_ec    get an IPC eventcount
               ipc_$open      open an IPC socket
               ipc_$rcv       retrieve an IPC datagram
               ipc_$resolve   get an IPC socket handle
               ipc_$sar       send an IPC datagram and await a reply
               ipc_$send      send an IPC datagram
               ipc_$wait      wait for an IPC datagram

     IPC connections are fast, but messages are not guaranteed to arrive at
     their destinations in the order they were sent, they are not guaranteed
     to arrive only once or, indeed, to arrive at all.  Therefore, process
     communicating with the ipc_$ calls must do their own message sychroniza-
     tion if sequence is important or delivery is critical.

   Sockets
     The simplest IPC connection is a single "socket."  A socket is the desti-
     nation point for a "datagram," a small independently addressable unit of
     data.  IPC sockets are created with ipc_$create, and exist as typed
     objects in the file system.

   Socket Handles
     Most ipc_$ calls use a "socket handle" to identify a socket.  A socket
     handle uniquely identifies a socket; that is, no two sockets have identi-
     cal handles.  Any process that knows a socket's pathname can obtain its
     handle by calling ipc_$resolve.  Once a process has a socket's handle, it
     can open the socket and send datagrams to or retrieve datagrams from it.

   Datagrams
     A datagram has three sections of interest to programmers:  the reply han-
     dle, header, and data.  The reply handle is a socket handle provided by
     the sender that the receiving process can use to reply to the datagram.
     It is usually the handle for a socket monitored by the sender for
     replies, although it need not be.

     A datagram header is a short required section usually used to pass con-
     trol information from the sender to the receiver, although it can actu-
     ally be used for anything.  The ipc_$hdr_info_t data type defines the
     largest allowable datagram header.

     The data section of a datagram is optional and is usually used to pass
     the information content of a datagram.  If the information content of a
     datagram fits entirely in the header, the data section can can be omit-
     ted.  The ipc_$data_t data type defines the largest allowable datagram
     data section.

   Servers and Clients
     An IPC socket can only queue up to four datagrams at a time, and new
     datagrams arriving at a socket whose queue is full are lost without any
     notification to the sender.  To avoid the need to constantly deal with
     lost datagrams, most applications set up an "IPC server" whose primary
     purpose is to receive information and keep its socket free of incoming
     messages.  The IPC server services one or more "IPC clients" that send
     information to the server and perform the actual work of the application.
     Messages from a server to its clients are generally restricted to
     datagram acknowlegements, control information, and forwarded messages
     from other clients.  The ipc_$get_ec generally finds its use in server
     programs; the ipc_$sar and ipc_$wait generally find their use in client
     programs.

   Data Types
     ipc_$data_t
          An array type with a capacity equivalent to the largest possible
          data portion of an IPC datagram.

     ipc_$hdr_info_t
          An array type with a capacity equivalent to the largest possible IPC
          datagram header.

     ipc_$socket_handle_t
          An array type for passing socket handles to ipc_$ calls.

   Errors
     ipc_$OK
          Successful completion.

     ipc_$nomore_sockets
          Cannot create any more user sockets.

     ipc_$not_ipc_obj
          The specified pathname is not an IPC socket.

     ipc_$not_owner
          The socket was not opened by the calling process.

     ipc_$range_error
          The supplied socket number is outside the legal range.

     ipc_$socket_already_open
          The specified socket is already open.

     ipc_$socket_empty
          There are no datagrams in the socket.

     ipc_$socket_not_open
          The socket is not open.

     ipc_$timeout
          The call timed out before a datagram was received.

     ipc_$too_deep
          The supplied socket depth is too big.

     ipc_$too_much_data
          The data is too long to send.

SEE ALSO
     mbx_$intro.