Standard C Library Functions                       portalert(3C)



NAME
     portalert - set a port in alert mode

SYNOPSIS
     #include 

     int portalert(int port, int flags, int events, void *user);


DESCRIPTION
     The portalert() function transitions a port into or out  of
     alert  mode.   A  port in alert mode immediately awakens all
     threads blocked  in  portget(3C)  or  portgetn(3C).  These
     threads return with an alert notification that consists of a
     single    porteventt    structure    with    the    source
     PORTSOURCEALERT.  Subsequent  threads  trying  to retrieve
     events from a port that is in alert mode will return immedi-
     ately with the alert notification.


     A port is  transitioned  into  alert  mode  by  calling  the
     portalert() function with a non-zero events parameter.  The
     specified events and user parameters will be made  available
     in  the  portevevents  and  the  portevuser members of the
     alert notification, respectively. The flags argument  deter-
     mines the mode of operation of the alert mode:

         o    If flags is  set  to  PORTALERTSET,  portalert()
              sets  the  port  in  alert  mode independent of the
              current state of the port.  The  portevevents  and
              portevuser members are set or updated accordingly.

         o    If flags is set to PORTALERTUPDATE and  the  port
              is  not in alert mode, portalert() transitions the
              port  into  alert  mode.   The  portevevents   and
              portevuser members are set accordingly.

         o    If flags is set to PORTALERTUPDATE and  the  port
              is already in alert mode, portalert() returns with
              an error value of EBUSY.


     PORTALERTSET and PORTALERTUPDATE are mutually exclusive.


     A port is transitioned out of  alert  mode  by  calling  the
     portalert() function with a zero events parameter.


     Events can be queued to a port that is in  alert  mode,  but
     they  will not be retrievable until the port is transitioned
     out of alert mode.



SunOS 5.11           Last change: 1 Oct 2003                    1






Standard C Library Functions                       portalert(3C)



RETURN VALUES
     Upon succesful completion, 0 is returned. Otherwise,  -1  is
     returned and errno is set to indicate the error.

ERORS
     The portalert() function will fail if:

     EBADF     The port identifier is not valid.


     EBADFD    The port  argument  is  not  an  event  port  file
               descriptor.


     EBUSY     The port is already in alert mode.


     EINVAL    Mutually exclusive flags are set.


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



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


SEE ALSO
     portassociate(3C),      portcreate(3C),      portget(3C),
     portsend(3C), attributes(5)













SunOS 5.11           Last change: 1 Oct 2003                    2