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.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Architecture | all |
+--------------------+-----------------+
|Interface Stability | Committed |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
close(2),
exit(2),
fork(2),
poll(2),
setrctl(2),
aio_read(3C),
aio_write(3C),
lio_listio(3C),
mq_notify(3C),
port_associate(3C),
port_get(3C),
timer_create(3C),
aio.h(3HEAD),
attributes(7),
rctladm(8) February 17, 2023
PORT_CREATE(3C)