Tribblix: manual page: port

PORT_CREATE(3C) Standard C Library Functions PORT_CREATE(3C)

NAME

port_create - create a port

SYNOPSIS

#include <port.h>

int port_create(void);

DESCRIPTION

The port_create() function establishes a queue that multiplexes
events from disjoint sources. Each source has a corresponding object
type and source-specific mechanism for associating an object with a
port.

source object type association mechanism
------------------------------------------------------------
PORT_SOURCE_AIO struct aiocb aio_read(3C),
aio_write(3C),
lio_listio(3C)
PORT_SOURCE_FD file descriptor port_associate(3C)
PORT_SOURCE_MQ mqd_t mq_notify(3C)
PORT_SOURCE_TIMER timer_t timer_create(3C)
PORT_SOURCE_USER uintptr_t port_send(3C)
PORT_SOURCE_ALERT uintptr_t port_alert(3C)
PORT_SOURCE_FILE file_obj_t port_associate(3C)

PORT_SOURCE_AIO events represent the completion of an asynchronous
I/O transaction. An asynchronous I/O transaction is associated with a
port by specifying SIGEV_PORT as its notification mechanism. See
aio_read(3C), aio_write(3C), lio_listio(3C), and aio.h(3HEAD) for
details.

PORT_SOURCE_FD events represent a transition in the poll(2) status of
a given file descriptor. Once an event is delivered, the file
descriptor is no longer associated with the port. A file descriptor
is associated (or re-associated) with a port using the
port_associate(3C) function.

PORT_SOURCE_MQ events represent a message queue transition from empty
to non-empty. A message queue is associated with a port by
specifying SIGEV_PORT as its notification mechanism. See
mq_notify(3C) for more information.

PORT_SOURCE_TIMER events represent one or more timer expirations for
a given timer. A timer is associated with a port by specifying
SIGEV_PORT as its notification mechanism. See timer_create(3C) for
more information.

PORT_SOURCE_USER events represent user-defined events. These events
are generated by port_send(3C) or port_sendn(3C).

PORT_SOURCE_ALERT events indicate that the port itself is in alert
mode. The mode of the port is changed with port_alert(3C). The
port_create() function returns a file descriptor that represents a
newly created port. The close(2) function destroys the port and frees
all allocated resources.

PORT_SOURCE_FILE events represent file/directory status change. Once
an event is delivered, the file object associated with the port is no
longer active. It has to be reassociated to activate. A file object
is associated or reassociated with a port using the
port_associate(3C).

The port_get(3C) and port_getn(3C) functions retrieve events from a
port. They ignore non retrievable events (non-own or non-shareable
events).

As a port is represented by a file descriptor, ports are shared
between child and parent processes after fork(). Both can continue
to associate sources with the port, both can receive events from the
port, and events associated with and/or generated by either process
are retrievable in the other. Since some events might not have
meaning in both parent and child, care must be taken when using ports
after fork().

If a port is exported to other processes, the port is destroyed on
last close.

PORT_SOURCE_USER and PORT_SOURCE_ALERT events can be distributed
across processes. PORT_SOURCE_FD events can only be shared between
processes when child processes inherit opened file descriptors from
the parent process. See fork(2). PORT_SOURCE_TIMER and
PORT_SOURCE_AIO cannot be shared between processes.

RETURN VALUES

Upon successful completion, the port_create() function returns a non-
negative value, the port identifier. Otherwise, -1 is returned and
errno is set to indicate the error.

ERRORS

The port_create() function will fail if:

EAGAIN
The maximum allowable number of ports is currently open in
the system. The maximum allowable number of ports is the
minimum value of the project.max-port-ids resource control.
See setrctl(2) and rctladm(8) for information on using
resource controls.

EMFILE
The process has too many open descriptors.