mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-12-22 14:30:29 +00:00
130 lines
3.7 KiB
Groff
130 lines
3.7 KiB
Groff
.\"
|
|
.\" $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).
|