PORTS IPC(2)                     System Calls                     PORTS IPC(2)

NAME

       pbind, pcreate, pdelete, pgetcount, pgetport, preceive, preset, psend -
       GNO ports IPC system

SYNOPSIS

       #include <sys/ports.h>

       int pcreate (int count);
       int pbind (int portid, const char *name);
       int pgetport (const char *name);
       int psend (int portid, long msg);
       long preceive (int portid);
       int pdelete (int portid, int (*dispose)(long));
       int preset (int portid, int (*dispose)(long));
       int pgetcount (int portid);

DESCRIPTION

       The Ports IPC (interprocess communication) machanism is a  very  flexi‐
       ble,  powerful,  and efficient method of interprocess communication.  A
       port is a queue that can contain a number of 32-bit values.   The  size
       of  the  port  (how  many  messages it can contain) is specified as the
       count parameter of the pcreate call.

       Creation of a port is done with pcreate.  You must specify the size  of
       the  port in this call, which must be at least 1 (one).  The larger the
       port, the more data it can hold without blocking the  sending  process.
       pcreate  returns  a port ID value that must be used in subsequent calls
       to the Ports IPC routines.

       A name may be associated with a port;  this  allows  totally  unrelated
       processes  to  access  a port without having to communicate the port ID
       through some other method, and without knowing the process  ID  of  the
       other.  To bind a name to a port, call pbind.  The name argument may be
       any length, but only the first 32 characters  are  significant.   If  a
       name  has  already  been bound to the chosen portid, -1 is returned and
       errno is set.

       To get the portid of a port by it's name, use the pgetport  call,  with
       name  as the name of the port for which you wish to obtain the port ID.
       If no port is associated with name, -1 is returned and  errno  is  set.
       Names are only unbound from a port when that port is deleted.

       psend  is  used  to send a 32-bit datum to a port.  If the port is full
       (that is, if there are more unread messages in the port than are speci‐
       fied in the pcreate call), then the sending process blocks until a mes‐
       sage is read from the port.  Messages are retrieved from a  port  using
       the  preceive  call.   pgetcount  returns the number of messages in the
       port that have not been received; this may be used to avoid blocking on
       a psend call.

       If  you  wish to clear the contents of a port, (for example to synchro‐
       nize communication after an error condition), use the preset call.  The
       arguments  to  this  call  are the port ID and the address of a dispose
       function.  Each message in the port, before being cleared, is passed to
       the  dispose  function so that appropriate clean-up actio nmay be taken
       on the data.  For example, if the messages correspond to the address of
       memory  blocks  obtained with malloc(3), you could pass free(3) as dis���
       pose to automatically deallocate that memory.  If  you  don't  wish  to
       take  any  special  action  on  the  data  being cleared, pass the NULL
       pointer for the dispose argument.

       To destroy a port, make the pdelete call.  It accepts  the  same  argu‐
       ments  as  preset  and they operate as described above.  The difference
       between preset and pdelete is that the latter totally destroys a  port;
       it  may  no  longer be used.  preset clears a ports data but leaves the
       port open for more data transmissions.

EXAMPLES

       For an example of the use of ports, see the source code  to  the  print
       spooling utilities, lpc(1), lpr(1), lpd(8), and FilePort.

SEE ALSO

       procsend(2).



GNO                            16 December 1996                   PORTS IPC(2)