port_create(3C)                                                                                                                    port_create(3C)

NAME

       port_create - create a port

SYNOPSIS

       #include <port.h>

       int port_create(void);

       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(3RT),
                                                  aio_write(3RT),
                                                  lio_listio(3RT)
       PORT_SOURCE_FD       file descriptor       port_associate(3C)
       PORT_SOURCE_TIMER    timer_t               timer_create(3RT)
       PORT_SOURCE_USER     uintptr_t             port_send(3C)
       PORT_SOURCE_ALERT    uintptr_t             port_alert(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(3RT), aio_write(3RT), lio_listio(3RT), 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_asso-
       ciate(3C) function.

       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(3RT) 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_cre-
       ate() function returns a file descriptor that represents a newly created port. The close(2) function destroys the port and frees all  allo-
       cated resources.

       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  as-
       sociate  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 pro-
       cesses when child processes inherit opened file decriptors from the parent process. See fork(2). PORT_SOURCE_TIMER and PORT_SOURCE_AIO can-
       not be shared between processes.

       Upon  succesful  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.

       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(1M) for information on using resource con-
                       trols.

       EMFILE          The process has too many open descriptors.

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Architecture                 |all                          |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWcsr, SUNWhea             |
       +-----------------------------+-----------------------------+
       |Interface Stability          |Evolving                     |
       +-----------------------------+-----------------------------+
       |MT-Level                     |Safe                         |
       +-----------------------------+-----------------------------+

       rctladm(1M), close(2), exit(2), fork(2), poll(2), setrctl(2), aio_read(3RT), aio_write(3RT), aio.h(3HEAD),  lio_listio(3RT),  port_get(3C),
       timer_create(3RT), attributes(5)

                                                                    22 Feb 2005                                                    port_create(3C)