Standard C Library Functions port_get(3C)
NAME
port_get, port_getn - retrieve event information from a port
SYNOPSIS
#include
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 theport_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 alertmode. See port_alert(3C) for details on alert mode.
SunOS 5.11 Last change: 30 Mar 2010 1
Standard C Library Functions port_get(3C)
The port_getn() function can retrieve multiple events from a
port. The list argument is an array of uninitializedport_event_t structures that is filled in by the system when
the port_getn() function returns succesfully. The nget argu-
ment 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 availableon 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() func-
tion 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 succesful 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 accomodate the list of events is not reasonable), or the timeout argument is not reasonable.SunOS 5.11 Last change: 30 Mar 2010 2
Standard C Library Functions port_get(3C)
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 any events were posted to the port.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 ofthe port_send(3C) function.
#include
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 ... */ ...SunOS 5.11 Last change: 30 Mar 2010 3
Standard C Library Functions port_get(3C)
return(...); } ... events = 0x01; /* own event definition(s) */ object =; user =
; 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 =
* pe.portev_user =
*/ ... close(myport);ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:SunOS 5.11 Last change: 30 Mar 2010 4
Standard C Library Functions port_get(3C)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | all ||_____________________________|_____________________________|
| Availability | SUNWcs, system/header ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Safe |
|_____________________________|_____________________________|
SEE ALSO
port_alert(3C), port_associate(3C), port_create(3C),
port_send(3C), attributes(5)
SunOS 5.11 Last change: 30 Mar 2010 5