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

   1 '\" te
   2 .\" Copyright (c) 2007, 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_GET 3C "April 9, 2016"
   7 .SH NAME
   8 port_get, port_getn \- retrieve event information from a port
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <port.h>
  13
  14 \fBint\fR \fBport_get\fR(\fBint\fR \fIport\fR, \fBport_event_t *\fR\fIpe\fR,
  15      \fBconst timespec_t *\fR\fItimeout\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBint\fR \fBport_getn\fR(\fBint\fR \fIport\fR, \fBport_event_t\fR \fIlist\fR[], \fBuint_t\fR \fImax\fR,
  21      \fBuint_t *\fR\fInget\fR, \fBconst timespec_t *\fR\fItimeout\fR);
  22 .fi
  23
  24 .SH DESCRIPTION
  25 .LP
  26 The \fBport_get()\fR and \fBport_getn()\fR functions retrieve events from a
  27 port. The \fBport_get()\fR function retrieves at most a single event. The
  28 \fBport_getn()\fR function can retrieve multiple events.
  29 .sp
  30 .LP
  31 The \fIpe\fR argument points to an uninitialized \fBport_event_t\fR structure
  32 that is filled in by the system when the \fBport_get()\fR function returns
  33 successfully.
  34 .sp
  35 .LP
  36 The \fBport_event_t\fR structure contains the following members:
  37 .sp
  38 .in +2
  39 .nf
  40 int       portev_events;   /* detected events           */
  41 ushort_t  portev_source;   /* event source              */
  42 uintptr_t portev_object;   /* specific to event source  */
  43 void      *portev_user;    /* user defined cookie       */
  44 .fi
  45 .in -2
  46
  47 .sp
  48 .LP
  49 The \fBportev_events\fR and \fBportev_object\fR members are specific to the
  50 event source. The \fBportev_events\fR denotes the delivered events. The
  51 \fBportev_object\fR refers to the associated object (see
  52 \fBport_create\fR(3C)). The \fBportev_source\fR member specifies the source of
  53 the event. The \fBportev_user\fR member is a user-specified value.
  54 .sp
  55 .LP
  56 If the \fItimeout\fR pointer is \fINULL\fR, the \fBport_get()\fR function
  57 blocks until an event is available. To poll for an event without waiting,
  58 \fItimeout\fR should point to a zeroed \fBtimespec\fR. A non-zeroed
  59 \fBtimespec\fR specifies the desired time to wait for events. The
  60 \fBport_get()\fR function returns before the timeout elapses if an event is
  61 available, a signal occurs, a port is closed by another thread, or the port is
  62 in or enters alert mode. See \fBport_alert\fR(3C) for details on alert mode.
  63 .sp
  64 .LP
  65 The \fBport_getn()\fR function can retrieve multiple events from a port. The
  66 \fIlist\fR argument is an array of uninitialized \fBport_event_t\fR structures
  67 that is filled in by the system when the \fBport_getn()\fR function returns
  68 successfully. The \fInget\fR argument points to the desired number of events to
  69 be retrieved. The \fImax\fR parameter specifies the maximum number of events
  70 that can be returned in \fIlist\fR[]. If \fImax\fR is 0, the value pointed to
  71 by \fInget\fR is set to the number of events available on the port. The
  72 \fBport_getn()\fR function returns immediately but no events are retrieved.
  73 .sp
  74 .LP
  75 The \fBport_getn()\fR function block until the desired number of events are
  76 available, the timeout elapses, a signal occurs, a port is closed by another
  77 thread, or the port is in or enters alert mode.
  78 .sp
  79 .LP
  80 On return, the value pointed to by \fInget\fR is updated to the actual number
  81 of events retrieved in list.
  82 .sp
  83 .LP
  84 Threads calling the \fBport_get()\fR function might starve threads waiting in
  85 the \fBport_getn()\fR function for more than one event.  Similarly, threads
  86 calling the \fBport_getn()\fR function for \fIn\fR events might starve threads
  87 waiting in the \fBport_getn()\fR function for more than \fIn\fR events.
  88 .sp
  89 .LP
  90 The \fBport_get()\fR and the \fBport_getn()\fR functions ignore non-shareable
  91 events (see \fBport_create\fR(3C)) generated by other processes.
  92 .SH RETURN VALUES
  93 .LP
  94 Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno
  95 is set to indicate the error.
  96 .SH ERRORS
  97 .LP
  98 The \fBport_get()\fR and \fBport_getn()\fR functions will fail if:
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBEBADF\fR\fR
 103 .ad
 104 .RS 10n
 105 The \fIport\fR identifier is not valid.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBEBADFD\fR\fR
 112 .ad
 113 .RS 10n
 114 The \fIport\fR argument is not an event port file descriptor.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEFAULT\fR\fR
 121 .ad
 122 .RS 10n
 123 Event or event list can not be delivered (\fIlist\fR[] pointer and/or user
 124 space reserved to accommodate the list of events is not reasonable), or the
 125 \fItimeout\fR argument is not reasonable.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBEINTR\fR\fR
 132 .ad
 133 .RS 10n
 134 A signal was caught during the execution of the function.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBEINVAL\fR\fR
 141 .ad
 142 .RS 10n
 143 The \fItimeout\fR element \fBtv_sec\fR is < 0 or the \fItimeout\fR element
 144 \fBtv_nsec\fR is < 0 or > 1000000000.
 145 .RE
 146
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fBETIME\fR\fR
 151 .ad
 152 .RS 10n
 153 The time interval expired before the expected number of events have been posted
 154 to the port.
 155 .RE
 156
 157 .sp
 158 .LP
 159 The \fBport_getn()\fR function will fail if:
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBEINVAL\fR\fR
 164 .ad
 165 .RS 10n
 166 The \fIlist\fR[] argument is \fINULL\fR, the \fInget\fR argument is \fINULL\fR,
 167 or the content of \fInget\fR is > \fImax\fR and \fImax\fR is > 0.
 168 .RE
 169
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fBEFAULT\fR\fR
 174 .ad
 175 .RS 10n
 176 The \fItimeout\fR argument is not reasonable.
 177 .RE
 178
 179 .sp
 180 .ne 2
 181 .na
 182 \fB\fBETIME\fR\fR
 183 .ad
 184 .RS 10n
 185 The time interval expired before the expected number of events have been posted
 186 to the port (original value in \fInget\fR), or \fInget\fR is updated with the
 187 number of returned \fBport_event_t\fR structures in \fIlist\fR[].
 188 .RE
 189
 190 .SH EXAMPLES
 191 .LP
 192 \fBExample 1 \fRSend a user event (PORT_SOURCE_USER) to a port and retrieve it
 193 with \fBport_get()\fR.
 194 .sp
 195 .LP
 196 The following example sends a user event (\fBPORT_SOURCE_USER\fR) to a port and
 197 retrieves it with \fBport_get()\fR. The \fBportev_user\fR and
 198 \fBportev_events\fR members of the \fBport_event_t\fR structure are the same as
 199 the corresponding user and events arguments of the \fBport_send\fR(3C)
 200 function.
 201
 202 .sp
 203 .in +2
 204 .nf
 205 #include <port.h>
 206
 207 int             myport;
 208 port_event_t    pe;
 209 struct timespec timeout;
 210 int             ret;
 211 void            *user;
 212 uintptr_t       object;
 213
 214 myport = port_create();
 215 if (myport < 0) {
 216         /* port creation failed ... */
 217         ...
 218         return(...);
 219 }
 220 \&...
 221 events = 0x01;          /* own event definition(s) */
 222 object = <myobject>;
 223 user = <my_own_value>;
 224 ret = port_send(myport, events, user);
 225 if (ret == -1) {
 226         /* error detected ... */
 227         ...
 228         close(myport);
 229         return (...);
 230 }
 231
 232 /*
 233  * The following code could also be executed in another thread or
 234  * process.
 235  */
 236 timeout.tv_sec = 1;     /* user defined */
 237 timeout.tv_nsec = 0;
 238 ret = port_get(myport, &pe, &timeout);
 239 if (ret == -1) {
 240         /*
 241          * error detected :
 242          * - EINTR or ETIME : log error code and try again ...
 243          * - Other kind of errors : may have to close the port ...
 244          */
 245         return(...);
 246 }
 247
 248 /*
 249  * After port_get() returns successfully, the port_event_t
 250  * structure will be filled with:
 251  * pe.portev_source =   PORT_SOURCE_USER
 252  * pe.portev_events = 0x01
 253  * pe.portev_object = <myobject>
 254  * pe.portev_user = <my_own_value>
 255  */
 256 \&...
 257 close(myport);
 258 .fi
 259 .in -2
 260
 261 .SH ATTRIBUTES
 262 .LP
 263 See \fBattributes\fR(5) for descriptions of the following attributes:
 264 .sp
 265
 266 .sp
 267 .TS
 268 box;
 269 c | c
 270 l | l .
 271 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 272 _
 273 Architecture    all
 274 _
 275 Interface Stability     Evolving
 276 _
 277 MT-Level        Safe
 278 .TE
 279
 280 .SH SEE ALSO
 281 .LP
 282 \fBport_alert\fR(3C), \fBport_associate\fR(3C), \fBport_create\fR(3C),
 283 \fBport_send\fR(3C), \fBattributes\fR(5)