1port_create(3C) Standard C Library Functions port_create(3C)
2
3
4
6 port_create - create a port
7
9 #include <port.h>
10
11 int port_create(void);
12
13
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
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
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
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
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)