PORT_SEND(3C) Standard C Library Functions 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 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).
RETURN VALUES
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.
ERRORS
The
port_send() and
port_sendn() functions will fail if:
EAGAIN The maximum number of events per port is exceeded. The maximum
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(8) for information on using resource controls.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Architecture | all |
+--------------------+-------------------+
|Interface Stability | Committed |
+--------------------+-------------------+
|MT-Level | Async-Signal-Safe |
+--------------------+-------------------+
SEE ALSO
setrctl(2),
port_alert(3C),
port_associate(3C),
port_create(3C),
port_get(3C),
attributes(7),
rctladm(8) October 24, 2007
PORT_SEND(3C)