Standard C Library Functions                      portcreate(3C)



NAME
     portcreate - create a port

SYNOPSIS
     #include 

     int portcreate(void);


DESCRIPTION
     The portcreate() 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
     
     PORTSOURCEAIO      struct aiocb          aioread(3C),
                                                aiowrite(3C),
                                                liolistio(3C)
     PORTSOURCEFD       file descriptor       portassociate(3C)
     PORTSOURCEMQ       mqdt                 mqnotify(3C)
     PORTSOURCETIMER    timert               timercreate(3C)
     PORTSOURCEUSER     uintptrt             portsend(3C)
     PORTSOURCEALERT    uintptrt             portalert(3C)
     PORTSOURCEFILE     fileobjt            portassociate(3C)



     PORTSOURCEAIO events represent the completion of an  asyn-
     chronous I/O transaction. An asynchronous I/O transaction is
     associated with a  port  by  specifying  SIGEVPORT  as  its
     notification  mechanism.  See  aioread(3C),  aiowrite(3C),
     liolistio(3C), and aio.h(3HEAD) for details.


     PORTSOURCEFD 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 portassociate(3C) function.


     PORTSOURCEMQ events represent a message  queue  transition
     from empty to non-empty.  A message queue is associated with
     a port by specifying SIGEVPORT as its notification  mechan-
     ism. See mqnotify(3C) for more information.






SunOS 5.11           Last change: 5 Feb 2008                    1






Standard C Library Functions                      portcreate(3C)



     PORTSOURCETIMER events represent one or more timer expira-
     tions  for a given timer.  A timer is associated with a port
     by specifying SIGEVPORT as its notification mechanism.  See
     timercreate(3C) for more information.


     PORTSOURCEUSER events represent user-defined events. These
     events are generated by portsend(3C) or portsendn(3C).


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


     PORTSOURCEFILE  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 portassociate(3C).


     The portget(3C) and portgetn(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.


     PORTSOURCEUSER and PORTSOURCEALERT events can be distri-
     buted  across  processes.  PORTSOURCEFD events can only be
     shared between processes when child processes inherit opened
     file  decriptors  from  the  parent  process.  See  fork(2).
     PORTSOURCETIMER  and  PORTSOURCEAIO  cannot  be   shared
     between processes.





SunOS 5.11           Last change: 5 Feb 2008                    2






Standard C Library Functions                      portcreate(3C)



RETURN VALUES
     Upon  succesful  completion,  the   portcreate()   function
     returns  a  non-negative  value, the port identifier. Other-
     wise, -1 is returned and errno is set to indicate the error.

ERORS
     The portcreate() 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.


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 all                         
    
     Availability                 SUNWcsr, SUNWhea            
    
     Interface Stability          Committed                   
    
     MT-Level                     Safe                        
    


SEE ALSO
     rctladm(1M),   close(2),    exit(2),    fork(2),    poll(2),
     setrctl(2),   aioread(3C),   aiowrite(3C),   aio.h(3HEAD),
     liolistio(3C),      mqnotify(3C),      portassociate(3C),
     portget(3C), timercreate(3C), attributes(5)












SunOS 5.11           Last change: 5 Feb 2008                    3