port_send(3c)

1port_send(3C)            Standard C Library Functions            port_send(3C)
2
3
4

NAME

6       port_send,  port_sendn - send a user-defined event to a port or list of
7       ports
8

SYNOPSIS

10       #include <port.h>
11
12       int port_send(int port, int events, void *user);
13
14
15       int port_sendn(int ports[], int errors[], uint_t nent,
16            int events, void *user);
17
18

DESCRIPTION

20       The port_send() function submits a user-defined event  to  a  specified
21       port.  The  port  argument is a file descriptor that represents a port.
22       The sent event has its portev_events member set to the value  specified
23       in  the  events  parameter  and its portev_user member set to the value
24       specified in the user parameter.  The portev_object member of an  event
25       sent with port_send() is unspecified.
26
27
28       The  port_sendn()  function  submits  a  user-defined event to multiple
29       ports. The ports argument is an array of file descriptors  that  repre‐
30       sents ports (see port_create(3C)). The nent argument specifies the num‐
31       ber of file descriptors in the ports[] array. An event is submitted  to
32       each specified port. Each event has its portev_events member set to the
33       value specified in the events parameter and its portev_user member  set
34       to the value specified in the user parameter.  The portev_object member
35       of events sent with port_sendn() is unspecified.
36
37
38       A port that is in alert mode can be sent an event, but that event  will
39       not  be  retrievable  until the port has resumed normal operation.  See
40       port_alert(3C).
41

RETURN VALUES

43       Upon successful completion, the port_send() function returns 0.  Other‐
44       wise, it returns −1 and sets errno to indicate the error.
45
46
47       The  port_sendn() function returns the number of successfully submitted
48       events.  A non-negative return value less than the nent argument  indi‐
49       cates  that  at least one error occurred. In this case, each element of
50       the errors[] array is filled in. An element of the  errors[]  array  is
51       set  to  0 if the event was successfully sent to the corresponding port
52       in the ports[] array, or is set to indicate the error if the event  was
53       not  successfully  sent.  If an error occurs, the port_sendn() function
54       returns −1 and sets errno to indicate the error.
55

ERRORS

57       The port_send() and port_sendn() functions will fail if:
58
59       EAGAIN    The maximum number of events per port is exceeded.  The maxi‐
60                 mum  allowable number of events per port is the minimum value
61                 of the process.max-port-events resource control at  the  time
62                 port_create(3C) was used to create the port.
63
64
65       EBADF     The port file descriptor is not valid.
66
67
68       EBADFD    The port argument is not an event port file descriptor.
69
70
71       ENOMEM    There is not enough memory available to satisfy the request.
72
73
74
75       The port_sendn() function will fail if:
76
77       EFAULT    The ports[] pointer or errors[] pointer is not reasonable.
78
79
80       EINVAL    The value of the nent argument is 0.
81
82

EXAMPLES

84       Example  1 Use port_send() to send a user event (PORT_SOURCE_USER) to a
85       port.
86
87
88       The  following  example  uses  port_send()  to  send   a   user   event
89       (PORT_SOURCE_USER)  to  a  port  and  port_get()  to  retrieve  it. The
90       portev_user and portev_events members of the port_event_t structure are
91       the  same  as  the  corresponding  user  and  events  arguments  of the
92       port_send() function.
93
94
95         #include <port.h>
96
97         int             myport;
98         port_event_t    pe;
99         struct timespec timeout;
100         int             ret;
101         void            *user;
102
103         myport = port_create();
104         if (myport) {
105                 /* port creation failed ... */
106                 ...
107                 return(...);
108         }
109         ...
110         events = 0x01;          /* own event definition(s) */
111         user = <my_own_value>;
112         ret = port_send(myport, events, user);
113         if (ret == -1) {
114                 /* error detected ... */
115                 ...
116                 close(myport);
117                 return (...);
118         }
119
120         /*
121          * The following code could also be executed from another thread or
122          * process.
123          */
124         timeout.tv_sec = 1;     /* user defined */
125         timeout.tv_nsec = 0;
126         ret = port_get(myport, &pe, &timeout);
127         if (ret == -1) {
128                 /*
129                  * error detected :
130                  * - EINTR or ETIME : log error code and try again ...
131                  * - Other kind of errors : may have to close the port ...
132                  */
133                 return(...);
134         }
135
136         /*
137          * After port_get() returns successfully, the port_event_t
138          * structure will be filled with:
139          * pe.portev_source =   PORT_SOURCE_USER
140          * pe.portev_events = 0x01
141          * pe.portev_object = unspecified
142          * pe.portev_user = <my_own_value>
143          */
144         ...
145         close(myport);
146
147

USAGE

149       See setrctl(2) and rctladm(1M) for information on using  resource  con‐
150       trols.
151

ATTRIBUTES

153       See attributes(5) for descriptions of the following attributes:
154
155
156
157
158       ┌─────────────────────────────┬─────────────────────────────┐
159       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
160       ├─────────────────────────────┼─────────────────────────────┤
161       │Architecture                 │all                          │
162       ├─────────────────────────────┼─────────────────────────────┤
163       │Availability                 │SUNWcsr, SUNWhea             │
164       ├─────────────────────────────┼─────────────────────────────┤
165       │Interface Stability          │Committed                    │
166       ├─────────────────────────────┼─────────────────────────────┤
167       │MT-Level                     │Async-Signal-Safe            │
168       └─────────────────────────────┴─────────────────────────────┘
169