'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PORT_CREATE 3C "Feb 5, 2008"
.SH NAME
port_create \- create a port
.SH SYNOPSIS
.LP
.nf
#include <port.h>

\fBint\fR \fBport_create\fR(\fBvoid\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBport_create()\fR function establishes a queue that multiplexes events
from disjoint sources.  Each source has a corresponding object type and
source-specific mechanism for associating an object with a port.
.sp

.sp
.TS
c c c
l l l .
source	object type	association mechanism
_
\fBPORT_SOURCE_AIO\fR	\fBstruct aiocb\fR	T{
\fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C)
T}
\fBPORT_SOURCE_FD\fR	file descriptor	\fBport_associate\fR(3C)
\fBPORT_SOURCE_MQ\fR	\fBmqd_t\fR	\fBmq_notify\fR(3C)
\fBPORT_SOURCE_TIMER\fR	\fBtimer_t\fR	\fBtimer_create\fR(3C)
\fBPORT_SOURCE_USER\fR	\fBuintptr_t\fR	\fBport_send\fR(3C)
\fBPORT_SOURCE_ALERT\fR	\fBuintptr_t\fR	\fBport_alert\fR(3C)
\fBPORT_SOURCE_FILE\fR	\fBfile_obj_t\fR	\fBport_associate\fR(3C)
.TE

.sp
.LP
\fBPORT_SOURCE_AIO\fR events represent the completion of an asynchronous I/O
transaction. An asynchronous I/O transaction is associated with a port by
specifying \fBSIGEV_PORT\fR as its notification mechanism. See
\fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C), and
\fBaio.h\fR(3HEAD) for details.
.sp
.LP
\fBPORT_SOURCE_FD\fR events represent a transition in the \fBpoll\fR(2) status
of a given file descriptor. Once an event is delivered, the file descriptor is
no longer associated with the port. A file descriptor is associated (or
re-associated) with a port using the \fBport_associate\fR(3C) function.
.sp
.LP
\fBPORT_SOURCE_MQ\fR events represent a message queue transition from empty to
non-empty.  A message queue is associated with a port by specifying
\fBSIGEV_PORT\fR as its notification mechanism. See \fBmq_notify\fR(3C) for
more information.
.sp
.LP
\fBPORT_SOURCE_TIMER\fR events represent one or more timer expirations for a
given timer.  A timer is associated with a port by specifying \fBSIGEV_PORT\fR
as its notification mechanism. See \fBtimer_create\fR(3C) for more information.
.sp
.LP
\fBPORT_SOURCE_USER\fR events represent user-defined events. These events are
generated by \fBport_send\fR(3C) or \fBport_sendn\fR(3C).
.sp
.LP
\fBPORT_SOURCE_ALERT\fR events indicate that the port itself is in alert mode.
The mode of the port is changed with \fBport_alert\fR(3C).The
\fBport_create()\fR function returns a file descriptor that represents a newly
created port. The \fBclose\fR(2) function destroys the port and frees all
allocated resources.
.sp
.LP
\fBPORT_SOURCE_FILE\fR events represent file/directory status change. Once an
event is delivered, the file object associated with the port is no longer
active. It has to be reassociated to activate. A file object is associated or
reassociated with a port using the \fBport_associate\fR(3C).
.sp
.LP
The \fBport_get\fR(3C) and \fBport_getn\fR(3C) functions retrieve events from a
port. They ignore non retrievable events (non-own or non-shareable events).
.sp
.LP
As a port is represented by a file descriptor, ports are shared between child
and parent processes after \fBfork()\fR.  Both can continue to associate
sources with the port, both can receive events from the port, and events
associated with and/or generated by either process are retrievable in the
other. Since some events might not have meaning in both parent and child, care
must be taken when using ports after \fBfork()\fR.
.sp
.LP
If a port is exported to other processes, the port is destroyed on last close.
.sp
.LP
\fBPORT_SOURCE_USER\fR and \fBPORT_SOURCE_ALERT\fR events can be distributed
across processes. \fBPORT_SOURCE_FD\fR events can only be shared between
processes when child processes inherit opened file decriptors from the parent
process. See \fBfork\fR(2). \fBPORT_SOURCE_TIMER\fR and \fBPORT_SOURCE_AIO\fR
cannot be shared between processes.
.SH RETURN VALUES
.sp
.LP
Upon succesful completion, the \fBport_create()\fR function returns a
non-negative value, the port identifier. Otherwise, \(mi1 is returned and errno
is set to indicate the error.
.SH ERRORS
.sp
.LP
The \fBport_create()\fR function will fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
The maximum allowable number of ports is currently open in the system. The
maximum allowable number of ports is the minimum value of the
\fBproject.max-port-ids\fR resource control. See \fBsetrctl\fR(2) and
\fBrctladm\fR(1M) for information on using resource controls.
.RE

.sp
.ne 2
.na
\fB\fBEMFILE\fR\fR
.ad
.RS 10n
The process has too many open descriptors.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	all
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBrctladm\fR(1M), \fBclose\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBpoll\fR(2),
\fBsetrctl\fR(2), \fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBaio.h\fR(3HEAD),
\fBlio_listio\fR(3C), \fBmq_notify\fR(3C), \fBport_associate\fR(3C),
\fBport_get\fR(3C), \fBtimer_create\fR(3C), \fBattributes\fR(5)