1IOCTL(3P) POSIX Programmer's Manual IOCTL(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 ioctl - control a STREAMS device (STREAMS)
13
15 #include <stropts.h>
16 int ioctl(int fildes, int request, ... /* arg */);
18
21 The ioctl() function shall perform a variety of control functions on
22 STREAMS devices. For non-STREAMS devices, the functions performed by
23 this call are unspecified. The request argument and an optional third
24 argument (with varying type) shall be passed to and interpreted by the
25 appropriate part of the STREAM associated with fildes.
26 The fildes argument is an open file descriptor that refers to a device.
28 The request argument selects the control function to be performed and
30 shall depend on the STREAMS device being addressed.
31 The arg argument represents additional information that is needed by
33 this specific STREAMS device to perform the requested function. The
34 type of arg depends upon the particular control request, but it shall
35 be either an integer or a pointer to a device-specific data structure.
36 The ioctl() commands applicable to STREAMS, their arguments, and error
38 conditions that apply to each individual command are described below.
39 The following ioctl() commands, with error values indicated, are appli‐
41 cable to all STREAMS files:
42 I_PUSH Pushes the module whose name is pointed to by arg onto the top
44 of the current STREAM, just below the STREAM head. It then calls
45 the open() function of the newly-pushed module.
46 The ioctl() function with the I_PUSH command shall fail if:
48 EINVAL
50 Invalid module name.
51 ENXIO
53 Open function of new module failed.
54 ENXIO
56 Hangup received on fildes.
57 I_POP Removes the module just below the STREAM head of the STREAM
60 pointed to by fildes. The arg argument should be 0 in an I_POP
61 request.
62 The ioctl() function with the I_POP command shall fail if:
64 EINVAL
66 No module present in the STREAM.
67 ENXIO
69 Hangup received on fildes.
70 I_LOOK Retrieves the name of the module just below the STREAM head of
73 the STREAM pointed to by fildes, and places it in a character
74 string pointed to by arg. The buffer pointed to by arg should be
75 at least FMNAMESZ+1 bytes long, where FMNAMESZ is defined in
76 <stropts.h>.
77 The ioctl() function with the I_LOOK command shall fail if:
79 EINVAL
81 No module present in the STREAM.
82 I_FLUSH
85 Flushes read and/or write queues, depending on the value of arg.
86 Valid arg values are:
87 FLUSHR
89 Flush all read queues.
90 FLUSHW
92 Flush all write queues.
93 FLUSHRW
95 Flush all read and all write queues.
96 The ioctl() function with the I_FLUSH command shall fail if:
99 EINVAL
101 Invalid arg value.
102 EAGAIN or ENOSR
104 Unable to allocate buffers for flush message.
106 ENXIO
108 Hangup received on fildes.
109 I_FLUSHBAND
112 Flushes a particular band of messages. The arg argument points
113 to a bandinfo structure. The bi_flag member may be one of
114 FLUSHR, FLUSHW, or FLUSHRW as described above. The bi_pri member
115 determines the priority band to be flushed.
116 I_SETSIG
118 Requests that the STREAMS implementation send the SIGPOLL signal
119 to the calling process when a particular event has occurred on
120 the STREAM associated with fildes. I_SETSIG supports an asyn‐
121 chronous processing capability in STREAMS. The value of arg is a
122 bitmask that specifies the events for which the process should
123 be signaled. It is the bitwise-inclusive OR of any combination
124 of the following constants:
125 S_RDNORM
127 A normal (priority band set to 0) message has arrived at the
128 head of a STREAM head read queue. A signal shall be generated
129 even if the message is of zero length.
130 S_RDBAND
132 A message with a non-zero priority band has arrived at the head
133 of a STREAM head read queue. A signal shall be generated even if
134 the message is of zero length.
135 S_INPUT
137 A message, other than a high-priority message, has arrived at
138 the head of a STREAM head read queue. A signal shall be gener‐
139 ated even if the message is of zero length.
140 S_HIPRI
142 A high-priority message is present on a STREAM head read queue.
143 A signal shall be generated even if the message is of zero
144 length.
145 S_OUTPUT
147 The write queue for normal data (priority band 0) just below the
148 STREAM head is no longer full. This notifies the process that
149 there is room on the queue for sending (or writing) normal data
150 downstream.
151 S_WRNORM
153 Equivalent to S_OUTPUT.
154 S_WRBAND
156 The write queue for a non-zero priority band just below the
157 STREAM head is no longer full. This notifies the process that
158 there is room on the queue for sending (or writing) priority
159 data downstream.
160 S_MSG
162 A STREAMS signal message that contains the SIGPOLL signal has
163 reached the front of the STREAM head read queue.
164 S_ERROR
166 Notification of an error condition has reached the STREAM head.
167 S_HANGUP
169 Notification of a hangup has reached the STREAM head.
170 S_BANDURG
172 When used in conjunction with S_RDBAND, SIGURG is generated
173 instead of SIGPOLL when a priority message reaches the front of
174 the STREAM head read queue.
175 If arg is 0, the calling process shall be unregistered and shall not
178 receive further SIGPOLL signals for the stream associated with fildes.
179 Processes that wish to receive SIGPOLL signals shall ensure that they
181 explicitly register to receive them using I_SETSIG. If several pro‐
182 cesses register to receive this signal for the same event on the same
183 STREAM, each process shall be signaled when the event occurs.
184 The ioctl() function with the I_SETSIG command shall fail if:
186 EINVAL
188 The value of arg is invalid.
189 EINVAL
191 The value of arg is 0 and the calling process is not registered
192 to receive the SIGPOLL signal.
193 EAGAIN
195 There were insufficient resources to store the signal request.
196 I_GETSIG
199 Returns the events for which the calling process is currently
200 registered to be sent a SIGPOLL signal. The events are returned
201 as a bitmask in an int pointed to by arg, where the events are
202 those specified in the description of I_SETSIG above.
203 The ioctl() function with the I_GETSIG command shall fail if:
205 EINVAL
207 Process is not registered to receive the SIGPOLL signal.
208 I_FIND Compares the names of all modules currently present in the
211 STREAM to the name pointed to by arg, and returns 1 if the named
212 module is present in the STREAM, or returns 0 if the named mod‐
213 ule is not present.
214 The ioctl() function with the I_FIND command shall fail if:
216 EINVAL
218 arg does not contain a valid module name.
219 I_PEEK Retrieves the information in the first message on the STREAM
222 head read queue without taking the message off the queue. It is
223 analogous to getmsg() except that this command does not remove
224 the message from the queue. The arg argument points to a strpeek
225 structure.
226 The application shall ensure that the maxlen member in the ctlbuf and
228 databuf strbuf structures is set to the number of bytes of control
229 information and/or data information, respectively, to retrieve. The
230 flags member may be marked RS_HIPRI or 0, as described by getmsg(). If
231 the process sets flags to RS_HIPRI, for example, I_PEEK shall only look
232 for a high-priority message on the STREAM head read queue.
233 I_PEEK returns 1 if a message was retrieved, and returns 0 if no mes‐
235 sage was found on the STREAM head read queue, or if the RS_HIPRI flag
236 was set in flags and a high-priority message was not present on the
237 STREAM head read queue. It does not wait for a message to arrive. On
238 return, ctlbuf specifies information in the control buffer, databuf
239 specifies information in the data buffer, and flags contains the value
240 RS_HIPRI or 0.
241 I_SRDOPT
243 Sets the read mode using the value of the argument arg. Read
244 modes are described in read(). Valid arg flags are:
245 RNORM
247 Byte-stream mode, the default.
248 RMSGD
250 Message-discard mode.
251 RMSGN
253 Message-nondiscard mode.
254 The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. The
257 bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall result in
258 the other flag overriding RNORM which is the default.
259 In addition, treatment of control messages by the STREAM head may be
261 changed by setting any of the following flags in arg:
262 RPROTNORM
264 Fail read() with [EBADMSG] if a message containing a control
265 part is at the front of the STREAM head read queue.
266 RPROTDAT
268 Deliver the control part of a message as data when a process
269 issues a read().
270 RPROTDIS
272 Discard the control part of a message, delivering any data por‐
273 tion, when a process issues a read().
274 The ioctl() function with the I_SRDOPT command shall fail if:
277 EINVAL
279 The arg argument is not valid.
280 I_GRDOPT
283 Returns the current read mode setting, as described above, in an
284 int pointed to by the argument arg. Read modes are described in
285 read().
286 I_NREAD
288 Counts the number of data bytes in the data part of the first
289 message on the STREAM head read queue and places this value in
290 the int pointed to by arg. The return value for the command
291 shall be the number of messages on the STREAM head read queue.
292 For example, if 0 is returned in arg, but the ioctl() return
293 value is greater than 0, this indicates that a zero-length mes‐
294 sage is next on the queue.
295 I_FDINSERT
297 Creates a message from specified buffer(s), adds information
298 about another STREAM, and sends the message downstream. The mes‐
299 sage contains a control part and an optional data part. The data
300 and control parts to be sent are distinguished by placement in
301 separate buffers, as described below. The arg argument points to
302 a strfdinsert structure.
303 The application shall ensure that the len member in the ctlbuf strbuf
305 structure is set to the size of a t_uscalar_t plus the number of bytes
306 of control information to be sent with the message. The fildes member
307 specifies the file descriptor of the other STREAM, and the offset mem‐
308 ber, which must be suitably aligned for use as a t_uscalar_t, specifies
309 the offset from the start of the control buffer where I_FDINSERT shall
310 store a t_uscalar_t whose interpretation is specific to the STREAM end.
311 The application shall ensure that the len member in the databuf strbuf
312 structure is set to the number of bytes of data information to be sent
313 with the message, or to 0 if no data part is to be sent.
314 The flags member specifies the type of message to be created. A normal
316 message is created if flags is set to 0, and a high-priority message is
317 created if flags is set to RS_HIPRI. For non-priority messages,
318 I_FDINSERT shall block if the STREAM write queue is full due to inter‐
319 nal flow control conditions. For priority messages, I_FDINSERT does
320 not block on this condition. For non-priority messages, I_FDINSERT does
321 not block when the write queue is full and O_NONBLOCK is set. Instead,
322 it fails and sets errno to [EAGAIN].
323 I_FDINSERT also blocks, unless prevented by lack of internal resources,
325 waiting for the availability of message blocks in the STREAM, regard‐
326 less of priority or whether O_NONBLOCK has been specified. No partial
327 message is sent.
328 The ioctl() function with the I_FDINSERT command shall fail if:
330 EAGAIN
332 A non-priority message is specified, the O_NONBLOCK flag is set,
333 and the STREAM write queue is full due to internal flow control
334 conditions.
335 EAGAIN or ENOSR
337 Buffers cannot be allocated for the message that is to be cre‐
339 ated.
340 EINVAL
342 One of the following:
343 * The fildes member of the strfdinsert structure is not
345 a valid, open STREAM file descriptor.
346 * The size of a t_uscalar_t plus offset is greater than
348 the len member for the buffer specified through ctl‐
349 buf.
350 * The offset member does not specify a properly-aligned
352 location in the data buffer.
353 * An undefined value is stored in flags.
355 ENXIO
357 Hangup received on the STREAM identified by either the fildes
358 argument or the fildes member of the strfdinsert structure.
359 ERANGE
361 The len member for the buffer specified through databuf does not
362 fall within the range specified by the maximum and minimum
363 packet sizes of the topmost STREAM module; or the len member for
364 the buffer specified through databuf is larger than the maximum
365 configured size of the data part of a message; or the len member
366 for the buffer specified through ctlbuf is larger than the maxi‐
367 mum configured size of the control part of a message.
368 I_STR Constructs an internal STREAMS ioctl() message from the data
371 pointed to by arg, and sends that message downstream.
372 This mechanism is provided to send ioctl() requests to downstream mod‐
374 ules and drivers. It allows information to be sent with ioctl(), and
375 returns to the process any information sent upstream by the downstream
376 recipient. I_STR shall block until the system responds with either a
377 positive or negative acknowledgement message, or until the request
378 times out after some period of time. If the request times out, it shall
379 fail with errno set to [ETIME].
380 At most, one I_STR can be active on a STREAM. Further I_STR calls shall
382 block until the active I_STR completes at the STREAM head. The default
383 timeout interval for these requests is 15 seconds. The O_NONBLOCK flag
384 has no effect on this call.
385 To send requests downstream, the application shall ensure that arg
387 points to a strioctl structure.
388 The ic_cmd member is the internal ioctl() command intended for a down‐
390 stream module or driver and ic_timout is the number of seconds
391 (-1=infinite, 0=use implementation-defined timeout interval, >0=as
392 specified) an I_STR request shall wait for acknowledgement before tim‐
393 ing out. ic_len is the number of bytes in the data argument, and ic_dp
394 is a pointer to the data argument. The ic_len member has two uses: on
395 input, it contains the length of the data argument passed in, and on
396 return from the command, it contains the number of bytes being returned
397 to the process (the buffer pointed to by ic_dp should be large enough
398 to contain the maximum amount of data that any module or the driver in
399 the STREAM can return).
400 The STREAM head shall convert the information pointed to by the stri‐
402 octl structure to an internal ioctl() command message and send it down‐
403 stream.
404 The ioctl() function with the I_STR command shall fail if:
406 EAGAIN or ENOSR
408 Unable to allocate buffers for the ioctl() message.
410 EINVAL
412 The ic_len member is less than 0 or larger than the maximum con‐
413 figured size of the data part of a message, or ic_timout is less
414 than -1.
415 ENXIO
417 Hangup received on fildes.
418 ETIME
420 A downstream ioctl() timed out before acknowledgement was
421 received.
422 An I_STR can also fail while waiting for an acknowledgement if a mes‐
425 sage indicating an error or a hangup is received at the STREAM head. In
426 addition, an error code can be returned in the positive or negative
427 acknowledgement message, in the event the ioctl() command sent down‐
428 stream fails. For these cases, I_STR shall fail with errno set to the
429 value in the message.
430 I_SWROPT
432 Sets the write mode using the value of the argument arg. Valid
433 bit settings for arg are:
434 SNDZERO
436 Send a zero-length message downstream when a write() of 0 bytes
437 occurs. To not send a zero-length message when a write() of 0
438 bytes occurs, the application shall ensure that this bit is not
439 set in arg (for example, arg would be set to 0).
440 The ioctl() function with the I_SWROPT command shall fail if:
443 EINVAL
445 arg is not the above value.
446 I_GWROPT
449 Returns the current write mode setting, as described above, in
450 the int that is pointed to by the argument arg.
451 I_SENDFD
453 Creates a new reference to the open file description associated
454 with the file descriptor arg, and writes a message on the
455 STREAMS-based pipe fildes containing this reference, together
456 with the user ID and group ID of the calling process.
457 The ioctl() function with the I_SENDFD command shall fail if:
459 EAGAIN
461 The sending STREAM is unable to allocate a message block to con‐
462 tain the file pointer; or the read queue of the receiving STREAM
463 head is full and cannot accept the message sent by I_SENDFD.
464 EBADF
466 The arg argument is not a valid, open file descriptor.
467 EINVAL
469 The fildes argument is not connected to a STREAM pipe.
470 ENXIO
472 Hangup received on fildes.
473 I_RECVFD
476 Retrieves the reference to an open file description from a mes‐
477 sage written to a STREAMS-based pipe using the I_SENDFD command,
478 and allocates a new file descriptor in the calling process that
479 refers to this open file description. The arg argument is a
480 pointer to a strrecvfd data structure as defined in <stropts.h>.
481 The fd member is a file descriptor. The uid and gid members are the
483 effective user ID and effective group ID, respectively, of the sending
484 process.
485 If O_NONBLOCK is not set, I_RECVFD shall block until a message is
487 present at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail
488 with errno set to [EAGAIN] if no message is present at the STREAM head.
489 If the message at the STREAM head is a message sent by an I_SENDFD, a
491 new file descriptor shall be allocated for the open file descriptor
492 referenced in the message. The new file descriptor is placed in the fd
493 member of the strrecvfd structure pointed to by arg.
494 The ioctl() function with the I_RECVFD command shall fail if:
496 EAGAIN
498 A message is not present at the STREAM head read queue and the
499 O_NONBLOCK flag is set.
500 EBADMSG
502 The message at the STREAM head read queue is not a message con‐
503 taining a passed file descriptor.
504 EMFILE
506 The process has the maximum number of file descriptors currently
507 open that it is allowed.
508 ENXIO
510 Hangup received on fildes.
511 I_LIST Allows the process to list all the module names on the STREAM,
514 up to and including the topmost driver name. If arg is a null
515 pointer, the return value shall be the number of modules,
516 including the driver, that are on the STREAM pointed to by
517 fildes. This lets the process allocate enough space for the mod‐
518 ule names. Otherwise, it should point to a str_list structure.
519 The sl_nmods member indicates the number of entries the process has
521 allocated in the array. Upon return, the sl_modlist member of the
522 str_list structure shall contain the list of module names, and the num‐
523 ber of entries that have been filled into the sl_modlist array is found
524 in the sl_nmods member (the number includes the number of modules
525 including the driver). The return value from ioctl() shall be 0. The
526 entries are filled in starting at the top of the STREAM and continuing
527 downstream until either the end of the STREAM is reached, or the number
528 of requested modules ( sl_nmods) is satisfied.
529 The ioctl() function with the I_LIST command shall fail if:
531 EINVAL
533 The sl_nmods member is less than 1.
534 EAGAIN or ENOSR
536 Unable to allocate buffers.
538 I_ATMARK
541 Allows the process to see if the message at the head of the
542 STREAM head read queue is marked by some module downstream. The
543 arg argument determines how the checking is done when there may
544 be multiple marked messages on the STREAM head read queue. It
545 may take on the following values:
546 ANYMARK
548 Check if the message is marked.
549 LASTMARK
551 Check if the message is the last one marked on the queue.
552 The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permit‐
555 ted.
556 The return value shall be 1 if the mark condition is satisfied; other‐
558 wise, the value shall be 0.
559 The ioctl() function with the I_ATMARK command shall fail if:
561 EINVAL
563 Invalid arg value.
564 I_CKBAND
567 Checks if the message of a given priority band exists on the
568 STREAM head read queue. This shall return 1 if a message of the
569 given priority exists, 0 if no such message exists, or -1 on
570 error. arg should be of type int.
571 The ioctl() function with the I_CKBAND command shall fail if:
573 EINVAL
575 Invalid arg value.
576 I_GETBAND
579 Returns the priority band of the first message on the STREAM
580 head read queue in the integer referenced by arg.
581 The ioctl() function with the I_GETBAND command shall fail if:
583 ENODATA
585 No message on the STREAM head read queue.
586 I_CANPUT
589 Checks if a certain band is writable. arg is set to the priority
590 band in question. The return value shall be 0 if the band is
591 flow-controlled, 1 if the band is writable, or -1 on error.
592 The ioctl() function with the I_CANPUT command shall fail if:
594 EINVAL
596 Invalid arg value.
597 I_SETCLTIME
600 This request allows the process to set the time the STREAM head
601 shall delay when a STREAM is closing and there is data on the
602 write queues. Before closing each module or driver, if there is
603 data on its write queue, the STREAM head shall delay for the
604 specified amount of time to allow the data to drain. If, after
605 the delay, data is still present, it shall be flushed. The arg
606 argument is a pointer to an integer specifying the number of
607 milliseconds to delay, rounded up to the nearest valid value. If
608 I_SETCLTIME is not performed on a STREAM, an implementation-
609 defined default timeout interval is used.
610 The ioctl() function with the I_SETCLTIME command shall fail if:
612 EINVAL
614 Invalid arg value.
615 I_GETCLTIME
618 Returns the close time delay in the integer pointed to by arg.
619 Multiplexed STREAMS Configurations
622 The following commands are used for connecting and disconnecting multi‐
623 plexed STREAMS configurations. These commands use an implementation-
624 defined default timeout interval.
625 I_LINK Connects two STREAMs, where fildes is the file descriptor of the
627 STREAM connected to the multiplexing driver, and arg is the file
628 descriptor of the STREAM connected to another driver. The STREAM
629 designated by arg is connected below the multiplexing driver.
630 I_LINK requires the multiplexing driver to send an acknowledge‐
631 ment message to the STREAM head regarding the connection. This
632 call shall return a multiplexer ID number (an identifier used to
633 disconnect the multiplexer; see I_UNLINK) on success, and -1 on
634 failure.
635 The ioctl() function with the I_LINK command shall fail if:
637 ENXIO
639 Hangup received on fildes.
640 ETIME
642 Timeout before acknowledgement message was received at STREAM
643 head.
644 EAGAIN or ENOSR
646 Unable to allocate STREAMS storage to perform the I_LINK.
648 EBADF
650 The arg argument is not a valid, open file descriptor.
651 EINVAL
653 The fildes argument does not support multiplexing; or arg is not
654 a STREAM or is already connected downstream from a multiplexer;
655 or the specified I_LINK operation would connect the STREAM head
656 in more than one place in the multiplexed STREAM.
657 An I_LINK can also fail while waiting for the multiplexing driver to
660 acknowledge the request, if a message indicating an error or a hangup
661 is received at the STREAM head of fildes. In addition, an error code
662 can be returned in the positive or negative acknowledgement message.
663 For these cases, I_LINK fails with errno set to the value in the mes‐
664 sage.
665 I_UNLINK
667 Disconnects the two STREAMs specified by fildes and arg. fildes
668 is the file descriptor of the STREAM connected to the multiplex‐
669 ing driver. The arg argument is the multiplexer ID number that
670 was returned by the I_LINK ioctl() command when a STREAM was
671 connected downstream from the multiplexing driver. If arg is
672 MUXID_ALL, then all STREAMs that were connected to fildes shall
673 be disconnected. As in I_LINK, this command requires acknowl‐
674 edgement.
675 The ioctl() function with the I_UNLINK command shall fail if:
677 ENXIO
679 Hangup received on fildes.
680 ETIME
682 Timeout before acknowledgement message was received at STREAM
683 head.
684 EAGAIN or ENOSR
686 Unable to allocate buffers for the acknowledgement message.
688 EINVAL
690 Invalid multiplexer ID number.
691 An I_UNLINK can also fail while waiting for the multiplexing driver to
694 acknowledge the request if a message indicating an error or a hangup is
695 received at the STREAM head of fildes. In addition, an error code can
696 be returned in the positive or negative acknowledgement message. For
697 these cases, I_UNLINK shall fail with errno set to the value in the
698 message.
699 I_PLINK
701 Creates a persistent connection between two STREAMs, where
702 fildes is the file descriptor of the STREAM connected to the
703 multiplexing driver, and arg is the file descriptor of the
704 STREAM connected to another driver. This call shall create a
705 persistent connection which can exist even if the file descrip‐
706 tor fildes associated with the upper STREAM to the multiplexing
707 driver is closed. The STREAM designated by arg gets connected
708 via a persistent connection below the multiplexing driver.
709 I_PLINK requires the multiplexing driver to send an acknowledge‐
710 ment message to the STREAM head. This call shall return a multi‐
711 plexer ID number (an identifier that may be used to disconnect
712 the multiplexer; see I_PUNLINK) on success, and -1 on failure.
713 The ioctl() function with the I_PLINK command shall fail if:
715 ENXIO
717 Hangup received on fildes.
718 ETIME
720 Timeout before acknowledgement message was received at STREAM
721 head.
722 EAGAIN or ENOSR
724 Unable to allocate STREAMS storage to perform the I_PLINK.
726 EBADF
728 The arg argument is not a valid, open file descriptor.
729 EINVAL
731 The fildes argument does not support multiplexing; or arg is not
732 a STREAM or is already connected downstream from a multiplexer;
733 or the specified I_PLINK operation would connect the STREAM head
734 in more than one place in the multiplexed STREAM.
735 An I_PLINK can also fail while waiting for the multiplexing driver to
738 acknowledge the request, if a message indicating an error or a hangup
739 is received at the STREAM head of fildes. In addition, an error code
740 can be returned in the positive or negative acknowledgement message.
741 For these cases, I_PLINK shall fail with errno set to the value in the
742 message.
743 I_PUNLINK
745 Disconnects the two STREAMs specified by fildes and arg from a
746 persistent connection. The fildes argument is the file descrip‐
747 tor of the STREAM connected to the multiplexing driver. The arg
748 argument is the multiplexer ID number that was returned by the
749 I_PLINK ioctl() command when a STREAM was connected downstream
750 from the multiplexing driver. If arg is MUXID_ALL, then all
751 STREAMs which are persistent connections to fildes shall be dis‐
752 connected. As in I_PLINK, this command requires the multiplexing
753 driver to acknowledge the request.
754 The ioctl() function with the I_PUNLINK command shall fail if:
756 ENXIO
758 Hangup received on fildes.
759 ETIME
761 Timeout before acknowledgement message was received at STREAM
762 head.
763 EAGAIN or ENOSR
765 Unable to allocate buffers for the acknowledgement message.
767 EINVAL
769 Invalid multiplexer ID number.
770 An I_PUNLINK can also fail while waiting for the multiplexing driver to
773 acknowledge the request if a message indicating an error or a hangup is
774 received at the STREAM head of fildes. In addition, an error code can
775 be returned in the positive or negative acknowledgement message. For
776 these cases, I_PUNLINK shall fail with errno set to the value in the
777 message.
778
781 Upon successful completion, ioctl() shall return a value other than -1
782 that depends upon the STREAMS device control function. Otherwise, it
783 shall return -1 and set errno to indicate the error.
784
786 Under the following general conditions, ioctl() shall fail if:
787 EBADF The fildes argument is not a valid open file descriptor.
789 EINTR A signal was caught during the ioctl() operation.
791 EINVAL The STREAM or multiplexer referenced by fildes is linked
793 (directly or indirectly) downstream from a multiplexer.
794 If an underlying device driver detects an error, then ioctl() shall
797 fail if:
798 EINVAL The request or arg argument is not valid for this device.
800 EIO Some physical I/O error has occurred.
802 ENOTTY The fildes argument is not associated with a STREAMS device that
804 accepts control functions.
805 ENXIO The request and arg arguments are valid for this device driver,
807 but the service requested cannot be performed on this particular
808 sub-device.
809 ENODEV The fildes argument refers to a valid STREAMS device, but the
811 corresponding device driver does not support the ioctl() func‐
812 tion.
813 If a STREAM is connected downstream from a multiplexer, any ioctl()
816 command except I_UNLINK and I_PUNLINK shall set errno to [EINVAL].
817 The following sections are informative.
819
821 None.
822
824 The implementation-defined timeout interval for STREAMS has histori‐
825 cally been 15 seconds.
826
828 None.
829
831 None.
832
834 STREAMS, close(), fcntl(), getmsg(), open(), pipe(), poll(), putmsg(),
835 read(), sigaction(), write(), the Base Definitions volume of
836 IEEE Std 1003.1-2001, <stropts.h>
837
839 Portions of this text are reprinted and reproduced in electronic form
840 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
841 -- Portable Operating System Interface (POSIX), The Open Group Base
842 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
843 Electrical and Electronics Engineers, Inc and The Open Group. In the
844 event of any discrepancy between this version and the original IEEE and
845 The Open Group Standard, the original IEEE and The Open Group Standard
846 is the referee document. The original Standard can be obtained online
847 at http://www.opengroup.org/unix/online.html .
848IEEE/The Open Group 2003 IOCTL(3P)