Проект OpenNet: MAN port_send (3) Библиотечные вызовы (FreeBSD и Linux)

Интерактивная система просмотра системных руководств (man-ов)

port_send (3)

>> port_send (3) ( Solaris man: Библиотечные вызовы )

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);