Standard C Library Functions portsend(3C)
NAME
portsend, portsendn - send a user-defined event to a port
or list of ports
SYNOPSIS
#include
int portsend(int port, int events, void *user);
int portsendn(int ports[], int errors[], uintt nent,
int events, void *user);
DESCRIPTION
The portsend() 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 portevevents
member set to the value specified in the events parameter
and its portevuser member set to the value specified in the
user parameter. The portevobject member of an event sent
with portsend() is unspecified.
The portsendn() function submits a user-defined event to
multiple ports. The ports argument is an array of file
descriptors that represents ports (see portcreate(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 portevevents member set to the
value specified in the events parameter and its portevuser
member set to the value specified in the user parameter.
The portevobject member of events sent with portsendn() 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 portalert(3C).
RETURN VALUES
Upon successful completion, the portsend() function returns
0. Otherwise, it returns -1 and sets errno to indicate the
error.
The portsendn() 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
SunOS 5.11 Last change: 24 Oct 2007 1
Standard C Library Functions portsend(3C)
ports[] array, or is set to indicate the error if the event
was not successfully sent. If an error occurs, the
portsendn() function returns -1 and sets errno to indicate
the error.
ERORS
The portsend() and portsendn() 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 portcreate(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 portsendn() 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 portsend() to send a user event
(PORTSOURCEUSER) to a port.
The following example uses portsend() to send a user event
(PORTSOURCEUSER) to a port and portget() to retrieve it.
The portevuser and portevevents members of the
porteventt structure are the same as the corresponding
user and events arguments of the portsend() function.
#include
int myport;
porteventt pe;
SunOS 5.11 Last change: 24 Oct 2007 2
Standard C Library Functions portsend(3C)
struct timespec timeout;
int ret;
void *user;
myport = portcreate();
if (myport) {
/* port creation failed ... */
...
return(...);
}
...
events = 0x01; /* own event definition(s) */
user = ;
ret = portsend(myport, events, user);
if (ret == -1) {
/* error detected ... */
...
close(myport);
return (...);
}
/*
* The following code could also be executed from 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 = unspecified
* pe.portevuser =
*/
...
close(myport);
USAGE
See setrctl(2) and rctladm(1M) for information on using
resource controls.
SunOS 5.11 Last change: 24 Oct 2007 3
Standard C Library Functions portsend(3C)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture all
Availability SUNWcsr, SUNWhea
Interface Stability Committed
MT-Level Async-Signal-Safe
SEE ALSO
rctladm(1M), setrctl(2), portalert(3C), portassociate(3C),
portcreate(3C), portget(3C), attributes(5)
SunOS 5.11 Last change: 24 Oct 2007 4
|
