PORT_GET(3C) Standard C Library Functions PORT_GET(3C)

NAME


port_get, port_getn - retrieve event information from a port

SYNOPSIS


#include <port.h>

int port_get(int port, port_event_t *pe,
const timespec_t *timeout);


int port_getn(int port, port_event_t list[], uint_t max,
uint_t *nget, const timespec_t *timeout);


DESCRIPTION


The port_get() and port_getn() functions retrieve events from a port. The
port_get() function retrieves at most a single event. The port_getn()
function can retrieve multiple events.


The pe argument points to an uninitialized port_event_t structure that is
filled in by the system when the port_get() function returns
successfully.


The port_event_t structure contains the following members:

int portev_events; /* detected events */
ushort_t portev_source; /* event source */
uintptr_t portev_object; /* specific to event source */
void *portev_user; /* user defined cookie */


The portev_events and portev_object members are specific to the event
source. The portev_events denotes the delivered events. The portev_object
refers to the associated object (see port_create(3C)). The portev_source
member specifies the source of the event. The portev_user member is a
user-specified value.


If the timeout pointer is NULL, the port_get() function blocks until an
event is available. To poll for an event without waiting, timeout should
point to a zeroed timespec. A non-zeroed timespec specifies the desired
time to wait for events. The port_get() function returns before the
timeout elapses if an event is available, a signal occurs, a port is
closed by another thread, or the port is in or enters alert mode. See
port_alert(3C) for details on alert mode.


The port_getn() function can retrieve multiple events from a port. The
list argument is an array of uninitialized port_event_t structures that
is filled in by the system when the port_getn() function returns
successfully. The nget argument points to the desired number of events to
be retrieved. The max parameter specifies the maximum number of events
that can be returned in list[]. If max is 0, the value pointed to by nget
is set to the number of events available on the port. The port_getn()
function returns immediately but no events are retrieved.


The port_getn() function block until the desired number of events are
available, the timeout elapses, a signal occurs, a port is closed by
another thread, or the port is in or enters alert mode.


On return, the value pointed to by nget is updated to the actual number
of events retrieved in list.


Threads calling the port_get() function might starve threads waiting in
the port_getn() function for more than one event. Similarly, threads
calling the port_getn() function for n events might starve threads
waiting in the port_getn() function for more than n events.


The port_get() and the port_getn() functions ignore non-shareable events
(see port_create(3C)) generated by other processes.

RETURN VALUES


Upon successful completion, 0 is returned. Otherwise, -1 is returned and
errno is set to indicate the error.

ERRORS


The port_get() and port_getn() functions will fail if:

EBADF
The port identifier is not valid.


EBADFD
The port argument is not an event port file descriptor.


EFAULT
Event or event list can not be delivered (list[] pointer and/or
user space reserved to accommodate the list of events is not
reasonable), or the timeout argument is not reasonable.


EINTR
A signal was caught during the execution of the function.


EINVAL
The timeout element tv_sec is < 0 or the timeout element
tv_nsec is < 0 or > 1000000000.


ETIME
The time interval expired before the expected number of events
have been posted to the port.


The port_getn() function will fail if:

EINVAL
The list[] argument is NULL, the nget argument is NULL, or the
content of nget is > max and max is > 0.


EFAULT
The timeout argument is not reasonable.


ETIME
The time interval expired before the expected number of events
have been posted to the port (original value in nget), or nget
is updated with the number of returned port_event_t structures
in list[].


EXAMPLES


Example 1: Send a user event (PORT_SOURCE_USER) to a port and retrieve it


with port_get().


The following example sends a user event (PORT_SOURCE_USER) to a port and
retrieves it with port_get(). 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(3C) function.


#include <port.h>

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

myport = port_create();
if (myport < 0) {
/* port creation failed ... */
...
return(...);
}
...
events = 0x01; /* own event definition(s) */
object = <myobject>;
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 in 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 = <myobject>
* pe.portev_user = <my_own_value>
*/
...
close(myport);


ATTRIBUTES


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


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Architecture | all |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+

SEE ALSO


port_alert(3C), port_associate(3C), port_create(3C), port_send(3C),
attributes(7)

April 9, 2016 PORT_GET(3C)