Standard C Library Functions portget(3C)
NAME
portget, portgetn - retrieve event information from a port
SYNOPSIS
#include
int portget(int port, porteventt *pe,
const timespect *timeout);
int portgetn(int port, porteventt list[], uintt max,
uintt *nget, const timespect *timeout);
DESCRIPTION
The portget() and portgetn() functions retrieve events
from a port. The portget() function retrieves at most a
single event. The portgetn() function can retrieve multiple
events.
The pe argument points to an uninitialized porteventt
structure that is filled in by the system when the
portget() function returns successfully.
The porteventt structure contains the following members:
int portevevents; /* detected events */
ushortt portevsource; /* event source */
uintptrt portevobject; /* specific to event source */
void *portevuser; /* user defined cookie */
The portevevents and portevobject members are specific to
the event source. The portevevents denotes the delivered
events. The portevobject refers to the associated object
(see portcreate(3C)). The portevsource member specifies
the source of the event. The portevuser member is a user-
specified value.
If the timeout pointer is NUL, the portget() 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 portget() 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 portalert(3C) for details on alert mode.
SunOS 5.11 Last change: 31 Jan 2007 1
Standard C Library Functions portget(3C)
The portgetn() function can retrieve multiple events from a
port. The list argument is an array of uninitialized
porteventt structures that is filled in by the system when
the portgetn() 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 available
on the port. The portgetn() function returns immediately
but no events are retrieved.
The portgetn() 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 portget() function might starve threads
waiting in the portgetn() function for more than one event.
Similarly, threads calling the portgetn() function for n
events might starve threads waiting in the portgetn() func-
tion for more than n events.
The portget() and the portgetn() functions ignore non-
shareable events (see portcreate(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.
ERORS
The portget() and portgetn() 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: 31 Jan 2007 2
Standard C Library Functions portget(3C)
EINTR A signal was caught during the execution of the
function.
EINVAL The timeout element tvsec is < 0 or the timeout
element tvnsec is < 0 or > 1000000000.
ETIME The time interval expired before the expected
number of events have been posted to the port.
The portgetn() function will fail if:
EINVAL The list[] argument is NUL, the nget argument is
NUL, 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 porteventt structures in
list[].
EXAMPLES
Example 1 Send a user event (PORTSOURCEUSER) to a port and
retrieve it with portget().
The following example sends a user event (PORTSOURCEUSER)
to a port and retrieves it with portget(). The portevuser
and portevevents members of the porteventt structure are
the same as the corresponding user and events arguments of
the portsend(3C) function.
#include
int myport;
porteventt pe;
struct timespec timeout;
int ret;
void *user;
uintptrt object;
myport = portcreate();
SunOS 5.11 Last change: 31 Jan 2007 3
Standard C Library Functions portget(3C)
if (myport < 0) {
/* port creation failed ... */
...
return(...);
}
...
events = 0x01; /* own event definition(s) */
object = ;
user = ;
ret = portsend(myport, events, user);
if (ret == -1) {
/* error detected ... */
...
close(myport);
return (...);
}
/*
* The following code could also be executed in another thread or
* process.
*/
timeout.tvsec = 1; /* user defined */
timeout.tvnsec = 0;
ret = portget(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 portget() returns successfully, the porteventt
* structure will be filled with:
* pe.portevsource = PORTSOURCEUSER
* pe.portevevents = 0x01
* pe.portevobject =
* pe.portevuser =
*/
...
close(myport);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 31 Jan 2007 4
Standard C Library Functions portget(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture all
Availability SUNWcsr, SUNWhea
Interface Stability Evolving
MT-Level Safe
SEE ALSO
portalert(3C), portassociate(3C), portcreate(3C),
portsend(3C), attributes(5)
SunOS 5.11 Last change: 31 Jan 2007 5
|
