1IOCTL(P) POSIX Programmer's Manual IOCTL(P)
2
6 ioctl - control a STREAMS device (STREAMS)
7
9 #include <stropts.h>
10 int ioctl(int fildes, int request, ... /* arg */);
12
15 The ioctl() function shall perform a variety of control functions on
16 STREAMS devices. For non-STREAMS devices, the functions performed by
17 this call are unspecified. The request argument and an optional third
18 argument (with varying type) shall be passed to and interpreted by the
19 appropriate part of the STREAM associated with fildes.
20 The fildes argument is an open file descriptor that refers to a device.
22 The request argument selects the control function to be performed and
24 shall depend on the STREAMS device being addressed.
25 The arg argument represents additional information that is needed by
27 this specific STREAMS device to perform the requested function. The
28 type of arg depends upon the particular control request, but it shall
29 be either an integer or a pointer to a device-specific data structure.
30 The ioctl() commands applicable to STREAMS, their arguments, and error
32 conditions that apply to each individual command are described below.
33 The following ioctl() commands, with error values indicated, are appli‐
35 cable to all STREAMS files:
36 I_PUSH Pushes the module whose name is pointed to by arg onto the top
38 of the current STREAM, just below the STREAM head. It then calls
39 the open() function of the newly-pushed module.
40 The ioctl() function with the I_PUSH command shall fail if:
42 EINVAL
44 Invalid module name.
45 ENXIO
47 Open function of new module failed.
48 ENXIO
50 Hangup received on fildes.
51 I_POP Removes the module just below the STREAM head of the STREAM
54 pointed to by fildes. The arg argument should be 0 in an I_POP
55 request.
56 The ioctl() function with the I_POP command shall fail if:
58 EINVAL
60 No module present in the STREAM.
61 ENXIO
63 Hangup received on fildes.
64 I_LOOK Retrieves the name of the module just below the STREAM head of
67 the STREAM pointed to by fildes, and places it in a character
68 string pointed to by arg. The buffer pointed to by arg should be
69 at least FMNAMESZ+1 bytes long, where FMNAMESZ is defined in
70 <stropts.h>.
71 The ioctl() function with the I_LOOK command shall fail if:
73 EINVAL
75 No module present in the STREAM.
76 I_FLUSH
79 Flushes read and/or write queues, depending on the value of arg.
80 Valid arg values are:
81 FLUSHR
83 Flush all read queues.
84 FLUSHW
86 Flush all write queues.
87 FLUSHRW
89 Flush all read and all write queues.
90 The ioctl() function with the I_FLUSH command shall fail if:
93 EINVAL
95 Invalid arg value.
96 EAGAIN or ENOSR
98 Unable to allocate buffers for flush message.
100 ENXIO
102 Hangup received on fildes.
103 I_FLUSHBAND
106 Flushes a particular band of messages. The arg argument points
107 to a bandinfo structure. The bi_flag member may be one of
108 FLUSHR, FLUSHW, or FLUSHRW as described above. The bi_pri member
109 determines the priority band to be flushed.
110 I_SETSIG
112 Requests that the STREAMS implementation send the SIGPOLL signal
113 to the calling process when a particular event has occurred on
114 the STREAM associated with fildes. I_SETSIG supports an asyn‐
115 chronous processing capability in STREAMS. The value of arg is a
116 bitmask that specifies the events for which the process should
117 be signaled. It is the bitwise-inclusive OR of any combination
118 of the following constants:
119 S_RDNORM
121 A normal (priority band set to 0) message has arrived at the
122 head of a STREAM head read queue. A signal shall be generated
123 even if the message is of zero length.
124 S_RDBAND
126 A message with a non-zero priority band has arrived at the head
127 of a STREAM head read queue. A signal shall be generated even if
128 the message is of zero length.
129 S_INPUT
131 A message, other than a high-priority message, has arrived at
132 the head of a STREAM head read queue. A signal shall be gener‐
133 ated even if the message is of zero length.
134 S_HIPRI
136 A high-priority message is present on a STREAM head read queue.
137 A signal shall be generated even if the message is of zero
138 length.
139 S_OUTPUT
141 The write queue for normal data (priority band 0) just below the
142 STREAM head is no longer full. This notifies the process that
143 there is room on the queue for sending (or writing) normal data
144 downstream.
145 S_WRNORM
147 Equivalent to S_OUTPUT.
148 S_WRBAND
150 The write queue for a non-zero priority band just below the
151 STREAM head is no longer full. This notifies the process that
152 there is room on the queue for sending (or writing) priority
153 data downstream.
154 S_MSG
156 A STREAMS signal message that contains the SIGPOLL signal has
157 reached the front of the STREAM head read queue.
158 S_ERROR
160 Notification of an error condition has reached the STREAM head.
161 S_HANGUP
163 Notification of a hangup has reached the STREAM head.
164 S_BANDURG
166 When used in conjunction with S_RDBAND, SIGURG is generated
167 instead of SIGPOLL when a priority message reaches the front of
168 the STREAM head read queue.
169 If arg is 0, the calling process shall be unregistered and shall not
172 receive further SIGPOLL signals for the stream associated with fildes.
173 Processes that wish to receive SIGPOLL signals shall ensure that they
175 explicitly register to receive them using I_SETSIG. If several pro‐
176 cesses register to receive this signal for the same event on the same
177 STREAM, each process shall be signaled when the event occurs.
178 The ioctl() function with the I_SETSIG command shall fail if:
180 EINVAL
182 The value of arg is invalid.
183 EINVAL
185 The value of arg is 0 and the calling process is not registered
186 to receive the SIGPOLL signal.
187 EAGAIN
189 There were insufficient resources to store the signal request.
190 I_GETSIG
193 Returns the events for which the calling process is currently
194 registered to be sent a SIGPOLL signal. The events are returned
195 as a bitmask in an int pointed to by arg, where the events are
196 those specified in the description of I_SETSIG above.
197 The ioctl() function with the I_GETSIG command shall fail if:
199 EINVAL
201 Process is not registered to receive the SIGPOLL signal.
202 I_FIND Compares the names of all modules currently present in the
205 STREAM to the name pointed to by arg, and returns 1 if the named
206 module is present in the STREAM, or returns 0 if the named mod‐
207 ule is not present.
208 The ioctl() function with the I_FIND command shall fail if:
210 EINVAL
212 arg does not contain a valid module name.
213 I_PEEK Retrieves the information in the first message on the STREAM
216 head read queue without taking the message off the queue. It is
217 analogous to getmsg() except that this command does not remove
218 the message from the queue. The arg argument points to a strpeek
219 structure.
220 The application shall ensure that the maxlen member in the ctlbuf and
222 databuf strbuf structures is set to the number of bytes of control
223 information and/or data information, respectively, to retrieve. The
224 flags member may be marked RS_HIPRI or 0, as described by getmsg(). If
225 the process sets flags to RS_HIPRI, for example, I_PEEK shall only look
226 for a high-priority message on the STREAM head read queue.
227 I_PEEK returns 1 if a message was retrieved, and returns 0 if no mes‐
229 sage was found on the STREAM head read queue, or if the RS_HIPRI flag
230 was set in flags and a high-priority message was not present on the
231 STREAM head read queue. It does not wait for a message to arrive. On
232 return, ctlbuf specifies information in the control buffer, databuf
233 specifies information in the data buffer, and flags contains the value
234 RS_HIPRI or 0.
235 I_SRDOPT
237 Sets the read mode using the value of the argument arg. Read
238 modes are described in read() . Valid arg flags are:
239 RNORM
241 Byte-stream mode, the default.
242 RMSGD
244 Message-discard mode.
245 RMSGN
247 Message-nondiscard mode.
248 The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. The
251 bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall result in
252 the other flag overriding RNORM which is the default.
253 In addition, treatment of control messages by the STREAM head may be
255 changed by setting any of the following flags in arg:
256 RPROTNORM
258 Fail read() with [EBADMSG] if a message containing a control
259 part is at the front of the STREAM head read queue.
260 RPROTDAT
262 Deliver the control part of a message as data when a process
263 issues a read().
264 RPROTDIS
266 Discard the control part of a message, delivering any data por‐
267 tion, when a process issues a read().
268 The ioctl() function with the I_SRDOPT command shall fail if:
271 EINVAL
273 The arg argument is not valid.
274 I_GRDOPT
277 Returns the current read mode setting, as described above, in an
278 int pointed to by the argument arg. Read modes are described in
279 read() .
280 I_NREAD
282 Counts the number of data bytes in the data part of the first
283 message on the STREAM head read queue and places this value in
284 the int pointed to by arg. The return value for the command
285 shall be the number of messages on the STREAM head read queue.
286 For example, if 0 is returned in arg, but the ioctl() return
287 value is greater than 0, this indicates that a zero-length mes‐
288 sage is next on the queue.
289 I_FDINSERT
291 Creates a message from specified buffer(s), adds information
292 about another STREAM, and sends the message downstream. The mes‐
293 sage contains a control part and an optional data part. The data
294 and control parts to be sent are distinguished by placement in
295 separate buffers, as described below. The arg argument points to
296 a strfdinsert structure.
297 The application shall ensure that the len member in the ctlbuf strbuf
299 structure is set to the size of a t_uscalar_t plus the number of bytes
300 of control information to be sent with the message. The fildes member
301 specifies the file descriptor of the other STREAM, and the offset mem‐
302 ber, which must be suitably aligned for use as a t_uscalar_t, specifies
303 the offset from the start of the control buffer where I_FDINSERT shall
304 store a t_uscalar_t whose interpretation is specific to the STREAM end.
305 The application shall ensure that the len member in the databuf strbuf
306 structure is set to the number of bytes of data information to be sent
307 with the message, or to 0 if no data part is to be sent.
308 The flags member specifies the type of message to be created. A normal
310 message is created if flags is set to 0, and a high-priority message is
311 created if flags is set to RS_HIPRI. For non-priority messages,
312 I_FDINSERT shall block if the STREAM write queue is full due to inter‐
313 nal flow control conditions. For priority messages, I_FDINSERT does
314 not block on this condition. For non-priority messages, I_FDINSERT does
315 not block when the write queue is full and O_NONBLOCK is set. Instead,
316 it fails and sets errno to [EAGAIN].
317 I_FDINSERT also blocks, unless prevented by lack of internal resources,
319 waiting for the availability of message blocks in the STREAM, regard‐
320 less of priority or whether O_NONBLOCK has been specified. No partial
321 message is sent.
322 The ioctl() function with the I_FDINSERT command shall fail if:
324 EAGAIN
326 A non-priority message is specified, the O_NONBLOCK flag is set,
327 and the STREAM write queue is full due to internal flow control
328 conditions.
329 EAGAIN or ENOSR
331 Buffers cannot be allocated for the message that is to be cre‐
333 ated.
334 EINVAL
336 One of the following:
337 * The fildes member of the strfdinsert structure is not
339 a valid, open STREAM file descriptor.
340 * The size of a t_uscalar_t plus offset is greater than
342 the len member for the buffer specified through ctl‐
343 buf.
344 * The offset member does not specify a properly-aligned
346 location in the data buffer.
347 * An undefined value is stored in flags.
349 ENXIO
351 Hangup received on the STREAM identified by either the fildes
352 argument or the fildes member of the strfdinsert structure.
353 ERANGE
355 The len member for the buffer specified through databuf does not
356 fall within the range specified by the maximum and minimum
357 packet sizes of the topmost STREAM module; or the len member for
358 the buffer specified through databuf is larger than the maximum
359 configured size of the data part of a message; or the len member
360 for the buffer specified through ctlbuf is larger than the maxi‐
361 mum configured size of the control part of a message.
362 I_STR Constructs an internal STREAMS ioctl() message from the data
365 pointed to by arg, and sends that message downstream.
366 This mechanism is provided to send ioctl() requests to downstream mod‐
368 ules and drivers. It allows information to be sent with ioctl(), and
369 returns to the process any information sent upstream by the downstream
370 recipient. I_STR shall block until the system responds with either a
371 positive or negative acknowledgement message, or until the request
372 times out after some period of time. If the request times out, it shall
373 fail with errno set to [ETIME].
374 At most, one I_STR can be active on a STREAM. Further I_STR calls shall
376 block until the active I_STR completes at the STREAM head. The default
377 timeout interval for these requests is 15 seconds. The O_NONBLOCK flag
378 has no effect on this call.
379 To send requests downstream, the application shall ensure that arg
381 points to a strioctl structure.
382 The ic_cmd member is the internal ioctl() command intended for a down‐
384 stream module or driver and ic_timout is the number of seconds
385 (-1=infinite, 0=use implementation-defined timeout interval, >0=as
386 specified) an I_STR request shall wait for acknowledgement before tim‐
387 ing out. ic_len is the number of bytes in the data argument, and ic_dp
388 is a pointer to the data argument. The ic_len member has two uses: on
389 input, it contains the length of the data argument passed in, and on
390 return from the command, it contains the number of bytes being returned
391 to the process (the buffer pointed to by ic_dp should be large enough
392 to contain the maximum amount of data that any module or the driver in
393 the STREAM can return).
394 The STREAM head shall convert the information pointed to by the stri‐
396 octl structure to an internal ioctl() command message and send it down‐
397 stream.
398 The ioctl() function with the I_STR command shall fail if:
400 EAGAIN or ENOSR
402 Unable to allocate buffers for the ioctl() message.
404 EINVAL
406 The ic_len member is less than 0 or larger than the maximum con‐
407 figured size of the data part of a message, or ic_timout is less
408 than -1.
409 ENXIO
411 Hangup received on fildes.
412 ETIME
414 A downstream ioctl() timed out before acknowledgement was
415 received.
416 An I_STR can also fail while waiting for an acknowledgement if a mes‐
419 sage indicating an error or a hangup is received at the STREAM head. In
420 addition, an error code can be returned in the positive or negative
421 acknowledgement message, in the event the ioctl() command sent down‐
422 stream fails. For these cases, I_STR shall fail with errno set to the
423 value in the message.
424 I_SWROPT
426 Sets the write mode using the value of the argument arg. Valid
427 bit settings for arg are:
428 SNDZERO
430 Send a zero-length message downstream when a write() of 0 bytes
431 occurs. To not send a zero-length message when a write() of 0
432 bytes occurs, the application shall ensure that this bit is not
433 set in arg (for example, arg would be set to 0).
434 The ioctl() function with the I_SWROPT command shall fail if:
437 EINVAL
439 arg is not the above value.
440 I_GWROPT
443 Returns the current write mode setting, as described above, in
444 the int that is pointed to by the argument arg.
445 I_SENDFD
447 Creates a new reference to the open file description associated
448 with the file descriptor arg, and writes a message on the
449 STREAMS-based pipe fildes containing this reference, together
450 with the user ID and group ID of the calling process.
451 The ioctl() function with the I_SENDFD command shall fail if:
453 EAGAIN
455 The sending STREAM is unable to allocate a message block to con‐
456 tain the file pointer; or the read queue of the receiving STREAM
457 head is full and cannot accept the message sent by I_SENDFD.
458 EBADF
460 The arg argument is not a valid, open file descriptor.
461 EINVAL
463 The fildes argument is not connected to a STREAM pipe.
464 ENXIO
466 Hangup received on fildes.
467 I_RECVFD
470 Retrieves the reference to an open file description from a mes‐
471 sage written to a STREAMS-based pipe using the I_SENDFD command,
472 and allocates a new file descriptor in the calling process that
473 refers to this open file description. The arg argument is a
474 pointer to a strrecvfd data structure as defined in <stropts.h>.
475 The fd member is a file descriptor. The uid and gid members are the
477 effective user ID and effective group ID, respectively, of the sending
478 process.
479 If O_NONBLOCK is not set, I_RECVFD shall block until a message is
481 present at the STREAM head. If O_NONBLOCK is set, I_RECVFD shall fail
482 with errno set to [EAGAIN] if no message is present at the STREAM head.
483 If the message at the STREAM head is a message sent by an I_SENDFD, a
485 new file descriptor shall be allocated for the open file descriptor
486 referenced in the message. The new file descriptor is placed in the fd
487 member of the strrecvfd structure pointed to by arg.
488 The ioctl() function with the I_RECVFD command shall fail if:
490 EAGAIN
492 A message is not present at the STREAM head read queue and the
493 O_NONBLOCK flag is set.
494 EBADMSG
496 The message at the STREAM head read queue is not a message con‐
497 taining a passed file descriptor.
498 EMFILE
500 The process has the maximum number of file descriptors currently
501 open that it is allowed.
502 ENXIO
504 Hangup received on fildes.
505 I_LIST Allows the process to list all the module names on the STREAM,
508 up to and including the topmost driver name. If arg is a null
509 pointer, the return value shall be the number of modules,
510 including the driver, that are on the STREAM pointed to by
511 fildes. This lets the process allocate enough space for the mod‐
512 ule names. Otherwise, it should point to a str_list structure.
513 The sl_nmods member indicates the number of entries the process has
515 allocated in the array. Upon return, the sl_modlist member of the
516 str_list structure shall contain the list of module names, and the num‐
517 ber of entries that have been filled into the sl_modlist array is found
518 in the sl_nmods member (the number includes the number of modules
519 including the driver). The return value from ioctl() shall be 0. The
520 entries are filled in starting at the top of the STREAM and continuing
521 downstream until either the end of the STREAM is reached, or the number
522 of requested modules ( sl_nmods) is satisfied.
523 The ioctl() function with the I_LIST command shall fail if:
525 EINVAL
527 The sl_nmods member is less than 1.
528 EAGAIN or ENOSR
530 Unable to allocate buffers.
532 I_ATMARK
535 Allows the process to see if the message at the head of the
536 STREAM head read queue is marked by some module downstream. The
537 arg argument determines how the checking is done when there may
538 be multiple marked messages on the STREAM head read queue. It
539 may take on the following values:
540 ANYMARK
542 Check if the message is marked.
543 LASTMARK
545 Check if the message is the last one marked on the queue.
546 The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permit‐
549 ted.
550 The return value shall be 1 if the mark condition is satisfied; other‐
552 wise, the value shall be 0.
553 The ioctl() function with the I_ATMARK command shall fail if:
555 EINVAL
557 Invalid arg value.
558 I_CKBAND
561 Checks if the message of a given priority band exists on the
562 STREAM head read queue. This shall return 1 if a message of the
563 given priority exists, 0 if no such message exists, or -1 on
564 error. arg should be of type int.
565 The ioctl() function with the I_CKBAND command shall fail if:
567 EINVAL
569 Invalid arg value.
570 I_GETBAND
573 Returns the priority band of the first message on the STREAM
574 head read queue in the integer referenced by arg.
575 The ioctl() function with the I_GETBAND command shall fail if:
577 ENODATA
579 No message on the STREAM head read queue.
580 I_CANPUT
583 Checks if a certain band is writable. arg is set to the priority
584 band in question. The return value shall be 0 if the band is
585 flow-controlled, 1 if the band is writable, or -1 on error.
586 The ioctl() function with the I_CANPUT command shall fail if:
588 EINVAL
590 Invalid arg value.
591 I_SETCLTIME
594 This request allows the process to set the time the STREAM head
595 shall delay when a STREAM is closing and there is data on the
596 write queues. Before closing each module or driver, if there is
597 data on its write queue, the STREAM head shall delay for the
598 specified amount of time to allow the data to drain. If, after
599 the delay, data is still present, it shall be flushed. The arg
600 argument is a pointer to an integer specifying the number of
601 milliseconds to delay, rounded up to the nearest valid value. If
602 I_SETCLTIME is not performed on a STREAM, an implementation-
603 defined default timeout interval is used.
604 The ioctl() function with the I_SETCLTIME command shall fail if:
606 EINVAL
608 Invalid arg value.
609 I_GETCLTIME
612 Returns the close time delay in the integer pointed to by arg.
613 Multiplexed STREAMS Configurations
616 The following commands are used for connecting and disconnecting multi‐
617 plexed STREAMS configurations. These commands use an implementation-
618 defined default timeout interval.
619 I_LINK Connects two STREAMs, where fildes is the file descriptor of the
621 STREAM connected to the multiplexing driver, and arg is the file
622 descriptor of the STREAM connected to another driver. The STREAM
623 designated by arg is connected below the multiplexing driver.
624 I_LINK requires the multiplexing driver to send an acknowledge‐
625 ment message to the STREAM head regarding the connection. This
626 call shall return a multiplexer ID number (an identifier used to
627 disconnect the multiplexer; see I_UNLINK) on success, and -1 on
628 failure.
629 The ioctl() function with the I_LINK command shall fail if:
631 ENXIO
633 Hangup received on fildes.
634 ETIME
636 Timeout before acknowledgement message was received at STREAM
637 head.
638 EAGAIN or ENOSR
640 Unable to allocate STREAMS storage to perform the I_LINK.
642 EBADF
644 The arg argument is not a valid, open file descriptor.
645 EINVAL
647 The fildes argument does not support multiplexing; or arg is not
648 a STREAM or is already connected downstream from a multiplexer;
649 or the specified I_LINK operation would connect the STREAM head
650 in more than one place in the multiplexed STREAM.
651 An I_LINK can also fail while waiting for the multiplexing driver to
654 acknowledge the request, if a message indicating an error or a hangup
655 is received at the STREAM head of fildes. In addition, an error code
656 can be returned in the positive or negative acknowledgement message.
657 For these cases, I_LINK fails with errno set to the value in the mes‐
658 sage.
659 I_UNLINK
661 Disconnects the two STREAMs specified by fildes and arg. fildes
662 is the file descriptor of the STREAM connected to the multiplex‐
663 ing driver. The arg argument is the multiplexer ID number that
664 was returned by the I_LINK ioctl() command when a STREAM was
665 connected downstream from the multiplexing driver. If arg is
666 MUXID_ALL, then all STREAMs that were connected to fildes shall
667 be disconnected. As in I_LINK, this command requires acknowl‐
668 edgement.
669 The ioctl() function with the I_UNLINK command shall fail if:
671 ENXIO
673 Hangup received on fildes.
674 ETIME
676 Timeout before acknowledgement message was received at STREAM
677 head.
678 EAGAIN or ENOSR
680 Unable to allocate buffers for the acknowledgement message.
682 EINVAL
684 Invalid multiplexer ID number.
685 An I_UNLINK can also fail while waiting for the multiplexing driver to
688 acknowledge the request if a message indicating an error or a hangup is
689 received at the STREAM head of fildes. In addition, an error code can
690 be returned in the positive or negative acknowledgement message. For
691 these cases, I_UNLINK shall fail with errno set to the value in the
692 message.
693 I_PLINK
695 Creates a persistent connection between two STREAMs, where
696 fildes is the file descriptor of the STREAM connected to the
697 multiplexing driver, and arg is the file descriptor of the
698 STREAM connected to another driver. This call shall create a
699 persistent connection which can exist even if the file descrip‐
700 tor fildes associated with the upper STREAM to the multiplexing
701 driver is closed. The STREAM designated by arg gets connected
702 via a persistent connection below the multiplexing driver.
703 I_PLINK requires the multiplexing driver to send an acknowledge‐
704 ment message to the STREAM head. This call shall return a multi‐
705 plexer ID number (an identifier that may be used to disconnect
706 the multiplexer; see I_PUNLINK) on success, and -1 on failure.
707 The ioctl() function with the I_PLINK command shall fail if:
709 ENXIO
711 Hangup received on fildes.
712 ETIME
714 Timeout before acknowledgement message was received at STREAM
715 head.
716 EAGAIN or ENOSR
718 Unable to allocate STREAMS storage to perform the I_PLINK.
720 EBADF
722 The arg argument is not a valid, open file descriptor.
723 EINVAL
725 The fildes argument does not support multiplexing; or arg is not
726 a STREAM or is already connected downstream from a multiplexer;
727 or the specified I_PLINK operation would connect the STREAM head
728 in more than one place in the multiplexed STREAM.
729 An I_PLINK can also fail while waiting for the multiplexing driver to
732 acknowledge the request, if a message indicating an error or a hangup
733 is received at the STREAM head of fildes. In addition, an error code
734 can be returned in the positive or negative acknowledgement message.
735 For these cases, I_PLINK shall fail with errno set to the value in the
736 message.
737 I_PUNLINK
739 Disconnects the two STREAMs specified by fildes and arg from a
740 persistent connection. The fildes argument is the file descrip‐
741 tor of the STREAM connected to the multiplexing driver. The arg
742 argument is the multiplexer ID number that was returned by the
743 I_PLINK ioctl() command when a STREAM was connected downstream
744 from the multiplexing driver. If arg is MUXID_ALL, then all
745 STREAMs which are persistent connections to fildes shall be dis‐
746 connected. As in I_PLINK, this command requires the multiplexing
747 driver to acknowledge the request.
748 The ioctl() function with the I_PUNLINK command shall fail if:
750 ENXIO
752 Hangup received on fildes.
753 ETIME
755 Timeout before acknowledgement message was received at STREAM
756 head.
757 EAGAIN or ENOSR
759 Unable to allocate buffers for the acknowledgement message.
761 EINVAL
763 Invalid multiplexer ID number.
764 An I_PUNLINK can also fail while waiting for the multiplexing driver to
767 acknowledge the request if a message indicating an error or a hangup is
768 received at the STREAM head of fildes. In addition, an error code can
769 be returned in the positive or negative acknowledgement message. For
770 these cases, I_PUNLINK shall fail with errno set to the value in the
771 message.
772
775 Upon successful completion, ioctl() shall return a value other than -1
776 that depends upon the STREAMS device control function. Otherwise, it
777 shall return -1 and set errno to indicate the error.
778
780 Under the following general conditions, ioctl() shall fail if:
781 EBADF The fildes argument is not a valid open file descriptor.
783 EINTR A signal was caught during the ioctl() operation.
785 EINVAL The STREAM or multiplexer referenced by fildes is linked
787 (directly or indirectly) downstream from a multiplexer.
788 If an underlying device driver detects an error, then ioctl() shall
791 fail if:
792 EINVAL The request or arg argument is not valid for this device.
794 EIO Some physical I/O error has occurred.
796 ENOTTY The fildes argument is not associated with a STREAMS device that
798 accepts control functions.
799 ENXIO The request and arg arguments are valid for this device driver,
801 but the service requested cannot be performed on this particular
802 sub-device.
803 ENODEV The fildes argument refers to a valid STREAMS device, but the
805 corresponding device driver does not support the ioctl() func‐
806 tion.
807 If a STREAM is connected downstream from a multiplexer, any ioctl()
810 command except I_UNLINK and I_PUNLINK shall set errno to [EINVAL].
811 The following sections are informative.
813
815 None.
816
818 The implementation-defined timeout interval for STREAMS has histori‐
819 cally been 15 seconds.
820
822 None.
823
825 None.
826
828 STREAMS , close() , fcntl() , getmsg() , open() , pipe() , poll() ,
829 putmsg() , read() , sigaction() , write() , the Base Definitions volume
830 of IEEE Std 1003.1-2001, <stropts.h>
831
833 Portions of this text are reprinted and reproduced in electronic form
834 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
835 -- Portable Operating System Interface (POSIX), The Open Group Base
836 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
837 Electrical and Electronics Engineers, Inc and The Open Group. In the
838 event of any discrepancy between this version and the original IEEE and
839 The Open Group Standard, the original IEEE and The Open Group Standard
840 is the referee document. The original Standard can be obtained online
841 at http://www.opengroup.org/unix/online.html .
842IEEE/The Open Group 2003 IOCTL(P)