usr/src/man/man3c/port_create.3c

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PORT_CREATE 3C "April 9, 2016"
   7 .SH NAME
   8 port_create \- create a port
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <port.h>
  13
  14 \fBint\fR \fBport_create\fR(\fBvoid\fR);
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .LP
  19 The \fBport_create()\fR function establishes a queue that multiplexes events
  20 from disjoint sources.  Each source has a corresponding object type and
  21 source-specific mechanism for associating an object with a port.
  22 .sp
  23
  24 .sp
  25 .TS
  26 c c c
  27 l l l .
  28 source  object type     association mechanism
  29 _
  30 \fBPORT_SOURCE_AIO\fR   \fBstruct aiocb\fR      T{
  31 \fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C)
  32 T}
  33 \fBPORT_SOURCE_FD\fR    file descriptor \fBport_associate\fR(3C)
  34 \fBPORT_SOURCE_MQ\fR    \fBmqd_t\fR     \fBmq_notify\fR(3C)
  35 \fBPORT_SOURCE_TIMER\fR \fBtimer_t\fR   \fBtimer_create\fR(3C)
  36 \fBPORT_SOURCE_USER\fR  \fBuintptr_t\fR \fBport_send\fR(3C)
  37 \fBPORT_SOURCE_ALERT\fR \fBuintptr_t\fR \fBport_alert\fR(3C)
  38 \fBPORT_SOURCE_FILE\fR  \fBfile_obj_t\fR        \fBport_associate\fR(3C)
  39 .TE
  40
  41 .sp
  42 .LP
  43 \fBPORT_SOURCE_AIO\fR events represent the completion of an asynchronous I/O
  44 transaction. An asynchronous I/O transaction is associated with a port by
  45 specifying \fBSIGEV_PORT\fR as its notification mechanism. See
  46 \fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBlio_listio\fR(3C), and
  47 \fBaio.h\fR(3HEAD) for details.
  48 .sp
  49 .LP
  50 \fBPORT_SOURCE_FD\fR events represent a transition in the \fBpoll\fR(2) status
  51 of a given file descriptor. Once an event is delivered, the file descriptor is
  52 no longer associated with the port. A file descriptor is associated (or
  53 re-associated) with a port using the \fBport_associate\fR(3C) function.
  54 .sp
  55 .LP
  56 \fBPORT_SOURCE_MQ\fR events represent a message queue transition from empty to
  57 non-empty.  A message queue is associated with a port by specifying
  58 \fBSIGEV_PORT\fR as its notification mechanism. See \fBmq_notify\fR(3C) for
  59 more information.
  60 .sp
  61 .LP
  62 \fBPORT_SOURCE_TIMER\fR events represent one or more timer expirations for a
  63 given timer.  A timer is associated with a port by specifying \fBSIGEV_PORT\fR
  64 as its notification mechanism. See \fBtimer_create\fR(3C) for more information.
  65 .sp
  66 .LP
  67 \fBPORT_SOURCE_USER\fR events represent user-defined events. These events are
  68 generated by \fBport_send\fR(3C) or \fBport_sendn\fR(3C).
  69 .sp
  70 .LP
  71 \fBPORT_SOURCE_ALERT\fR events indicate that the port itself is in alert mode.
  72 The mode of the port is changed with \fBport_alert\fR(3C).The
  73 \fBport_create()\fR function returns a file descriptor that represents a newly
  74 created port. The \fBclose\fR(2) function destroys the port and frees all
  75 allocated resources.
  76 .sp
  77 .LP
  78 \fBPORT_SOURCE_FILE\fR events represent file/directory status change. Once an
  79 event is delivered, the file object associated with the port is no longer
  80 active. It has to be reassociated to activate. A file object is associated or
  81 reassociated with a port using the \fBport_associate\fR(3C).
  82 .sp
  83 .LP
  84 The \fBport_get\fR(3C) and \fBport_getn\fR(3C) functions retrieve events from a
  85 port. They ignore non retrievable events (non-own or non-shareable events).
  86 .sp
  87 .LP
  88 As a port is represented by a file descriptor, ports are shared between child
  89 and parent processes after \fBfork()\fR.  Both can continue to associate
  90 sources with the port, both can receive events from the port, and events
  91 associated with and/or generated by either process are retrievable in the
  92 other. Since some events might not have meaning in both parent and child, care
  93 must be taken when using ports after \fBfork()\fR.
  94 .sp
  95 .LP
  96 If a port is exported to other processes, the port is destroyed on last close.
  97 .sp
  98 .LP
  99 \fBPORT_SOURCE_USER\fR and \fBPORT_SOURCE_ALERT\fR events can be distributed
 100 across processes. \fBPORT_SOURCE_FD\fR events can only be shared between
 101 processes when child processes inherit opened file decriptors from the parent
 102 process. See \fBfork\fR(2). \fBPORT_SOURCE_TIMER\fR and \fBPORT_SOURCE_AIO\fR
 103 cannot be shared between processes.
 104 .SH RETURN VALUES
 105 .LP
 106 Upon successful completion, the \fBport_create()\fR function returns a
 107 non-negative value, the port identifier. Otherwise, \(mi1 is returned and errno
 108 is set to indicate the error.
 109 .SH ERRORS
 110 .LP
 111 The \fBport_create()\fR function will fail if:
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBEAGAIN\fR\fR
 116 .ad
 117 .RS 10n
 118 The maximum allowable number of ports is currently open in the system. The
 119 maximum allowable number of ports is the minimum value of the
 120 \fBproject.max-port-ids\fR resource control. See \fBsetrctl\fR(2) and
 121 \fBrctladm\fR(1M) for information on using resource controls.
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBEMFILE\fR\fR
 128 .ad
 129 .RS 10n
 130 The process has too many open descriptors.
 131 .RE
 132
 133 .SH ATTRIBUTES
 134 .LP
 135 See \fBattributes\fR(5) for descriptions of the following attributes:
 136 .sp
 137
 138 .sp
 139 .TS
 140 box;
 141 c | c
 142 l | l .
 143 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 144 _
 145 Architecture    all
 146 _
 147 Interface Stability     Committed
 148 _
 149 MT-Level        Safe
 150 .TE
 151
 152 .SH SEE ALSO
 153 .LP
 154 \fBrctladm\fR(1M), \fBclose\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBpoll\fR(2),
 155 \fBsetrctl\fR(2), \fBaio_read\fR(3C), \fBaio_write\fR(3C), \fBaio.h\fR(3HEAD),
 156 \fBlio_listio\fR(3C), \fBmq_notify\fR(3C), \fBport_associate\fR(3C),
 157 \fBport_get\fR(3C), \fBtimer_create\fR(3C), \fBattributes\fR(5)