PORTS IPC(2) System Calls PORTS IPC(2)
pbind, pcreate, pdelete, pgetcount, pgetport, preceive, preset, psend -
GNO ports IPC system
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);
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
arguments as preset and they operate as described above. The differ-
ence 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.
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.
GNO 16 December 1996 PORTS IPC(2)
Man(1) output converted with