Synopsis

Description

The port_associate() function associates specific events of a given object with a
port. Only objects associated with a particular port are able to
generate events that can be retrieved using port_get(3C) or port_getn(3C). The delivery
event has its portev_user member set to the value specified in the
user parameter. If the specified object is already associated with the specified
port, the port_associate() function serves to update the events and user arguments
of the association. The port_dissociate() function removes the association of an
object with a port.

The only objects associated with a port by way of the port_associate()
function are objects of type PORT_SOURCE_FD. Objects of other types have type-specific
association mechanisms. A port_notify_t structure, defined in <port.h>, is used to
specify the event port and an application-defined cookie to associate with these
event sources. See port_create(3C) and signal.h(3HEAD).

Objects of type PORT_SOURCE_FD are file descriptors. The event types for PORT_SOURCE_FD
objects are described in poll(2). At most one event notification will be
generated per associated file descriptor. For example, if a file descriptor
is associated with a port for the POLLRDNORM event and data is
available on the file descriptor at the time the port_associate() function is called,
an event is immediately sent to the port. If data is not
yet available, one event is sent to the port when data first
becomes available.

When an event for a PORT_SOURCE_FD object is retrieved, the object no
longer has an association with the port. The event can be
processed without the possibility that another thread can retrieve a subsequent event
for the same object. After processing of the file descriptor is completed,
the port_associate() function can be called to reassociate the object with the
port.

The parent and child processes are allowed to retrieve events from file
descriptors shared after a call to fork(2). The process performing the first
association with a port (parent or child process) is designated as the owner
of the association. Only the owner of an association is allowed to
dissociate the file descriptor from a port. The association is removed if
the owner of the association closes the port .

Return Values

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

Errors

The port_associate() and port_dissociate() functions will fail if:

EBADF

The port identifier is not valid.

EBADFD

The source argument is of type PORT_SOURCE_FD and the object argument is not a valid file descriptor.

EINVAL

The source argument is not valid.

The port_associate() function will fail if:

EAGAIN

The maximum number of objects associated with the port was exceeded. The maximum allowable number of events or association of objects 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. See setrctl(2) and rctladm(1M) for information on using resource controls.

The number of objects associated with a port is composed of all supported resource types. Some of the source types do not explicitly use the port_associate() function.