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