usr/src/man/man3c/port_send.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_SEND 3C "Oct 24, 2007"
   7 .SH NAME
   8 port_send, port_sendn \- send a user-defined event to a port or list of ports
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <port.h>
  13
  14 \fBint\fR \fBport_send\fR(\fBint\fR \fIport\fR, \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBint\fR \fBport_sendn\fR(\fBint\fR \fIports\fR[], \fBint\fR \fIerrors\fR[], \fBuint_t\fR \fInent\fR,
  20      \fBint\fR \fIevents\fR, \fBvoid *\fR\fIuser\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBport_send()\fR function submits a user-defined event to a specified
  27 port. The \fIport\fR argument is a file descriptor that represents a port.  The
  28 sent event has its \fBportev_events\fR member set to the value specified in the
  29 \fIevents\fR parameter and its \fBportev_user\fR member set to the value
  30 specified in the \fIuser\fR parameter.  The \fBportev_object\fR member of an
  31 event sent with \fBport_send()\fR is unspecified.
  32 .sp
  33 .LP
  34 The \fBport_sendn()\fR function submits a user-defined event to multiple ports.
  35 The \fIports\fR argument is an array of file descriptors that represents ports
  36 (see \fBport_create\fR(3C)). The \fInent\fR argument specifies the number of
  37 file descriptors in the \fIports\fR[] array. An event is submitted to each
  38 specified port. Each event has its \fBportev_events\fR member set to the value
  39 specified in the \fIevents\fR parameter and its \fBportev_user\fR member set to
  40 the value specified in the \fIuser\fR parameter.  The \fBportev_object\fR
  41 member of \fIevents\fR sent with \fBport_sendn()\fR is unspecified.
  42 .sp
  43 .LP
  44 A port that is in alert mode can be sent an event, but that event will not be
  45 retrievable until the port has resumed normal operation.  See
  46 \fBport_alert\fR(3C).
  47 .SH RETURN VALUES
  48 .sp
  49 .LP
  50 Upon successful completion, the \fBport_send()\fR function returns 0.
  51 Otherwise, it returns \(mi1 and sets \fBerrno\fR to indicate the error.
  52 .sp
  53 .LP
  54 The \fBport_sendn()\fR function returns the number of successfully submitted
  55 events.  A non-negative return value less than the \fInent\fR argument
  56 indicates that at least one error occurred. In this case, each element of the
  57 \fIerrors\fR[] array is filled in. An element of the \fIerrors\fR[] array is
  58 set to 0 if the event was successfully sent to the corresponding port in the
  59 \fIports\fR[] array, or is set to indicate the error if the event was not
  60 successfully sent.  If an error occurs, the \fBport_sendn()\fR function returns
  61 \(mi1 and sets \fBerrno\fR to indicate the error.
  62 .SH ERRORS
  63 .sp
  64 .LP
  65 The \fBport_send()\fR and \fBport_sendn()\fR functions will fail if:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBEAGAIN\fR\fR
  70 .ad
  71 .RS 10n
  72 The maximum number of events per port is exceeded.  The maximum allowable
  73 number of events per port is the minimum value of the
  74 \fBprocess.max-port-events\fR resource control at the time
  75 \fBport_create\fR(3C) was used to create the port.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBEBADF\fR\fR
  82 .ad
  83 .RS 10n
  84 The port file descriptor is not valid.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBEBADFD\fR\fR
  91 .ad
  92 .RS 10n
  93 The \fIport\fR argument is not an event port file descriptor.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBENOMEM\fR\fR
 100 .ad
 101 .RS 10n
 102 There is not enough memory available to satisfy the request.
 103 .RE
 104
 105 .sp
 106 .LP
 107 The \fBport_sendn()\fR function will fail if:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBEFAULT\fR\fR
 112 .ad
 113 .RS 10n
 114 The \fIports\fR[] pointer or \fIerrors\fR[] pointer is not reasonable.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEINVAL\fR\fR
 121 .ad
 122 .RS 10n
 123 The value of the \fInent\fR argument is 0.
 124 .RE
 125
 126 .SH EXAMPLES
 127 .LP
 128 \fBExample 1 \fRUse \fBport_send()\fR to send a user event (PORT_SOURCE_USER)
 129 to a port.
 130 .sp
 131 .LP
 132 The following example uses \fBport_send()\fR to send a user event
 133 (\fBPORT_SOURCE_USER\fR) to a port and \fBport_get()\fR to retrieve it. The
 134 \fBportev_user\fR and \fBportev_events\fR members of the \fBport_event_t\fR
 135 structure are the same as the corresponding user and events arguments of the
 136 \fBport_send()\fR function.
 137
 138 .sp
 139 .in +2
 140 .nf
 141 #include <port.h>
 142
 143 int             myport;
 144 port_event_t    pe;
 145 struct timespec timeout;
 146 int             ret;
 147 void            *user;
 148
 149 myport = port_create();
 150 if (myport) {
 151         /* port creation failed ... */
 152         ...
 153         return(...);
 154 }
 155 \&...
 156 events = 0x01;          /* own event definition(s) */
 157 user = <my_own_value>;
 158 ret = port_send(myport, events, user);
 159 if (ret == -1) {
 160         /* error detected ... */
 161         ...
 162         close(myport);
 163         return (...);
 164 }
 165
 166 /*
 167  * The following code could also be executed from another thread or
 168  * process.
 169  */
 170 timeout.tv_sec = 1;     /* user defined */
 171 timeout.tv_nsec = 0;
 172 ret = port_get(myport, &pe, &timeout);
 173 if (ret == -1) {
 174         /*
 175          * error detected :
 176          * - EINTR or ETIME : log error code and try again ...
 177          * - Other kind of errors : may have to close the port ...
 178          */
 179         return(...);
 180 }
 181
 182 /*
 183  * After port_get() returns successfully, the port_event_t
 184  * structure will be filled with:
 185  * pe.portev_source =   PORT_SOURCE_USER
 186  * pe.portev_events = 0x01
 187  * pe.portev_object = unspecified
 188  * pe.portev_user = <my_own_value>
 189  */
 190 \&...
 191 close(myport);
 192 .fi
 193 .in -2
 194
 195 .SH USAGE
 196 .sp
 197 .LP
 198 See \fBsetrctl\fR(2) and \fBrctladm\fR(1M) for information on using resource
 199 controls.
 200 .SH ATTRIBUTES
 201 .sp
 202 .LP
 203 See \fBattributes\fR(5) for descriptions of the following attributes:
 204 .sp
 205
 206 .sp
 207 .TS
 208 box;
 209 c | c
 210 l | l .
 211 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 212 _
 213 Architecture    all
 214 _
 215 Interface Stability     Committed
 216 _
 217 MT-Level        Async-Signal-Safe
 218 .TE
 219
 220 .SH SEE ALSO
 221 .sp
 222 .LP
 223 \fBrctladm\fR(1M), \fBsetrctl\fR(2), \fBport_alert\fR(3C),
 224 \fBport_associate\fR(3C), \fBport_create\fR(3C), \fBport_get\fR(3C),
 225 \fBattributes\fR(5)