.\"
.\" $Id: ports.2,v 1.2 1998/01/25 18:02:12 gdr-ftp Exp $
.\"
.\" .TH "PORTS IPC" 2 GNO "System Calls" "16 December 1996"
.TH "PORTS IPC" 2 "16 December 1996" GNO "System Calls"
.SH NAME
.BR pbind ,
.BR pcreate ,
.BR pdelete ,
.BR pgetcount ,
.BR pgetport ,
.BR preceive ,
.BR preset ,
.BR psend
\- GNO ports IPC system
.SH SYNOPSIS
.nf
#include <sys/ports.h>

int pcreate (int \fIcount\fR);
int pbind (int \fIportid\fR, const char *\fIname\fR);
int pgetport (const char *\fIname\fR);
int psend (int \fIportid\fR, long \fImsg\fR);
long preceive (int \fIportid\fR);
int pdelete (int \fIportid\fR, int (*\fIdispose\fR)(long));
int preset (int \fIportid\fR, int (*\fIdispose\fR)(long));
int pgetcount (int \fIportid\fR);
.fi
.SH 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
.IR count
parameter of the
.BR pcreate
call.
.LP
Creation of a port is done with
.BR 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.
.BR pcreate
returns a port ID value that must be used in subsequent calls to the Ports
IPC routines.
.LP
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 
.BR pbind .
The
.IR name
argument may be any length, but only the first 32 characters are significant.
If a name has already been bound to the chosen
.IR portid ,
-1 is returned and
.BR errno
is set.
.LP
To get the
.IR portid
of a port by it's name, use the 
.BR pgetport
call, with
.IR name
as the name of the port for which you wish to obtain the port ID.
If no port is associated with
.IR name ,
-1 is returned and errno is set.  Names are only unbound from a port
when that port is deleted.
.LP
.BR 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 
.BR pcreate 
call), then the sending process blocks until a message is read from the
port.  Messages are retrieved from a port using the 
.BR preceive
call.
.BR pgetcount
returns the number of messages in the port that have not been received;
this may be used to avoid blocking on a
.BR psend
call.
.LP
If you wish to clear the contents of a port, (for example to synchronize
communication after an error condition), use the 
.BR preset
call.  The arguments to this call are the port ID and the address of a
.IR dispose
function.  Each message in the port, before being cleared, is passed to the
.IR 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 
.BR malloc (3),
you could pass
.BR free (3)
as
.IR 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 
.IR dispose
argument.
.LP
To destroy a port, make the 
.BR pdelete
call.  It accepts the same arguments as 
.BR preset
and they operate as described above.  The difference between
.BR preset
and 
.BR pdelete
is that the latter totally destroys a port; it may no longer be used.
.BR preset 
clears a ports data but leaves the port open for more data transmissions.
.SH EXAMPLES
For an example of the use of ports, see the source code to the print
spooling utilities, 
.BR lpc (1),
.BR lpr (1),
.BR lpd (8),
and
.BR FilePort .
.SH "SEE ALSO"
.BR procsend (2).