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

NAME

6       port_create - create a port
7

SYNOPSIS

9       #include <port.h>
10
11       int port_create(void);
12
13

DESCRIPTION

15       The  port_create() function establishes a queue that multiplexes events
16       from disjoint sources.  Each source has a corresponding object type and
17       source-specific mechanism for associating an object with a port.
18
19
20
21
22             source             object type       association mechanism
23       ─────────────────────────────────────────────────────────────────
24       PORT_SOURCE_AIO      struct aiocb          aio_read(3C),
25                                                  aio_write(3C),
26                                                  lio_listio(3C)
27       PORT_SOURCE_FD       file descriptor       port_associate(3C)
28       PORT_SOURCE_MQ       mqd_t                 mq_notify(3C)
29       PORT_SOURCE_TIMER    timer_t               timer_create(3C)
30       PORT_SOURCE_USER     uintptr_t             port_send(3C)
31       PORT_SOURCE_ALERT    uintptr_t             port_alert(3C)
32       PORT_SOURCE_FILE     file_obj_t            port_associate(3C)
33
34
35
36       PORT_SOURCE_AIO  events represent the completion of an asynchronous I/O
37       transaction. An asynchronous I/O transaction is associated with a  port
38       by   specifying   SIGEV_PORT   as   its   notification  mechanism.  See
39       aio_read(3C),  aio_write(3C),  lio_listio(3C),  and  aio.h(3HEAD)   for
40       details.
41
42
43       PORT_SOURCE_FD events represent a transition in the poll(2) status of a
44       given file descriptor. Once an event is delivered, the file  descriptor
45       is  no longer associated with the port. A file descriptor is associated
46       (or re-associated) with a port using the port_associate(3C) function.
47
48
49       PORT_SOURCE_MQ events represent a message queue transition  from  empty
50       to  non-empty.  A message queue is associated with a port by specifying
51       SIGEV_PORT as its notification mechanism. See  mq_notify(3C)  for  more
52       information.
53
54
55       PORT_SOURCE_TIMER  events represent one or more timer expirations for a
56       given  timer.   A  timer  is  associated  with  a  port  by  specifying
57       SIGEV_PORT as its notification mechanism. See timer_create(3C) for more
58       information.
59
60
61       PORT_SOURCE_USER events represent user-defined events. These events are
62       generated by port_send(3C) or port_sendn(3C).
63
64
65       PORT_SOURCE_ALERT  events  indicate  that  the  port itself is in alert
66       mode.   The  mode  of  the  port  is  changed  with  port_alert(3C).The
67       port_create()  function  returns  a  file  descriptor that represents a
68       newly created port. The close(2) function destroys the port  and  frees
69       all allocated resources.
70
71
72       PORT_SOURCE_FILE events represent file/directory status change. Once an
73       event is delivered, the file object associated  with  the  port  is  no
74       longer  active. It has to be reassociated to activate. A file object is
75       associated or reassociated with a port using the port_associate(3C).
76
77
78       The port_get(3C) and port_getn(3C) functions  retrieve  events  from  a
79       port.  They  ignore  non  retrievable  events (non-own or non-shareable
80       events).
81
82
83       As a port is represented by a file descriptor, ports are shared between
84       child  and  parent  processes after fork().  Both can continue to asso‐
85       ciate sources with the port, both can receive events from the port, and
86       events  associated with and/or generated by either process are retriev‐
87       able in the other. Since some events might not  have  meaning  in  both
88       parent and child, care must be taken when using ports after fork().
89
90
91       If a port is exported to other processes, the port is destroyed on last
92       close.
93
94
95       PORT_SOURCE_USER and PORT_SOURCE_ALERT events can be distributed across
96       processes.  PORT_SOURCE_FD  events can only be shared between processes
97       when child processes inherit opened file  decriptors  from  the  parent
98       process.  See  fork(2). PORT_SOURCE_TIMER and PORT_SOURCE_AIO cannot be
99       shared between processes.
100

RETURN VALUES

102       Upon succesful completion, the port_create() function  returns  a  non-
103       negative  value,  the  port  identifier.  Otherwise, −1 is returned and
104       errno is set to indicate the error.
105

ERRORS

107       The port_create() function will fail if:
108
109       EAGAIN    The maximum allowable number of ports is  currently  open  in
110                 the system. The maximum allowable number of ports is the min‐
111                 imum value of the project.max-port-ids resource control.  See
112                 setrctl(2)  and rctladm(1M) for information on using resource
113                 controls.
114
115
116       EMFILE    The process has too many open descriptors.
117
118

ATTRIBUTES

120       See attributes(5) for descriptions of the following attributes:
121
122
123
124
125       ┌─────────────────────────────┬─────────────────────────────┐
126       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
127       ├─────────────────────────────┼─────────────────────────────┤
128       │Architecture                 │all                          │
129       ├─────────────────────────────┼─────────────────────────────┤
130       │Availability                 │SUNWcsr, SUNWhea             │
131       ├─────────────────────────────┼─────────────────────────────┤
132       │Interface Stability          │Committed                    │
133       ├─────────────────────────────┼─────────────────────────────┤
134       │MT-Level                     │Safe                         │
135       └─────────────────────────────┴─────────────────────────────┘
136

SEE ALSO

138       rctladm(1M),   close(2),   exit(2),   fork(2),   poll(2),   setrctl(2),
139       aio_read(3C),      aio_write(3C),     aio.h(3HEAD),     lio_listio(3C),
140       mq_notify(3C),  port_associate(3C),   port_get(3C),   timer_create(3C),
141       attributes(5)
142
143
144
145SunOS 5.11                        5 Feb 2008                   port_create(3C)
Impressum