Manual Pages for UNIX Operating System command usage for man port_create

Standard C Library Functions                      port_create(3C)



NAME
     port_create - create a port

SYNOPSIS
     #include 

     int port_create(void);


DESCRIPTION
     The port_create() function establishes a queue  that  multi-
     plexes  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  asyn-
     chronous 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  mechan-
     ism. See mq_notify(3C) for more information.






SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions                      port_create(3C)



     PORT_SOURCE_TIMER events represent one or more timer expira-
     tions  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 associ-
     ated with the port is no longer active. It has to be reasso-
     ciated to activate. A file object is associated or reassoci-
     ated 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  des-
     troyed on last close.


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





SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions                      port_create(3C)



RETURN VALUES
     Upon  succesful  completion,  the   port_create()   function
     returns  a  non-negative  value, the port identifier. Other-
     wise, -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(1M) for information on using resource con-
               trols.


     EMFILE    The process has too many open descriptors.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | all                         |
    |_____________________________|_____________________________|
    | Availability                | SUNWcs, system/header       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


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












SunOS 5.11           Last change: 5 Feb 2008                    3