te
Copyright (c) 2007, 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]
port_send, port_sendn - send a user-defined event to a port or list of ports

#include <port.h>

int port_send(int port, int events, void *user);

int port_sendn(int ports[], int errors[], uint_t nent,
 int events, void *user);

The port_send() function submits a user-defined event to a specified port. The port argument is a file descriptor that represents a port. The sent event has its portev_events member set to the value specified in the events parameter and its portev_user member set to the value specified in the user parameter. The portev_object member of an event sent with port_send() is unspecified.

The port_sendn() function submits a user-defined event to multiple ports. The ports argument is an array of file descriptors that represents ports (see port_create(3C)). The nent argument specifies the number of file descriptors in the ports[] array. An event is submitted to each specified port. Each event has its portev_events member set to the value specified in the events parameter and its portev_user member set to the value specified in the user parameter. The portev_object member of events sent with port_sendn() is unspecified.

A port that is in alert mode can be sent an event, but that event will not be retrievable until the port has resumed normal operation. See port_alert(3C).

Upon successful completion, the port_send() function returns 0. Otherwise, it returns -1 and sets errno to indicate the error.

The port_sendn() function returns the number of successfully submitted events. A non-negative return value less than the nent argument indicates that at least one error occurred. In this case, each element of the errors[] array is filled in. An element of the errors[] array is set to 0 if the event was successfully sent to the corresponding port in the ports[] array, or is set to indicate the error if the event was not successfully sent. If an error occurs, the port_sendn() function returns -1 and sets errno to indicate the error.

The port_send() and port_sendn() functions will fail if: EAGAIN

EBADF EBADFD ENOMEM

The port_sendn() function will fail if: EFAULT

EINVAL

Example 1 Use port_send() to send a user event (PORT_SOURCE_USER) to a port.

The following example uses port_send() to send a user event (PORT_SOURCE_USER) to a port and port_get() to retrieve it. The portev_user and portev_events members of the port_event_t structure are the same as the corresponding user and events arguments of the port_send() function.

#include <port.h>

int myport;
port_event_t pe;
struct timespec timeout;
int ret;
void *user;

myport = port_create();
if (myport) {
 /* port creation failed ... */
 ...
 return(...);
}
...
events = 0x01; /* own event definition(s) */
user = <my_own_value>;
ret = port_send(myport, events, user);
if (ret == -1) {
 /* error detected ... */
 ...
 close(myport);
 return (...);
}

/*
 * The following code could also be executed from another thread or
 * process.
 */
timeout.tv_sec = 1; /* user defined */
timeout.tv_nsec = 0;
ret = port_get(myport, &pe, &timeout);
if (ret == -1) {
 /*
 * error detected :
 * - EINTR or ETIME : log error code and try again ...
 * - Other kind of errors : may have to close the port ...
 */
 return(...);
}

/*
 * After port_get() returns successfully, the port_event_t
 * structure will be filled with:
 * pe.portev_source = PORT_SOURCE_USER
 * pe.portev_events = 0x01
 * pe.portev_object = unspecified
 * pe.portev_user = <my_own_value>
 */
...
close(myport);

See setrctl(2) and rctladm(8) for information on using resource controls.

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Architecture all

Interface Stability Committed

MT-Level Async-Signal-Safe

setrctl (2), port_alert (3C), port_associate (3C), port_create (3C), port_get (3C), attributes (7), rctladm (8)