Manual Pages for UNIX Operating System command usage for man port_send

Standard C Library Functions                        port_send(3C)



NAME
     port_send, port_sendn - send a user-defined event to a  port
     or list of ports

SYNOPSIS
     #include 

     int port_send(int port, int events, void *user);


     int port_sendn(int ports[], int errors[], uint_t nent,
          int events, void *user);


DESCRIPTION
     The port_send() function submits a user-defined event  to  a
     specified  port. The port argument is a file descriptor that
     represents a port.  The sent  event  has  its  portev_events
     member  set  to  the value specified in the events parameter
     and its portev_user member set to the value specified in the
     user  parameter.   The portev_object member of an event sent
     with port_send() is unspecified.


     The port_sendn() function submits a  user-defined  event  to
     multiple  ports.  The  ports  argument  is  an array of file
     descriptors that represents ports (see port_create(3C)). The
     nent  argument  specifies  the number of file descriptors in
     the ports[] array. An event is submitted to  each  specified
     port.  Each  event  has  its portev_events member set to the
     value specified in the events parameter and its  portev_user
     member  set  to  the  value specified in the user parameter.
     The portev_object member of events sent with port_sendn() is
     unspecified.


     A port that is in alert mode can be sent an event, but  that
     event  will  not  be  retrievable until the port has resumed
     normal operation.  See port_alert(3C).

RETURN VALUES
     Upon successful completion, the port_send() function returns
     0.   Otherwise, it returns -1 and sets errno to indicate the
     error.


     The port_sendn() function returns the number of successfully
     submitted events.  A non-negative return value less than the
     nent argument indicates that at least one error occurred. In
     this  case, each element of the errors[] array is filled in.
     An element of the errors[] array is set to 0  if  the  event
     was  successfully  sent  to  the  corresponding  port in the



SunOS 5.11          Last change: 24 Oct 2007                    1






Standard C Library Functions                        port_send(3C)



     ports[] array, or is set to indicate the error if the  event
     was   not  successfully  sent.   If  an  error  occurs,  the
     port_sendn() function returns -1 and sets errno to  indicate
     the error.

ERRORS
     The port_send() and port_sendn() functions will fail if:

     EAGAIN    The maximum number of events per port is exceeded.
               The maximum allowable number of events per port is
               the minimum value of  the  process.max-port-events
               resource  control  at the time port_create(3C) was
               used to create the port.


     EBADF     The port file descriptor is not valid.


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


     ENOMEM    There is not enough memory  available  to  satisfy
               the request.



     The port_sendn() function will fail if:

     EFAULT    The ports[] pointer or  errors[]  pointer  is  not
               reasonable.


     EINVAL    The value of the nent argument is 0.


EXAMPLES
     Example  1  Use   port_send()   to   send   a   user   event
     (PORT_SOURCE_USER) to a port.


     The following example uses port_send() to send a user  event
     (PORT_SOURCE_USER)  to a port and port_get() to retrieve it.
     The   portev_user   and   portev_events   members   of   the
     port_event_t  structure  are  the  same as the corresponding
     user and events arguments of the port_send() function.


       #include 

       int             myport;
       port_event_t    pe;



SunOS 5.11          Last change: 24 Oct 2007                    2






Standard C Library Functions                        port_send(3C)



       struct timespec timeout;
       int             ret;
       void            *user;

       myport = port_create();
       if (myport) {
               /* port creation failed ... */
               ...
               return(...);
       }
       ...
       events = 0x01;          /* own event definition(s) */
       user = ;
       ret = port_send(myport, events, user);
       if (ret == -1) {
               /* error detected ... */
               ...
               close(myport);
               return (...);
       }

       /*
        * The following code could also be executed from another thread or
        * process.
        */
       timeout.tv_sec = 1;     /* user defined */
       timeout.tv_nsec = 0;
       ret = port_get(myport, &pe, &timeout);
       if (ret == -1) {
               /*
                * error detected :
                * - EINTR or ETIME : log error code and try again ...
                * - Other kind of errors : may have to close the port ...
                */
               return(...);
       }

       /*
        * After port_get() returns successfully, the port_event_t
        * structure will be filled with:
        * pe.portev_source =   PORT_SOURCE_USER
        * pe.portev_events = 0x01
        * pe.portev_object = unspecified
        * pe.portev_user = 
        */
       ...
       close(myport);


USAGE
     See setrctl(2) and  rctladm(1M)  for  information  on  using
     resource controls.



SunOS 5.11          Last change: 24 Oct 2007                    3






Standard C Library Functions                        port_send(3C)



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                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|


SEE ALSO
     rctladm(1M), setrctl(2), port_alert(3C), port_associate(3C),
     port_create(3C), port_get(3C), attributes(5)

































SunOS 5.11          Last change: 24 Oct 2007                    4