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 flexible, 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 specified in the pcreate call), then the sending process blocks until a message 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 synchronize 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 dispose 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 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).