PORT_SEND(3C)PORT_SEND(3C)NAME
port_send, port_sendn - send a user-defined event to a port or list of
ports
SYNOPSIS
#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);
DESCRIPTION
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 repre‐
sents ports (see port_create(3C)). The nent argument specifies the num‐
ber 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).
RETURN VALUES
Upon successful completion, the port_send() function returns 0. Other‐
wise, 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 indi‐
cates 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.
ERRORS
The port_send() and port_sendn() functions will fail if:
EAGAIN
The maximum number of events per port is exceeded. The maxi‐
mum allowable number of events per port is the minimum value
of the process.max-port-events resource control at the time
port_create(3C) was used to create the port.
EBADF
The port file descriptor is not valid.
EBADFD
The port argument is not an event port file descriptor.
ENOMEM
There is not enough memory available to satisfy the request.
The port_sendn() function will fail if:
EFAULT
The ports[] pointer or errors[] pointer is not reasonable.
EINVAL
The value of the nent argument is 0.
EXAMPLES
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);
USAGE
See setrctl(2) and rctladm(1M) for information on using resource con‐
trols.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬───────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼───────────────────┤
│Architecture │ all │
├────────────────────┼───────────────────┤
│Interface Stability │ Committed │
├────────────────────┼───────────────────┤
│MT-Level │ Async-Signal-Safe │
└────────────────────┴───────────────────┘
SEE ALSOrctladm(1M), setrctl(2), port_alert(3C), port_associate(3C), port_cre‐
ate(3C), port_get(3C), attributes(5)
Oct 24, 2007 PORT_SEND(3C)
