Print this page
10596 Convert streamio(7I) to mandoc
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man7i/streamio.7i.man.txt
+++ new/usr/src/man/man7i/streamio.7i.man.txt
1 1 STREAMIO(7I) Ioctl Requests STREAMIO(7I)
2 2
3 -
4 -
5 3 NAME
6 - streamio - STREAMS ioctl commands
4 + streamio - STREAMS ioctl commands
7 5
8 6 SYNOPSIS
9 - #include <sys/types.h>
10 - #include <stropts.h>
11 - #include <sys/conf.h>
7 + #include <sys/types.h>
8 + #include <stropts.h>
9 + #include <sys/conf.h>
12 10
13 - int ioctl(int fildes, int command, ... /*arg*/);
11 + int
12 + ioctl(int fildes, int command, ... /*arg*/);
14 13
15 -
16 14 DESCRIPTION
17 - STREAMS (see Intro(3)) ioctl commands are a subset of the ioctl(2)
18 - commands and perform a variety of control functions on streams.
15 + STREAMS (see Intro(3)) ioctl() commands are a subset of the ioctl(2)
16 + commands and perform a variety of control functions on streams.
19 17
18 + The fildes argument is an open file descriptor that refers to a stream.
19 + The command argument determines the control function to be performed as
20 + described below. The arg argument represents additional information that
21 + is needed by this command. The type of arg depends upon the command, but
22 + it is generally an integer or a pointer to a command-specific data
23 + structure. The command and arg arguments are interpreted by the STREAM
24 + head. Certain combinations of these arguments may be passed to a module
25 + or driver in the stream.
20 26
21 - The fildes argument is an open file descriptor that refers to a stream.
22 - The command argument determines the control function to be performed as
23 - described below. The arg argument represents additional information
24 - that is needed by this command. The type of arg depends upon the
25 - command, but it is generally an integer or a pointer to a command-
26 - specific data structure. The command and arg arguments are interpreted
27 - by the STREAM head. Certain combinations of these arguments may be
28 - passed to a module or driver in the stream.
27 + Since these STREAMS commands are ioctls, they are subject to the errors
28 + described in ioctl(2). In addition to those errors, the call will fail
29 + with errno set to EINVAL, without processing a control function, if the
30 + STREAM referenced by fildes is linked below a multiplexor, or if command
31 + is not a valid value for a stream.
29 32
33 + Also, as described in ioctl(2), STREAMS modules and drivers can detect
34 + errors. In this case, the module or driver sends an error message to the
35 + STREAM head containing an error value. This causes subsequent calls to
36 + fail with errno set to this value.
30 37
31 - Since these STREAMS commands are ioctls, they are subject to the errors
32 - described in ioctl(2). In addition to those errors, the call will fail
33 - with errno set to EINVAL, without processing a control function, if the
34 - STREAM referenced by fildes is linked below a multiplexor, or if
35 - command is not a valid value for a stream.
36 -
37 -
38 - Also, as described in ioctl(2), STREAMS modules and drivers can detect
39 - errors. In this case, the module or driver sends an error message to
40 - the STREAM head containing an error value. This causes subsequent calls
41 - to fail with errno set to this value.
42 -
43 38 IOCTLS
44 - The following ioctl commands, with error values indicated, are
45 - applicable to all STREAMS files:
39 + The following ioctl() commands, with error values indicated, are
40 + applicable to all STREAMS files:
46 41
47 - I_PUSH
48 - Pushes the module whose name is pointed to by arg onto
49 - the top of the current stream, just below the STREAM
50 - head. If the STREAM is a pipe, the module will be
51 - inserted between the stream heads of both ends of the
52 - pipe. It then calls the open routine of the newly-pushed
53 - module. On failure, errno is set to one of the following
54 - values:
42 + I_PUSH Pushes the module whose name is pointed to by arg onto the
43 + top of the current stream, just below the STREAM head. If
44 + the STREAM is a pipe, the module will be inserted between
45 + the stream heads of both ends of the pipe. It then calls
46 + the open routine of the newly-pushed module. On failure,
47 + errno is set to one of the following values:
55 48
56 - EINVAL
57 - Invalid module name.
49 + EINVAL Invalid module name.
58 50
51 + EFAULT arg points outside the allocated address space.
59 52
60 - EFAULT
61 - arg points outside the allocated address
62 - space.
53 + ENXIO Open routine of new module failed.
63 54
55 + ENXIO Hangup received on fildes.
64 56
65 - ENXIO
66 - Open routine of new module failed.
57 + ENOTSUP Pushing a module is not supported on this stream.
67 58
59 + I_POP Removes the module just below the STREAM head of the STREAM
60 + pointed to by fildes. To remove a module from a pipe
61 + requires that the module was pushed on the side it is being
62 + removed from. arg should be 0 in an I_POP request. On
63 + failure, errno is set to one of the following values:
68 64
69 - ENXIO
70 - Hangup received on fildes.
65 + EINVAL No module present in the stream.
71 66
67 + ENXIO Hangup received on fildes.
72 68
73 - ENOTSUP
74 - Pushing a module is not supported on this
75 - stream.
69 + EPERM Attempt to pop through an anchor by an unprivileged
70 + process.
76 71
72 + ENOTSUP Removal is not supported.
77 73
74 + I_ANCHOR Positions the stream anchor to be at the stream's module
75 + directly below the stream head. Once this has been done,
76 + only a privileged process may pop modules below the anchor
77 + on the stream. arg must be 0 in an I_ANCHOR request. On
78 + failure, errno is set to the following value:
78 79
79 - I_POP
80 - Removes the module just below the STREAM head of the
81 - STREAM pointed to by fildes. To remove a module from a
82 - pipe requires that the module was pushed on the side it
83 - is being removed from. arg should be 0 in an I_POP
84 - request. On failure, errno is set to one of the
85 - following values:
80 + EINVAL Request to put an anchor on a pipe.
86 81
87 - EINVAL
88 - No module present in the stream.
82 + I_LOOK Retrieves the name of the module just below the stream head
83 + of the stream pointed to by fildes, and places it in a null
84 + terminated character string pointed at by arg. The buffer
85 + pointed to by arg should be at least FMNAMESZ+1 bytes long.
86 + This requires the declaration `#include <sys/conf.h>'. On
87 + failure, errno is set to one of the following values:
89 88
89 + EFAULT arg points outside the allocated address space.
90 90
91 - ENXIO
92 - Hangup received on fildes.
91 + EINVAL No module present in stream.
93 92
93 + I_FLUSH This request flushes all input and/or output queues,
94 + depending on the value of arg. Legal arg values are:
94 95
95 - EPERM
96 - Attempt to pop through an anchor by an
97 - unprivileged process.
96 + FLUSHR Flush read queues.
98 97
98 + FLUSHW Flush write queues.
99 99
100 - ENOTSUP
101 - Removal is not supported.
100 + FLUSHRW Flush read and write queues.
102 101
102 + If a pipe or FIFO does not have any modules pushed, the read
103 + queue of the stream head on either end is flushed depending
104 + on the value of arg.
103 105
106 + If FLUSHR is set and fildes is a pipe, the read queue for
107 + that end of the pipe is flushed and the write queue for the
108 + other end is flushed. If fildes is a FIFO, both queues are
109 + flushed.
104 110
105 - I_ANCHOR
106 - Positions the stream anchor to be at the stream's module
107 - directly below the stream head. Once this has been done,
108 - only a privileged process may pop modules below the
109 - anchor on the stream. arg must be 0 in an I_ANCHOR
110 - request. On failure, errno is set to the following
111 - value:
111 + If FLUSHW is set and fildes is a pipe and the other end of
112 + the pipe exists, the read queue for the other end of the
113 + pipe is flushed and the write queue for this end is flushed.
114 + If fildes is a FIFO, both queues of the FIFO are flushed.
112 115
113 - EINVAL
114 - Request to put an anchor on a pipe.
116 + If FLUSHRW is set, all read queues are flushed, that is, the
117 + read queue for the FIFO and the read queue on both ends of
118 + the pipe are flushed.
115 119
120 + Correct flush handling of a pipe or FIFO with modules pushed
121 + is achieved via the pipemod module. This module should be
122 + the first module pushed onto a pipe so that it is at the
123 + midpoint of the pipe itself.
116 124
125 + On failure, errno is set to one of the following values:
117 126
118 - I_LOOK
119 - Retrieves the name of the module just below the stream
120 - head of the stream pointed to by fildes, and places it
121 - in a null terminated character string pointed at by arg.
122 - The buffer pointed to by arg should be at least
123 - FMNAMESZ+1 bytes long. This requires the declaration
124 - #include <sys/conf.h>. On failure, errno is set to one
125 - of the following values:
127 + ENOSR Unable to allocate buffers for flush message due to
128 + insufficient stream memory resources.
126 129
127 - EFAULT
128 - arg points outside the allocated address
129 - space.
130 + EINVAL Invalid arg value.
130 131
132 + ENXIO Hangup received on fildes.
131 133
132 - EINVAL
133 - No module present in stream.
134 + I_FLUSHBAND Flushes a particular band of messages. arg points to a
135 + bandinfo structure that has the following members:
134 136
137 + unsigned char bi_pri;
138 + int bi_flag;
135 139
140 + The bi_flag field may be one of FLUSHR, FLUSHW, or FLUSHRW
141 + as described earlier.
136 142
137 - I_FLUSH
138 - This request flushes all input and/or output queues,
139 - depending on the value of arg. Legal arg values are:
143 + I_SETSIG Informs the stream head that the user wishes the kernel to
144 + issue the SIGPOLL signal (see signal(3C)) when a particular
145 + event has occurred on the stream associated with fildes.
146 + I_SETSIG supports an asynchronous processing capability in
147 + streams. The value of arg is a bitmask that specifies the
148 + events for which the user should be signaled. It is the
149 + bitwise OR of any combination of the following constants:
140 150
141 - FLUSHR
142 - Flush read queues.
151 + S_INPUT Any message other than an M_PCPROTO has arrived
152 + on a stream head read queue. This event is
153 + maintained for compatibility with previous
154 + releases. This event is triggered even if the
155 + message is of zero length.
143 156
157 + S_RDNORM An ordinary (non-priority) message has arrived on
158 + a stream head read queue. This event is
159 + triggered even if the message is of zero length.
144 160
145 - FLUSHW
146 - Flush write queues.
161 + S_RDBAND A priority band message (band > 0) has arrived on
162 + a stream head read queue. This event is
163 + triggered even if the message is of zero length.
147 164
165 + S_HIPRI A high priority message is present on the stream
166 + head read queue. This event is triggered even if
167 + the message is of zero length.
148 168
149 - FLUSHRW
150 - Flush read and write queues.
169 + S_OUTPUT The write queue just below the stream head is no
170 + longer full. This notifies the user that there
171 + is room on the queue for sending (or writing)
172 + data downstream.
151 173
152 - If a pipe or FIFO does not have any modules pushed, the
153 - read queue of the stream head on either end is flushed
154 - depending on the value of arg.
174 + S_WRNORM This event is the same as S_OUTPUT.
155 175
156 - If FLUSHR is set and fildes is a pipe, the read queue
157 - for that end of the pipe is flushed and the write queue
158 - for the other end is flushed. If fildes is a FIFO, both
159 - queues are flushed.
176 + S_WRBAND A priority band greater than 0 of a queue
177 + downstream exists and is writable. This notifies
178 + the user that there is room on the queue for
179 + sending (or writing) priority data downstream.
160 180
161 - If FLUSHW is set and fildes is a pipe and the other end
162 - of the pipe exists, the read queue for the other end of
163 - the pipe is flushed and the write queue for this end is
164 - flushed. If fildes is a FIFO, both queues of the FIFO
165 - are flushed.
181 + S_MSG A STREAMS signal message that contains the
182 + SIGPOLL signal has reached the front of the
183 + stream head read queue.
166 184
167 - If FLUSHRW is set, all read queues are flushed, that is,
168 - the read queue for the FIFO and the read queue on both
169 - ends of the pipe are flushed.
185 + S_ERROR An M_ERROR message has reached the stream head.
170 186
171 - Correct flush handling of a pipe or FIFO with modules
172 - pushed is achieved via the pipemod module. This module
173 - should be the first module pushed onto a pipe so that it
174 - is at the midpoint of the pipe itself.
187 + S_HANGUP An M_HANGUP message has reached the stream head.
175 188
176 - On failure, errno is set to one of the following values:
189 + S_BANDURG When used in conjunction with S_RDBAND, SIGURG is
190 + generated instead of SIGPOLL when a priority
191 + message reaches the front of the stream head read
192 + queue.
177 193
178 - ENOSR
179 - Unable to allocate buffers for flush message
180 - due to insufficient stream memory resources.
194 + A user process may choose to be signaled only of high
195 + priority messages by setting the arg bitmask to the value
196 + S_HIPRI.
181 197
198 + Processes that wish to receive SIGPOLL signals must
199 + explicitly register to receive them using I_SETSIG. If
200 + several processes register to receive this signal for the
201 + same event on the same stream, each process will be signaled
202 + when the event occurs.
182 203
183 - EINVAL
184 - Invalid arg value.
204 + If the value of arg is zero, the calling process will be
205 + unregistered and will not receive further SIGPOLL signals.
206 + On failure, errno is set to one of the following values:
185 207
208 + EINVAL arg value is invalid or arg is zero and process is
209 + not registered to receive the SIGPOLL signal.
186 210
187 - ENXIO
188 - Hangup received on fildes.
211 + EAGAIN Allocation of a data structure to store the signal
212 + request failed.
189 213
214 + I_GETSIG Returns the events for which the calling process is
215 + currently registered to be sent a SIGPOLL signal. The
216 + events are returned as a bitmask pointed to by arg, where
217 + the events are those specified in the description of
218 + I_SETSIG above. On failure, errno is set to one of the
219 + following values:
190 220
221 + EINVAL Process not registered to receive the SIGPOLL
222 + signal.
191 223
192 - I_FLUSHBAND
193 - Flushes a particular band of messages. arg points to a
194 - bandinfo structure that has the following members:
224 + EFAULT arg points outside the allocated address space.
195 225
196 - unsigned char bi_pri;
197 - int bi_flag;
226 + I_FIND Compares the names of all modules currently present in the
227 + stream to the name pointed to by arg, and returns 1 if the
228 + named module is present in the stream. It returns 0 if the
229 + named module is not present. On failure, errno is set to
230 + one of the following values:
198 231
199 - The bi_flag field may be one of FLUSHR, FLUSHW, or
200 - FLUSHRW as described earlier.
232 + EFAULT arg points outside the allocated address space.
201 233
234 + EINVAL arg does not contain a valid module name.
202 235
203 - I_SETSIG
204 - Informs the stream head that the user wishes the kernel
205 - to issue the SIGPOLL signal (see signal(3C)) when a
206 - particular event has occurred on the stream associated
207 - with fildes. I_SETSIG supports an asynchronous
208 - processing capability in streams. The value of arg is a
209 - bitmask that specifies the events for which the user
210 - should be signaled. It is the bitwise OR of any
211 - combination of the following constants:
236 + I_PEEK Allows a user to retrieve the information in the first
237 + message on the stream head read queue without taking the
238 + message off the queue. I_PEEK is analogous to getmsg(2)
239 + except that it does not remove the message from the queue.
240 + arg points to a strpeek structure, which contains the
241 + following members:
212 242
213 - S_INPUT
214 - Any message other than an M_PCPROTO has
215 - arrived on a stream head read queue. This
216 - event is maintained for compatibility with
217 - previous releases. This event is triggered
218 - even if the message is of zero length.
243 + struct strbuf ctlbuf;
244 + struct strbuf databuf;
245 + long flags;
219 246
247 + The maxlen field in the ctlbuf and databuf strbuf structures
248 + (see getmsg(2)) must be set to the number of bytes of
249 + control information and/or data information, respectively,
250 + to retrieve. flags may be set to RS_HIPRI or 0. If
251 + RS_HIPRI is set, I_PEEK will look for a high priority
252 + message on the stream head read queue. Otherwise, I_PEEK
253 + will look for the first message on the stream head read
254 + queue.
220 255
221 - S_RDNORM
222 - An ordinary (non-priority) message has
223 - arrived on a stream head read queue. This
224 - event is triggered even if the message is
225 - of zero length.
256 + I_PEEK returns 1 if a message was retrieved, and returns 0
257 + if no message was found on the stream head read queue. It
258 + does not wait for a message to arrive. On return, ctlbuf
259 + specifies information in the control buffer, databuf
260 + specifies information in the data buffer, and flags contains
261 + the value RS_HIPRI or 0. On failure, errno is set to the
262 + following value:
226 263
264 + EFAULT arg points, or the buffer area specified in ctlbuf
265 + or databuf is, outside the allocated address space.
227 266
228 - S_RDBAND
229 - A priority band message (band > 0) has
230 - arrived on a stream head read queue. This
231 - event is triggered even if the message is
232 - of zero length.
267 + EBADMSG Queued message to be read is not valid for I_PEEK.
233 268
269 + EINVAL Illegal value for flags.
234 270
235 - S_HIPRI
236 - A high priority message is present on the
237 - stream head read queue. This event is
238 - triggered even if the message is of zero
239 - length.
271 + ENOSR Unable to allocate buffers to perform the I_PEEK
272 + due to insufficient STREAMS memory resources.
240 273
274 + I_SRDOPT Sets the read mode (see read(2)) using the value of the
275 + argument arg. Legal arg values are:
241 276
242 - S_OUTPUT
243 - The write queue just below the stream head
244 - is no longer full. This notifies the user
245 - that there is room on the queue for sending
246 - (or writing) data downstream.
277 + RNORM Byte-stream mode, the default.
247 278
279 + RMSGD Message-discard mode.
248 280
249 - S_WRNORM
250 - This event is the same as S_OUTPUT.
281 + RMSGN Message-nondiscard mode.
251 282
283 + In addition, the stream head's treatment of control messages
284 + may be changed by setting the following flags in arg:
252 285
253 - S_WRBAND
254 - A priority band greater than 0 of a queue
255 - downstream exists and is writable. This
256 - notifies the user that there is room on the
257 - queue for sending (or writing) priority
258 - data downstream.
286 + RPROTNORM Reject read(2) with EBADMSG if a control message
287 + is at the front of the stream head read queue.
259 288
289 + RPROTDAT Deliver the control portion of a message as data
290 + when a user issues read(2). This is the default
291 + behavior.
260 292
261 - S_MSG
262 - A STREAMS signal message that contains the
263 - SIGPOLL signal has reached the front of the
264 - stream head read queue.
293 + RPROTDIS Discard the control portion of a message,
294 + delivering any data portion, when a user issues a
295 + read(2).
265 296
297 + On failure, errno is set to the following value:
266 298
267 - S_ERROR
268 - An M_ERROR message has reached the stream
269 - head.
299 + EINVAL arg is not one of the above legal values, or arg is
300 + the bitwise inclusive OR of RMSGD and RMSGN.
270 301
302 + I_GRDOPT Returns the current read mode setting in an int pointed to
303 + by the argument arg. Read modes are described in read(2).
304 + On failure, errno is set to the following value:
271 305
272 - S_HANGUP
273 - An M_HANGUP message has reached the stream
274 - head.
306 + EFAULT arg points outside the allocated address space.
275 307
308 + I_NREAD Counts the number of data bytes in data blocks in the first
309 + message on the stream head read queue, and places this value
310 + in the location pointed to by arg. The return value for the
311 + command is the number of messages on the stream head read
312 + queue. For example, if zero is returned in arg, but the
313 + ioctl() return value is greater than zero, this indicates
314 + that a zero-length message is next on the queue. On
315 + failure, errno is set to the following value:
276 316
277 - S_BANDURG
278 - When used in conjunction with S_RDBAND,
279 - SIGURG is generated instead of SIGPOLL when
280 - a priority message reaches the front of the
281 - stream head read queue.
317 + EFAULT arg points outside the allocated address space.
282 318
283 - A user process may choose to be signaled only of high
284 - priority messages by setting the arg bitmask to the
285 - value S_HIPRI.
319 + I_FDINSERT Creates a message from specified buffer(s), adds information
320 + about another stream and sends the message downstream. The
321 + message contains a control part and an optional data part.
322 + The data and control parts to be sent are distinguished by
323 + placement in separate buffers, as described below.
286 324
287 - Processes that wish to receive SIGPOLL signals must
288 - explicitly register to receive them using I_SETSIG. If
289 - several processes register to receive this signal for
290 - the same event on the same stream, each process will be
291 - signaled when the event occurs.
325 + The arg argument points to a strfdinsert structure, which
326 + contains the following members:
292 327
293 - If the value of arg is zero, the calling process will be
294 - unregistered and will not receive further SIGPOLL
295 - signals. On failure, errno is set to one of the
296 - following values:
328 + struct strbuf ctlbuf;
329 + struct strbuf databuf;
330 + t_uscalar_t flags;
331 + int fildes;
332 + int offset;
297 333
298 - EINVAL
299 - arg value is invalid or arg is zero and
300 - process is not registered to receive the
301 - SIGPOLL signal.
334 + The len member in the ctlbuf strbuf structure (see
335 + putmsg(2)) must be set to the size of a t_uscalar_t plus the
336 + number of bytes of control information to be sent with the
337 + message. The fildes member specifies the file descriptor of
338 + the other stream, and the offset member, which must be
339 + suitably aligned for use as a t_uscalar_t, specifies the
340 + offset from the start of the control buffer where I_FDINSERT
341 + will store a t_uscalar_t whose interpretation is specific to
342 + the stream end. The len member in the databuf strbuf
343 + structure must be set to the number of bytes of data
344 + information to be sent with the message, or to 0 if no data
345 + part is to be sent.
302 346
347 + The flags member specifies the type of message to be
348 + created. A normal message is created if flags is set to 0,
349 + and a high-priority message is created if flags is set to
350 + RS_HIPRI. For non-priority messages, I_FDINSERT will block
351 + if the stream write queue is full due to internal flow
352 + control conditions. For priority messages, I_FDINSERT does
353 + not block on this condition. or non-priority messages,
354 + I_FDINSERT does not block when the write queue is full and
355 + O_NDELAY or O_NONBLOCK is set. Instead, it fails and sets
356 + errno to EAGAIN.
303 357
304 - EAGAIN
305 - Allocation of a data structure to store the
306 - signal request failed.
358 + I_FDINSERT also blocks, unless prevented by lack of internal
359 + resources, waiting for the availability of message blocks in
360 + the stream, regardless of priority or whether O_NDELAY or
361 + O_NONBLOCK has been specified. No partial message is sent.
307 362
363 + The ioctl() function with the I_FDINSERT command will fail
364 + if:
308 365
366 + EAGAIN A non-priority message is specified, the O_NDELAY or
367 + O_NONBLOCK flag is set, and the stream write queue
368 + is full due to internal flow control conditions.
309 369
310 - I_GETSIG
311 - Returns the events for which the calling process is
312 - currently registered to be sent a SIGPOLL signal. The
313 - events are returned as a bitmask pointed to by arg,
314 - where the events are those specified in the description
315 - of I_SETSIG above. On failure, errno is set to one of
316 - the following values:
370 + ENOSR Buffers can not be allocated for the message that is
371 + to be created.
317 372
318 - EINVAL
319 - Process not registered to receive the SIGPOLL
320 - signal.
373 + EFAULT The arg argument points, or the buffer area
374 + specified in ctlbuf or databuf is, outside the
375 + allocated address space.
321 376
377 + EINVAL One of the following: The fildes member of the
378 + strfdinsert structure is not a valid, open stream
379 + file descriptor; the size of a t_uscalar_t plus
380 + offset is greater than the len member for the buffer
381 + specified through ctlptr; the offset member does not
382 + specify a properly-aligned location in the data
383 + buffer; or an undefined value is stored in flags.
322 384
323 - EFAULT
324 - arg points outside the allocated address
325 - space.
385 + ENXIO Hangup received on the fildes argument of the
386 + ioctl() call or the fildes member of the strfdinsert
387 + structure.
326 388
389 + ERANGE The len field for the buffer specified through
390 + databuf does not fall within the range specified by
391 + the maximum and minimum packet sizes of the topmost
392 + stream module; or the len member for the buffer
393 + specified through databuf is larger than the maximum
394 + configured size of the data part of a message; or
395 + the len member for the buffer specified through
396 + ctlbuf is larger than the maximum configured size of
397 + the control part of a message.
327 398
399 + I_FDINSERT can also fail if an error message was received by
400 + the stream head of the stream corresponding to the fildes
401 + member of the strfdinsert structure. In this case, errno
402 + will be set to the value in the message.
328 403
329 - I_FIND
330 - Compares the names of all modules currently present in
331 - the stream to the name pointed to by arg, and returns 1
332 - if the named module is present in the stream. It returns
333 - 0 if the named module is not present. On failure, errno
334 - is set to one of the following values:
404 + I_STR Constructs an internal STREAMS ioctl message from the data
405 + pointed to by arg, and sends that message downstream.
335 406
336 - EFAULT
337 - arg points outside the allocated address
338 - space.
407 + This mechanism is provided to send user ioctl() requests to
408 + downstream modules and drivers. It allows information to be
409 + sent with the ioctl(), and will return to the user any
410 + information sent upstream by the downstream recipient.
411 + I_STR blocks until the system responds with either a
412 + positive or negative acknowledgement message, or until the
413 + request times out after some period of time. If the request
414 + times out, it fails with errno set to ETIME.
339 415
416 + To send requests downstream, arg must point to a strioctl
417 + structure which contains the following members:
340 418
341 - EINVAL
342 - arg does not contain a valid module name.
419 + int ic_cmd;
420 + int ic_timout;
421 + int ic_len;
422 + char *ic_dp;
343 423
424 + ic_cmd is the internal ioctl() command intended for a
425 + downstream module or driver and ic_timout is the number of
426 + seconds (-1 = infinite, 0 = use default, >0 = as specified)
427 + an I_STR request will wait for acknowledgement before timing
428 + out. ic_len is the number of bytes in the data argument and
429 + ic_dp is a pointer to the data argument. The ic_len field
430 + has two uses: on input, it contains the length of the data
431 + argument passed in, and on return from the command, it
432 + contains the number of bytes being returned to the user (the
433 + buffer pointed to by ic_dp should be large enough to contain
434 + the maximum amount of data that any module or the driver in
435 + the stream can return).
344 436
437 + At most one I_STR can be active on a stream. Further I_STR
438 + calls will block until the active I_STR completes via a
439 + positive or negative acknowlegment, a timeout, or an error
440 + condition at the stream head. By setting the ic_timout
441 + field to 0, the user is requesting STREAMS to provide the
442 + DEFAULT timeout. The default timeout is specific to the
443 + STREAMS implementation and may vary depending on which
444 + release of Solaris you are using. For Solaris 8 (and
445 + earlier versions), the default timeout is fifteen seconds.
446 + The O_NDELAY and O_NONBLOCK (see open(2)) flags have no
447 + effect on this call.
345 448
346 - I_PEEK
347 - Allows a user to retrieve the information in the first
348 - message on the stream head read queue without taking the
349 - message off the queue. I_PEEK is analogous to getmsg(2)
350 - except that it does not remove the message from the
351 - queue. arg points to a strpeek structure, which contains
352 - the following members:
449 + The stream head will convert the information pointed to by
450 + the strioctl structure to an internal ioctl() command
451 + message and send it downstream. On failure, errno is set to
452 + one of the following values:
353 453
354 - struct strbuf ctlbuf;
355 - struct strbuf databuf;
356 - long flags;
454 + ENOSR Unable to allocate buffers for the ioctl() message
455 + due to insufficient STREAMS memory resources.
357 456
358 - The maxlen field in the ctlbuf and databuf strbuf
359 - structures (see getmsg(2)) must be set to the number of
360 - bytes of control information and/or data information,
361 - respectively, to retrieve. flags may be set to RS_HIPRI
362 - or 0. If RS_HIPRI is set, I_PEEK will look for a high
363 - priority message on the stream head read queue.
364 - Otherwise, I_PEEK will look for the first message on the
365 - stream head read queue.
457 + EFAULT Either arg points outside the allocated address
458 + space, or the buffer area specified by ic_dp and
459 + ic_len (separately for data sent and data returned)
460 + is outside the allocated address space.
366 461
367 - I_PEEK returns 1 if a message was retrieved, and returns
368 - 0 if no message was found on the stream head read queue.
369 - It does not wait for a message to arrive. On return,
370 - ctlbuf specifies information in the control buffer,
371 - databuf specifies information in the data buffer, and
372 - flags contains the value RS_HIPRI or 0. On failure,
373 - errno is set to the following value:
462 + EINVAL ic_len is less than 0 or ic_len is larger than the
463 + maximum configured size of the data part of a
464 + message or ic_timout is less than -1.
374 465
375 - EFAULT
376 - arg points, or the buffer area specified in
377 - ctlbuf or databuf is, outside the allocated
378 - address space.
466 + ENXIO Hangup received on fildes.
379 467
468 + ETIME A downstream ioctl() timed out before
469 + acknowledgement was received.
380 470
381 - EBADMSG
382 - Queued message to be read is not valid for
383 - I_PEEK.
471 + An I_STR can also fail while waiting for an acknowledgement
472 + if a message indicating an error or a hangup is received at
473 + the stream head. In addition, an error code can be returned
474 + in the positive or negative acknowledgement message, in the
475 + event the ioctl command sent downstream fails. For these
476 + cases, I_STR will fail with errno set to the value in the
477 + message.
384 478
479 + I_SWROPT Sets the write mode using the value of the argument arg.
480 + Legal bit settings for arg are:
385 481
386 - EINVAL
387 - Illegal value for flags.
482 + SNDZERO Send a zero-length message downstream when a write
483 + of 0 bytes occurs.
388 484
485 + To not send a zero-length message when a write of 0 bytes
486 + occurs, this bit must not be set in arg.
389 487
390 - ENOSR
391 - Unable to allocate buffers to perform the
392 - I_PEEK due to insufficient STREAMS memory
393 - resources.
488 + On failure, errno may be set to the following value:
394 489
490 + EINVAL arg is not the above legal value.
395 491
492 + I_GWROPT Returns the current write mode setting, as described above,
493 + in the int that is pointed to by the argument arg.
396 494
397 - I_SRDOPT
398 - Sets the read mode (see read(2)) using the value of the
399 - argument arg. Legal arg values are:
495 + I_SENDFD Requests the stream associated with fildes to send a
496 + message, containing a file pointer, to the stream head at
497 + the other end of a stream pipe. The file pointer
498 + corresponds to arg, which must be an open file descriptor.
400 499
401 - RNORM
402 - Byte-stream mode, the default.
500 + I_SENDFD converts arg into the corresponding system file
501 + pointer. It allocates a message block and inserts the file
502 + pointer in the block. The user id and group id associated
503 + with the sending process are also inserted. This message is
504 + placed directly on the read queue (see Intro(3)) of the
505 + stream head at the other end of the stream pipe to which it
506 + is connected. On failure, errno is set to one of the
507 + following values:
403 508
509 + EAGAIN The sending stream is unable to allocate a message
510 + block to contain the file pointer.
404 511
405 - RMSGD
406 - Message-discard mode.
512 + EAGAIN The read queue of the receiving stream head is full
513 + and cannot accept the message sent by I_SENDFD.
407 514
515 + EBADF arg is not a valid, open file descriptor.
408 516
409 - RMSGN
410 - Message-nondiscard mode.
517 + EINVAL fildes is not connected to a stream pipe.
411 518
412 - In addition, the stream head's treatment of control
413 - messages may be changed by setting the following flags
414 - in arg:
519 + ENXIO Hangup received on fildes.
415 520
416 - RPROTNORM
417 - Reject read() with EBADMSG if a control
418 - message is at the front of the stream head
419 - read queue.
521 + I_RECVFD Retrieves the file descriptor associated with the message
522 + sent by an I_SENDFD ioctl() over a stream pipe. arg is a
523 + pointer to a data buffer large enough to hold an strrecvfd
524 + data structure containing the following members:
420 525
526 + int fd;
527 + uid_t uid;
528 + gid_t gid;
421 529
422 - RPROTDAT
423 - Deliver the control portion of a message as
424 - data when a user issues read(). This is the
425 - default behavior.
530 + fd is an integer file descriptor. uid and gid are the user
531 + id and group id, respectively, of the sending stream.
426 532
533 + If O_NDELAY and O_NONBLOCK are clear (see open(2)), I_RECVFD
534 + will block until a message is present at the stream head.
535 + If O_NDELAY or O_NONBLOCK is set, I_RECVFD will fail with
536 + errno set to EAGAIN if no message is present at the stream
537 + head.
427 538
428 - RPROTDIS
429 - Discard the control portion of a message,
430 - delivering any data portion, when a user
431 - issues a read().
539 + If the message at the stream head is a message sent by an
540 + I_SENDFD, a new user file descriptor is allocated for the
541 + file pointer contained in the message. The new file
542 + descriptor is placed in the fd field of the strrecvfd
543 + structure. The structure is copied into the user data
544 + buffer pointed to by arg. On failure, errno is set to one
545 + of the following values:
432 546
433 - On failure, errno is set to the following value:
547 + EAGAIN A message is not present at the stream head read
548 + queue, and the O_NDELAY or O_NONBLOCK flag is
549 + set.
434 550
435 - EINVAL
436 - arg is not one of the above legal values, or
437 - arg is the bitwise inclusive OR of RMSGD and
438 - RMSGN.
551 + EBADMSG The message at the stream head read queue is not
552 + a message containing a passed file descriptor.
439 553
554 + EFAULT arg points outside the allocated address space.
440 555
556 + EMFILE NOFILES file descriptors are currently open.
441 557
442 - I_GRDOPT
443 - Returns the current read mode setting in an int pointed
444 - to by the argument arg. Read modes are described in
445 - read(). On failure, errno is set to the following value:
558 + ENXIO Hangup received on fildes.
446 559
447 - EFAULT
448 - arg points outside the allocated address
449 - space.
560 + EOVERFLOW uid or gid is too large to be stored in the
561 + structure pointed to by arg.
450 562
563 + I_LIST Allows the user to list all the module names on the stream,
564 + up to and including the topmost driver name. If arg is
565 + NULL, the return value is the number of modules, including
566 + the driver, that are on the stream pointed to by fildes.
567 + This allows the user to allocate enough space for the module
568 + names. If arg is non-null, it should point to an str_list
569 + structure that has the following members:
451 570
571 + int sl_nmods;
572 + struct str_mlist *sl_modlist;
452 573
453 - I_NREAD
454 - Counts the number of data bytes in data blocks in the
455 - first message on the stream head read queue, and places
456 - this value in the location pointed to by arg. The return
457 - value for the command is the number of messages on the
458 - stream head read queue. For example, if zero is returned
459 - in arg, but the ioctl return value is greater than zero,
460 - this indicates that a zero-length message is next on the
461 - queue. On failure, errno is set to the following value:
574 + The str_mlist structure has the following member:
462 575
463 - EFAULT
464 - arg points outside the allocated address
465 - space.
576 + char l_name[FMNAMESZ+1];
466 577
578 + The sl_nmods member indicates the number of entries the
579 + process has allocated in the array. Upon return, the
580 + sl_modlist member of the str_list structure contains the
581 + list of module names, and the number of entries that have
582 + been filled into the sl_modlist array is found in the
583 + sl_nmods member (the number includes the number of modules
584 + including the driver). The return value from ioctl() is 0.
585 + The entries are filled in starting at the top of the stream
586 + and continuing downstream until either the end of the stream
587 + is reached, or the number of requested modules (sl_nmods) is
588 + satisfied. On failure, errno may be set to one of the
589 + following values:
467 590
591 + EINVAL The sl_nmods member is less than 1.
468 592
469 - I_FDINSERT
470 - Creates a message from specified buffer(s), adds
471 - information about another stream and sends the message
472 - downstream. The message contains a control part and an
473 - optional data part. The data and control parts to be
474 - sent are distinguished by placement in separate buffers,
475 - as described below.
593 + EAGAIN Unable to allocate buffers
476 594
477 - The arg argument points to a strfdinsert structure,
478 - which contains the following members:
595 + I_ATMARK Allows the user to see if the current message on the stream
596 + head read queue is "marked" by some module downstream. arg
597 + determines how the checking is done when there may be
598 + multiple marked messages on the stream head read queue. It
599 + may take the following values:
479 600
480 - struct strbuf ctlbuf;
481 - struct strbuf databuf;
482 - t_uscalar_t flags;
483 - int fildes;
484 - int offset;
601 + ANYMARK Check if the message is marked.
485 602
486 - The len member in the ctlbuf strbuf structure (see
487 - putmsg(2)) must be set to the size of a t_uscalar_t
488 - plus the number of bytes of control information to be
489 - sent with the message. The fildes member specifies the
490 - file descriptor of the other stream, and the offset
491 - member, which must be suitably aligned for use as a
492 - t_uscalar_t, specifies the offset from the start of the
493 - control buffer where I_FDINSERT will store a t_uscalar_t
494 - whose interpretation is specific to the stream end. The
495 - len member in the databuf strbuf structure must be set
496 - to the number of bytes of data information to be sent
497 - with the message, or to 0 if no data part is to be sent.
603 + LASTMARK Check if the message is the last one marked on the
604 + queue.
498 605
499 - The flags member specifies the type of message to be
500 - created. A normal message is created if flags is set to
501 - 0, and a high-priority message is created if flags is
502 - set to RS_HIPRI. For non-priority messages, I_FDINSERT
503 - will block if the stream write queue is full due to
504 - internal flow control conditions. For priority messages,
505 - I_FDINSERT does not block on this condition. For non-
506 - priority messages, I_FDINSERT does not block when the
507 - write queue is full and O_NDELAY or O_NONBLOCK is set.
508 - Instead, it fails and sets errno to EAGAIN.
606 + The return value is 1 if the mark condition is satisfied and
607 + 0 otherwise. On failure, errno is set to the following
608 + value:
509 609
510 - I_FDINSERT also blocks, unless prevented by lack of
511 - internal resources, waiting for the availability of
512 - message blocks in the stream, regardless of priority or
513 - whether O_NDELAY or O_NONBLOCK has been specified. No
514 - partial message is sent.
610 + EINVAL Invalid arg value.
515 611
516 - The ioctl() function with the I_FDINSERT command will
517 - fail if:
612 + I_CKBAND Check if the message of a given priority band exists on the
613 + stream head read queue. This returns 1 if a message of a
614 + given priority exists, 0 if not, or -1 on error. arg should
615 + be an integer containing the value of the priority band in
616 + question. On failure, errno is set to the following value:
518 617
519 - EAGAIN
520 - A non-priority message is specified, the
521 - O_NDELAY or O_NONBLOCK flag is set, and the
522 - stream write queue is full due to internal
523 - flow control conditions.
618 + EINVAL Invalid arg value.
524 619
620 + I_GETBAND Returns the priority band of the first message on the stream
621 + head read queue in the integer referenced by arg. On
622 + failure, errno is set to the following value:
525 623
526 - ENOSR
527 - Buffers can not be allocated for the message
528 - that is to be created.
624 + ENODATA No message on the stream head read queue.
529 625
626 + I_CANPUT Check if a certain band is writable. arg is set to the
627 + priority band in question. The return value is 0 if the
628 + priority band arg is flow controlled, 1 if the band is
629 + writable, or -1 on error. On failure, errno is set to the
630 + following value:
530 631
531 - EFAULT
532 - The arg argument points, or the buffer area
533 - specified in ctlbuf or databuf is, outside the
534 - allocated address space.
632 + EINVAL Invalid arg value.
535 633
634 + I_SETCLTIME Allows the user to set the time the stream head will delay
635 + when a stream is closing and there are data on the write
636 + queues. Before closing each module and driver, the stream
637 + head will delay for the specified amount of time to allow
638 + the data to drain. Note, however, that the module or driver
639 + may itself delay in its close routine; this delay is
640 + independent of the stream head's delay and is not settable.
641 + If, after the delay, data are still present, data will be
642 + flushed. arg is a pointer to an integer containing the
643 + number of milliseconds to delay, rounded up to the nearest
644 + legal value on the system. The default is fifteen seconds.
645 + On failure, errno is set to the following value:
536 646
537 - EINVAL
538 - One of the following: The fildes member of the
539 - strfdinsert structure is not a valid, open
540 - stream file descriptor; the size of a
541 - t_uscalar_t plus offset is greater than the
542 - len member for the buffer specified through
543 - ctlptr; the offset member does not specify a
544 - properly-aligned location in the data buffer;
545 - or an undefined value is stored in flags.
647 + EINVAL Invalid arg value.
546 648
649 + I_GETCLTIME Returns the close time delay in the integer pointed by arg.
547 650
548 - ENXIO
549 - Hangup received on the fildes argument of the
550 - ioctl call or the fildes member of the
551 - strfdinsert structure.
651 + I_SERROPT Sets the error mode using the value of the argument arg.
552 652
653 + Normally stream head errors are persistent; once they are
654 + set due to an M_ERROR or M_HANGUP, the error condition will
655 + remain until the stream is closed. This option can be used
656 + to set the stream head into non-persistent error mode i.e.
657 + once the error has been returned in response to a read(2),
658 + getmsg(2), ioctl(2), write(2), or putmsg(2) call the error
659 + condition will be cleared. The error mode can be controlled
660 + independently for read and write side errors. Legal arg
661 + values are either none or one of:
553 662
554 - ERANGE
555 - The len field for the buffer specified through
556 - databuf does not fall within the range
557 - specified by the maximum and minimum packet
558 - sizes of the topmost stream module; or the len
559 - member for the buffer specified through
560 - databuf is larger than the maximum configured
561 - size of the data part of a message; or the len
562 - member for the buffer specified through ctlbuf
563 - is larger than the maximum configured size of
564 - the control part of a message.
663 + RERRNORM Persistent read errors, the default.
565 664
566 - I_FDINSERT can also fail if an error message was
567 - received by the stream head of the stream corresponding
568 - to the fildes member of the strfdinsert structure. In
569 - this case, errno will be set to the value in the
570 - message.
665 + RERRNONPERSIST Non-persistent read errors.
571 666
667 + OR'ed with either none or one of:
572 668
573 - I_STR
574 - Constructs an internal STREAMS ioctl message from the
575 - data pointed to by arg, and sends that message
576 - downstream.
669 + WERRNORM Persistent write errors, the default.
577 670
578 - This mechanism is provided to send user ioctl requests
579 - to downstream modules and drivers. It allows information
580 - to be sent with the ioctl, and will return to the user
581 - any information sent upstream by the downstream
582 - recipient. I_STR blocks until the system responds with
583 - either a positive or negative acknowledgement message,
584 - or until the request times out after some period of
585 - time. If the request times out, it fails with errno set
586 - to ETIME.
671 + WERRNONPERSIST Non-persistent write errors.
587 672
588 - To send requests downstream, arg must point to a
589 - strioctl structure which contains the following members:
673 + When no value is specified e.g. for the read side error
674 + behavior then the behavior for that side will be left
675 + unchanged.
590 676
591 - int ic_cmd;
592 - int ic_timout;
593 - int ic_len;
594 - char *ic_dp;
677 + On failure, errno is set to the following value:
595 678
596 - ic_cmd is the internal ioctl command intended for a
597 - downstream module or driver and ic_timout is the number
598 - of seconds (-1 = infinite, 0 = use default, >0 = as
599 - specified) an I_STR request will wait for
600 - acknowledgement before timing out. ic_len is the number
601 - of bytes in the data argument and ic_dp is a pointer to
602 - the data argument. The ic_len field has two uses: on
603 - input, it contains the length of the data argument
604 - passed in, and on return from the command, it contains
605 - the number of bytes being returned to the user (the
606 - buffer pointed to by ic_dp should be large enough to
607 - contain the maximum amount of data that any module or
608 - the driver in the stream can return).
679 + EINVAL arg is not one of the above legal values.
609 680
610 - At most one I_STR can be active on a stream. Further
611 - I_STR calls will block until the active I_STR completes
612 - via a positive or negative acknowlegment, a timeout,
613 - or an error condition at the stream head. By setting
614 - the ic_timout field to 0, the user is requesting
615 - STREAMS to provide the DEFAULT timeout. The default
616 - timeout is specific to the STREAMS implementation and
617 - may vary depending on which release of Solaris you are
618 - using. For Solaris 8 (and earlier versions), the default
619 - timeout is fifteen seconds. The O_NDELAY and O_NONBLOCK
620 - (see open(2)) flags have no effect on this call.
681 + I_GERROPT Returns the current error mode setting in an int pointed to
682 + by the argument arg. Error modes are described above for
683 + I_SERROPT. On failure, errno is set to the following value:
621 684
622 - The stream head will convert the information pointed to
623 - by the strioctl structure to an internal ioctl command
624 - message and send it downstream. On failure, errno is set
625 - to one of the following values:
685 + EFAULT arg points outside the allocated address space.
626 686
627 - ENOSR
628 - Unable to allocate buffers for the ioctl
629 - message due to insufficient STREAMS memory
630 - resources.
687 + The following four commands are used for connecting and disconnecting
688 + multiplexed STREAMS configurations.
631 689
690 + I_LINK Connects two streams, where fildes is the file descriptor of
691 + the stream connected to the multiplexing driver, and arg is
692 + the file descriptor of the stream connected to another driver.
693 + The stream designated by arg gets connected below the
694 + multiplexing driver. I_LINK requires the multiplexing driver
695 + to send an acknowledgement message to the stream head
696 + regarding the linking operation. This call returns a
697 + multiplexor ID number (an identifier used to disconnect the
698 + multiplexor, see I_UNLINK) on success, and -1 on failure. On
699 + failure, errno is set to one of the following values:
632 700
633 - EFAULT
634 - Either arg points outside the allocated
635 - address space, or the buffer area specified by
636 - ic_dp and ic_len (separately for data sent and
637 - data returned) is outside the allocated
638 - address space.
701 + ENXIO Hangup received on fildes.
639 702
703 + ETIME Time out before acknowledgement message was received
704 + at stream head.
640 705
641 - EINVAL
642 - ic_len is less than 0 or ic_len is larger than
643 - the maximum configured size of the data part
644 - of a message or ic_timout is less than -1.
706 + EAGAIN Temporarily unable to allocate storage to perform the
707 + I_LINK.
645 708
709 + ENOSR Unable to allocate storage to perform the I_LINK due
710 + to insufficient STREAMS memory resources.
646 711
647 - ENXIO
648 - Hangup received on fildes.
712 + EBADF arg is not a valid, open file descriptor.
649 713
714 + EINVAL fildes stream does not support multiplexing.
650 715
651 - ETIME
652 - A downstream ioctl timed out before
653 - acknowledgement was received.
716 + EINVAL is not a stream, or is already linked under a
717 + multiplexor.
654 718
655 - An I_STR can also fail while waiting for an
656 - acknowledgement if a message indicating an error or a
657 - hangup is received at the stream head. In addition, an
658 - error code can be returned in the positive or negative
659 - acknowledgement message, in the event the ioctl command
660 - sent downstream fails. For these cases, I_STR will fail
661 - with errno set to the value in the message.
719 + EINVAL The specified link operation would cause a "cycle" in
720 + the resulting configuration; that is, a driver would
721 + be linked into the multiplexing configuration in more
722 + than one place.
662 723
724 + EINVAL fildes is the file descriptor of a pipe or FIFO.
663 725
664 - I_SWROPT
665 - Sets the write mode using the value of the argument arg.
666 - Legal bit settings for arg are:
726 + EINVAL Either the upper or lower stream has a major number >=
727 + the maximum major number on the system.
667 728
668 - SNDZERO
669 - Send a zero-length message downstream when a
670 - write of 0 bytes occurs.
729 + An I_LINK can also fail while waiting for the multiplexing
730 + driver to acknowledge the link request, if a message
731 + indicating an error or a hangup is received at the stream head
732 + of fildes. In addition, an error code can be returned in the
733 + positive or negative acknowledgement message. For these
734 + cases, I_LINK will fail with errno set to the value in the
735 + message.
671 736
672 - To not send a zero-length message when a write of 0
673 - bytes occurs, this bit must not be set in arg.
737 + I_UNLINK Disconnects the two streams specified by fildes and arg.
738 + fildes is the file descriptor of the stream connected to the
739 + multiplexing driver. arg is the multiplexor ID number that
740 + was returned by the I_LINK. If arg is -1, then all streams
741 + that were linked to fildes are disconnected. As in I_LINK,
742 + this command requires the multiplexing driver to acknowledge
743 + the unlink. On failure, errno is set to one of the following
744 + values:
674 745
675 - On failure, errno may be set to the following value:
746 + ENXIO Hangup received on fildes.
676 747
677 - EINVAL
678 - arg is not the above legal value.
748 + ETIME Time out before acknowledgement message was received
749 + at stream head.
679 750
751 + ENOSR Unable to allocate storage to perform the I_UNLINK due
752 + to insufficient STREAMS memory resources.
680 753
754 + EINVAL arg is an invalid multiplexor ID number or fildes is
755 + not the stream on which the I_LINK that returned arg
756 + was performed.
681 757
682 - I_GWROPT
683 - Returns the current write mode setting, as described
684 - above, in the int that is pointed to by the argument
685 - arg.
758 + EINVAL fildes is the file descriptor of a pipe or FIFO.
686 759
760 + An I_UNLINK can also fail while waiting for the multiplexing
761 + driver to acknowledge the link request, if a message
762 + indicating an error or a hangup is received at the stream head
763 + of fildes. In addition, an error code can be returned in the
764 + positive or negative acknowledgement message. For these
765 + cases, I_UNLINK will fail with errno set to the value in the
766 + message.
687 767
688 - I_SENDFD
689 - Requests the stream associated with fildes to send a
690 - message, containing a file pointer, to the stream head
691 - at the other end of a stream pipe. The file pointer
692 - corresponds to arg, which must be an open file
693 - descriptor.
768 + I_PLINK Connects two streams, where fildes is the file descriptor of
769 + the stream connected to the multiplexing driver, and arg is
770 + the file descriptor of the stream connected to another driver.
771 + The stream designated by arg gets connected via a persistent
772 + link below the multiplexing driver. I_PLINK requires the
773 + multiplexing driver to send an acknowledgement message to the
774 + stream head regarding the linking operation. This call
775 + creates a persistent link that continues to exist even if the
776 + file descriptor fildes associated with the upper stream to the
777 + multiplexing driver is closed. This call returns a
778 + multiplexor ID number (an identifier that may be used to
779 + disconnect the multiplexor, see I_PUNLINK) on success, and -1
780 + on failure. On failure, errno is set to one of the following
781 + values:
694 782
695 - I_SENDFD converts arg into the corresponding system file
696 - pointer. It allocates a message block and inserts the
697 - file pointer in the block. The user id and group id
698 - associated with the sending process are also inserted.
699 - This message is placed directly on the read queue (see
700 - Intro(3)) of the stream head at the other end of the
701 - stream pipe to which it is connected. On failure, errno
702 - is set to one of the following values:
783 + ENXIO Hangup received on fildes.
703 784
704 - EAGAIN
705 - The sending stream is unable to allocate a
706 - message block to contain the file pointer.
785 + ETIME Time out before acknowledgement message was received
786 + at the stream head.
707 787
788 + EAGAIN Unable to allocate STREAMS storage to perform the
789 + I_PLINK.
708 790
709 - EAGAIN
710 - The read queue of the receiving stream head is
711 - full and cannot accept the message sent by
712 - I_SENDFD.
791 + EBADF arg is not a valid, open file descriptor.
713 792
793 + EINVAL fildes does not support multiplexing.
714 794
715 - EBADF
716 - arg is not a valid, open file descriptor.
795 + EINVAL arg is not a stream or is already linked under a
796 + multiplexor.
717 797
798 + EINVAL The specified link operation would cause a "cycle" in
799 + the resulting configuration; that is, if a driver
800 + would be linked into the multiplexing configuration in
801 + more than one place.
718 802
719 - EINVAL
720 - fildes is not connected to a stream pipe.
803 + EINVAL fildes is the file descriptor of a pipe or FIFO.
721 804
805 + An I_PLINK can also fail while waiting for the multiplexing
806 + driver to acknowledge the link request, if a message
807 + indicating an error on a hangup is received at the stream head
808 + of fildes. In addition, an error code can be returned in the
809 + positive or negative acknowledgement message. For these
810 + cases, I_PLINK will fail with errno set to the value in the
811 + message.
722 812
723 - ENXIO
724 - Hangup received on fildes.
813 + I_PUNLINK Disconnects the two streams specified by fildes and arg that
814 + are connected with a persistent link. fildes is the file
815 + descriptor of the stream connected to the multiplexing driver.
816 + arg is the multiplexor ID number that was returned by I_PLINK
817 + when a stream was linked below the multiplexing driver. If
818 + arg is MUXID_ALL then all streams that are persistent links to
819 + fildes are disconnected. As in I_PLINK, this command requires
820 + the multiplexing driver to acknowledge the unlink. On
821 + failure, errno is set to one of the following values:
725 822
823 + ENXIO Hangup received on fildes.
726 824
825 + ETIME Time out before acknowledgement message was received
826 + at the stream head.
727 827
728 - I_RECVFD
729 - Retrieves the file descriptor associated with the
730 - message sent by an I_SENDFD ioctl over a stream pipe.
731 - arg is a pointer to a data buffer large enough to hold
732 - an strrecvfd data structure containing the following
733 - members:
828 + EAGAIN Unable to allocate buffers for the acknowledgement
829 + message.
734 830
735 - int fd;
736 - uid_t uid;
737 - gid_t gid;
831 + EINVAL Invalid multiplexor ID number.
738 832
739 - fd is an integer file descriptor. uid and gid are the
740 - user id and group id, respectively, of the sending
741 - stream.
833 + EINVAL fildes is the file descriptor of a pipe or FIFO.
742 834
743 - If O_NDELAY and O_NONBLOCK are clear (see open(2)),
744 - I_RECVFD will block until a message is present at the
745 - stream head. If O_NDELAY or O_NONBLOCK is set, I_RECVFD
746 - will fail with errno set to EAGAIN if no message is
747 - present at the stream head.
835 + An I_PUNLINK can also fail while waiting for the multiplexing
836 + driver to acknowledge the link request if a message indicating
837 + an error or a hangup is received at the stream head of fildes.
838 + In addition, an error code can be returned in the positive or
839 + negative acknowledgement message. For these cases, I_PUNLINK
840 + will fail with errno set to the value in the message.
748 841
749 - If the message at the stream head is a message sent by
750 - an I_SENDFD, a new user file descriptor is allocated for
751 - the file pointer contained in the message. The new file
752 - descriptor is placed in the fd field of the strrecvfd
753 - structure. The structure is copied into the user data
754 - buffer pointed to by arg. On failure, errno is set to
755 - one of the following values:
756 -
757 - EAGAIN
758 - A message is not present at the stream head
759 - read queue, and the O_NDELAY or O_NONBLOCK
760 - flag is set.
761 -
762 -
763 - EBADMSG
764 - The message at the stream head read queue
765 - is not a message containing a passed file
766 - descriptor.
767 -
768 -
769 - EFAULT
770 - arg points outside the allocated address
771 - space.
772 -
773 -
774 - EMFILE
775 - NOFILES file descriptors are currently
776 - open.
777 -
778 -
779 - ENXIO
780 - Hangup received on fildes.
781 -
782 -
783 - EOVERFLOW
784 - uid or gid is too large to be stored in the
785 - structure pointed to by arg.
786 -
787 -
788 -
789 - I_LIST
790 - Allows the user to list all the module names on the
791 - stream, up to and including the topmost driver name. If
792 - arg is NULL, the return value is the number of modules,
793 - including the driver, that are on the stream pointed to
794 - by fildes. This allows the user to allocate enough space
795 - for the module names. If arg is non-null, it should
796 - point to an str_list structure that has the following
797 - members:
798 -
799 - int sl_nmods;
800 - struct str_mlist *sl_modlist;
801 -
802 - The str_mlist structure has the following member:
803 -
804 - char l_name[FMNAMESZ+1];
805 -
806 - The sl_nmods member indicates the number of entries the
807 - process has allocated in the array. Upon return, the
808 - sl_modlist member of the str_list structure contains the
809 - list of module names, and the number of entries that
810 - have been filled into the sl_modlist array is found in
811 - the sl_nmods member (the number includes the number of
812 - modules including the driver). The return value from
813 - ioctl() is 0. The entries are filled in starting at the
814 - top of the stream and continuing downstream until either
815 - the end of the stream is reached, or the number of
816 - requested modules (sl_nmods) is satisfied. On failure,
817 - errno may be set to one of the following values:
818 -
819 - EINVAL
820 - The sl_nmods member is less than 1.
821 -
822 -
823 - EAGAIN
824 - Unable to allocate buffers
825 -
826 -
827 -
828 - I_ATMARK
829 - Allows the user to see if the current message on the
830 - stream head read queue is ``marked'' by some module
831 - downstream. arg determines how the checking is done when
832 - there may be multiple marked messages on the stream head
833 - read queue. It may take the following values:
834 -
835 - ANYMARK
836 - Check if the message is marked.
837 -
838 -
839 - LASTMARK
840 - Check if the message is the last one marked
841 - on the queue.
842 -
843 - The return value is 1 if the mark condition is satisfied
844 - and 0 otherwise. On failure, errno is set to the
845 - following value:
846 -
847 - EINVAL
848 - Invalid arg value.
849 -
850 -
851 -
852 - I_CKBAND
853 - Check if the message of a given priority band exists on
854 - the stream head read queue. This returns 1 if a message
855 - of a given priority exists, 0 if not, or -1 on error.
856 - arg should be an integer containing the value of the
857 - priority band in question. On failure, errno is set to
858 - the following value:
859 -
860 - EINVAL
861 - Invalid arg value.
862 -
863 -
864 -
865 - I_GETBAND
866 - Returns the priority band of the first message on the
867 - stream head read queue in the integer referenced by arg.
868 - On failure, errno is set to the following value:
869 -
870 - ENODATA
871 - No message on the stream head read queue.
872 -
873 -
874 -
875 - I_CANPUT
876 - Check if a certain band is writable. arg is set to the
877 - priority band in question. The return value is 0 if the
878 - priority band arg is flow controlled, 1 if the band is
879 - writable, or -1 on error. On failure, errno is set to
880 - the following value:
881 -
882 - EINVAL
883 - Invalid arg value.
884 -
885 -
886 -
887 - I_SETCLTIME
888 - Allows the user to set the time the stream head will
889 - delay when a stream is closing and there are data on the
890 - write queues. Before closing each module and driver,
891 - the stream head will delay for the specified amount of
892 - time to allow the data to drain. Note, however, that the
893 - module or driver may itself delay in its close routine;
894 - this delay is independent of the stream head's delay and
895 - is not settable. If, after the delay, data are still
896 - present, data will be flushed. arg is a pointer to an
897 - integer containing the number of milliseconds to delay,
898 - rounded up to the nearest legal value on the system.
899 - The default is fifteen seconds. On failure, errno is set
900 - to the following value:
901 -
902 - EINVAL
903 - Invalid arg value.
904 -
905 -
906 -
907 - I_GETCLTIME
908 - Returns the close time delay in the integer pointed by
909 - arg.
910 -
911 -
912 - I_SERROPT
913 - Sets the error mode using the value of the argument arg.
914 -
915 - Normally stream head errors are persistent; once they
916 - are set due to an M_ERROR or M_HANGUP, the error
917 - condition will remain until the stream is closed. This
918 - option can be used to set the stream head into non-
919 - persistent error mode i.e. once the error has been
920 - returned in response to a read(2), getmsg(2), ioctl(2),
921 - write(2), or putmsg(2) call the error condition will be
922 - cleared. The error mode can be controlled independently
923 - for read and write side errors. Legal arg values are
924 - either none or one of:
925 -
926 - RERRNORM
927 - Persistent read errors, the default.
928 -
929 -
930 - RERRNONPERSIST
931 - Non-persistent read errors.
932 -
933 - OR'ed with either none or one of:
934 -
935 - WERRNORM
936 - Persistent write errors, the default.
937 -
938 -
939 - WERRNONPERSIST
940 - Non-persistent write errors.
941 -
942 - When no value is specified e.g. for
943 - the read side error behavior then the
944 - behavior for that side will be left
945 - unchanged.
946 -
947 - On failure, errno is set to the following value:
948 -
949 - EINVAL
950 - arg is not one of the above legal values.
951 -
952 -
953 -
954 - I_GERROPT
955 - Returns the current error mode setting in an int pointed
956 - to by the argument arg. Error modes are described above
957 - for I_SERROPT. On failure,errno is set to the following
958 - value:
959 -
960 - EFAULT
961 - arg points outside the allocated address
962 - space.
963 -
964 -
965 -
966 -
967 - The following four commands are used for connecting and disconnecting
968 - multiplexed STREAMS configurations.
969 -
970 - I_LINK
971 - Connects two streams, where fildes is the file descriptor
972 - of the stream connected to the multiplexing driver, and
973 - arg is the file descriptor of the stream connected to
974 - another driver. The stream designated by arg gets
975 - connected below the multiplexing driver. I_LINK requires
976 - the multiplexing driver to send an acknowledgement message
977 - to the stream head regarding the linking operation. This
978 - call returns a multiplexor ID number (an identifier used
979 - to disconnect the multiplexor, see I_UNLINK) on success,
980 - and -1 on failure. On failure, errno is set to one of the
981 - following values:
982 -
983 - ENXIO
984 - Hangup received on fildes.
985 -
986 -
987 - ETIME
988 - Time out before acknowledgement message was
989 - received at stream head.
990 -
991 -
992 - EAGAIN
993 - Temporarily unable to allocate storage to
994 - perform the I_LINK.
995 -
996 -
997 - ENOSR
998 - Unable to allocate storage to perform the I_LINK
999 - due to insufficient STREAMS memory resources.
1000 -
1001 -
1002 - EBADF
1003 - arg is not a valid, open file descriptor.
1004 -
1005 -
1006 - EINVAL
1007 - fildes stream does not support multiplexing.
1008 -
1009 -
1010 - EINVAL
1011 - arg is not a stream, or is already linked under
1012 - a multiplexor.
1013 -
1014 -
1015 - EINVAL
1016 - The specified link operation would cause a
1017 - ``cycle'' in the resulting configuration; that
1018 - is, a driver would be linked into the
1019 - multiplexing configuration in more than one
1020 - place.
1021 -
1022 -
1023 - EINVAL
1024 - fildes is the file descriptor of a pipe or FIFO.
1025 -
1026 -
1027 - EINVAL
1028 - Either the upper or lower stream has a major
1029 - number >= the maximum major number on the
1030 - system.
1031 -
1032 - An I_LINK can also fail while waiting for the multiplexing
1033 - driver to acknowledge the link request, if a message
1034 - indicating an error or a hangup is received at the stream
1035 - head of fildes. In addition, an error code can be returned
1036 - in the positive or negative acknowledgement message. For
1037 - these cases, I_LINK will fail with errno set to the value
1038 - in the message.
1039 -
1040 -
1041 - I_UNLINK
1042 - Disconnects the two streams specified by fildes and arg.
1043 - fildes is the file descriptor of the stream connected to
1044 - the multiplexing driver. arg is the multiplexor ID number
1045 - that was returned by the I_LINK. If arg is -1, then all
1046 - streams that were linked to fildes are disconnected. As
1047 - in I_LINK, this command requires the multiplexing driver
1048 - to acknowledge the unlink. On failure, errno is set to one
1049 - of the following values:
1050 -
1051 - ENXIO
1052 - Hangup received on fildes.
1053 -
1054 -
1055 - ETIME
1056 - Time out before acknowledgement message was
1057 - received at stream head.
1058 -
1059 -
1060 - ENOSR
1061 - Unable to allocate storage to perform the
1062 - I_UNLINK due to insufficient STREAMS memory
1063 - resources.
1064 -
1065 -
1066 - EINVAL
1067 - arg is an invalid multiplexor ID number or
1068 - fildes is not the stream on which the I_LINK
1069 - that returned arg was performed.
1070 -
1071 -
1072 - EINVAL
1073 - fildes is the file descriptor of a pipe or FIFO.
1074 -
1075 - An I_UNLINK can also fail while waiting for the
1076 - multiplexing driver to acknowledge the link request, if a
1077 - message indicating an error or a hangup is received at the
1078 - stream head of fildes. In addition, an error code can be
1079 - returned in the positive or negative acknowledgement
1080 - message. For these cases, I_UNLINK will fail with errno
1081 - set to the value in the message.
1082 -
1083 -
1084 - I_PLINK
1085 - Connects two streams, where fildes is the file descriptor
1086 - of the stream connected to the multiplexing driver, and
1087 - arg is the file descriptor of the stream connected to
1088 - another driver. The stream designated by arg gets
1089 - connected via a persistent link below the multiplexing
1090 - driver. I_PLINK requires the multiplexing driver to send
1091 - an acknowledgement message to the stream head regarding
1092 - the linking operation. This call creates a persistent link
1093 - that continues to exist even if the file descriptor fildes
1094 - associated with the upper stream to the multiplexing
1095 - driver is closed. This call returns a multiplexor ID
1096 - number (an identifier that may be used to disconnect the
1097 - multiplexor, see I_PUNLINK) on success, and -1 on failure.
1098 - On failure, errno is set to one of the following values:
1099 -
1100 - ENXIO
1101 - Hangup received on fildes.
1102 -
1103 -
1104 - ETIME
1105 - Time out before acknowledgement message was
1106 - received at the stream head.
1107 -
1108 -
1109 - EAGAIN
1110 - Unable to allocate STREAMS storage to perform
1111 - the I_PLINK.
1112 -
1113 -
1114 - EBADF
1115 - arg is not a valid, open file descriptor.
1116 -
1117 -
1118 - EINVAL
1119 - fildes does not support multiplexing.
1120 -
1121 -
1122 - EINVAL
1123 - arg is not a stream or is already linked under a
1124 - multiplexor.
1125 -
1126 -
1127 - EINVAL
1128 - The specified link operation would cause a
1129 - ``cycle'' in the resulting configuration; that
1130 - is, if a driver would be linked into the
1131 - multiplexing configuration in more than one
1132 - place.
1133 -
1134 -
1135 - EINVAL
1136 - fildes is the file descriptor of a pipe or FIFO.
1137 -
1138 - An I_PLINK can also fail while waiting for the
1139 - multiplexing driver to acknowledge the link request, if a
1140 - message indicating an error on a hangup is received at the
1141 - stream head of fildes. In addition, an error code can be
1142 - returned in the positive or negative acknowledgement
1143 - message. For these cases, I_PLINK will fail with errno
1144 - set to the value in the message.
1145 -
1146 -
1147 - I_PUNLINK
1148 - Disconnects the two streams specified by fildes and arg
1149 - that are connected with a persistent link. fildes is the
1150 - file descriptor of the stream connected to the
1151 - multiplexing driver. arg is the multiplexor ID number that
1152 - was returned by I_PLINK when a stream was linked below the
1153 - multiplexing driver. If arg is MUXID_ALL then all streams
1154 - that are persistent links to fildes are disconnected. As
1155 - in I_PLINK, this command requires the multiplexing driver
1156 - to acknowledge the unlink. On failure, errno is set to one
1157 - of the following values:
1158 -
1159 - ENXIO
1160 - Hangup received on fildes.
1161 -
1162 -
1163 - ETIME
1164 - Time out before acknowledgement message was
1165 - received at the stream head.
1166 -
1167 -
1168 - EAGAIN
1169 - Unable to allocate buffers for the
1170 - acknowledgement message.
1171 -
1172 -
1173 - EINVAL
1174 - Invalid multiplexor ID number.
1175 -
1176 -
1177 - EINVAL
1178 - fildes is the file descriptor of a pipe or FIFO.
1179 -
1180 - An I_PUNLINK can also fail while waiting for the
1181 - multiplexing driver to acknowledge the link request if a
1182 - message indicating an error or a hangup is received at the
1183 - stream head of fildes. In addition, an error code can be
1184 - returned in the positive or negative acknowledgement
1185 - message. For these cases, I_PUNLINK will fail with errno
1186 - set to the value in the message.
1187 -
1188 -
1189 842 RETURN VALUES
1190 - Unless specified otherwise above, the return value from ioctl() is 0
1191 - upon success and -1 upon failure, with errno set as indicated.
843 + Unless specified otherwise above, the return value from ioctl(2) is 0
844 + upon success and -1 upon failure, with errno set as indicated.
1192 845
1193 846 SEE ALSO
1194 - Intro(3), close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2),
1195 - putmsg(2), read(2), write(2), signal(3C), signal.h(3HEAD),
847 + close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2),
848 + read(2), write(2), Intro(3), signal(3C), signal.h(3HEAD)
1196 849
850 + STREAMS Programming Guide
1197 851
1198 - STREAMS Programming Guide
1199 -
1200 -
1201 -
1202 - April 8, 2009 STREAMIO(7I)
852 +illumos October 29, 2017 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX