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
13 ioctl — control a STREAMS device (STREAMS)
14
16 #include <stropts.h>
17 int ioctl(int fildes, int request, ... /* arg */);
19
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
44 top of the current STREAM, just below the STREAM head. It
45 then calls the open() function of the newly-pushed module.
46 The ioctl() function with the I_PUSH command shall fail if:
48 EINVAL Invalid module name.
50 ENXIO Open function of new module failed.
52 ENXIO Hangup received on fildes.
54 I_POP Removes the module just below the STREAM head of the STREAM
56 pointed to by fildes. The arg argument should be 0 in an
57 I_POP request.
58 The ioctl() function with the I_POP command shall fail if:
60 EINVAL No module present in the STREAM.
62 ENXIO Hangup received on fildes.
64 I_LOOK Retrieves the name of the module just below the STREAM head
66 of the STREAM pointed to by fildes, and places it in a
67 character string pointed to by arg. The buffer pointed to
68 by arg should be at least FMNAMESZ+1 bytes long, where
69 FMNAMESZ is defined in <stropts.h>.
70 The ioctl() function with the I_LOOK command shall fail if:
72 EINVAL No module present in the STREAM.
74 I_FLUSH Flushes read and/or write queues, depending on the value of
76 arg. Valid arg values are:
77 FLUSHR Flush all read queues.
79 FLUSHW Flush all write queues.
81 FLUSHRW Flush all read and all write queues.
83 The ioctl() function with the I_FLUSH command shall fail
85 if:
86 EINVAL Invalid arg value.
88 EAGAIN or ENOSR
90 Unable to allocate buffers for flush message.
91 ENXIO Hangup received on fildes.
93 I_FLUSHBAND Flushes a particular band of messages. The arg argument
95 points to a bandinfo structure. The bi_flag member may be
96 one of FLUSHR, FLUSHW, or FLUSHRW as described above. The
97 bi_pri member determines the priority band to be flushed.
98 I_SETSIG Requests that the STREAMS implementation send the SIGPOLL
100 signal to the calling process when a particular event has
101 occurred on the STREAM associated with fildes. I_SETSIG
102 supports an asynchronous processing capability in STREAMS.
103 The value of arg is a bitmask that specifies the events for
104 which the process should be signaled. It is the bitwise-
105 inclusive OR of any combination of the following constants:
106 S_RDNORM A normal (priority band set to 0) message has
108 arrived at the head of a STREAM head read
109 queue. A signal shall be generated even if the
110 message is of zero length.
111 S_RDBAND A message with a non-zero priority band has
113 arrived at the head of a STREAM head read
114 queue. A signal shall be generated even if the
115 message is of zero length.
116 S_INPUT A message, other than a high-priority message,
118 has arrived at the head of a STREAM head read
119 queue. A signal shall be generated even if the
120 message is of zero length.
121 S_HIPRI A high-priority message is present on a STREAM
123 head read queue. A signal shall be generated
124 even if the message is of zero length.
125 S_OUTPUT The write queue for normal data (priority band
127 0) just below the STREAM head is no longer
128 full. This notifies the process that there is
129 room on the queue for sending (or writing) nor‐
130 mal data downstream.
131 S_WRNORM Equivalent to S_OUTPUT.
133 S_WRBAND The write queue for a non-zero priority band
135 just below the STREAM head is no longer full.
136 This notifies the process that there is room on
137 the queue for sending (or writing) priority
138 data downstream.
139 S_MSG A STREAMS signal message that contains the SIG‐
141 POLL signal has reached the front of the STREAM
142 head read queue.
143 S_ERROR Notification of an error condition has reached
145 the STREAM head.
146 S_HANGUP Notification of a hangup has reached the STREAM
148 head.
149 S_BANDURG When used in conjunction with S_RDBAND, SIGURG
151 is generated instead of SIGPOLL when a priority
152 message reaches the front of the STREAM head
153 read queue.
154 If arg is 0, the calling process shall be unregistered and
156 shall not receive further SIGPOLL signals for the stream
157 associated with fildes.
158 Processes that wish to receive SIGPOLL signals shall ensure
160 that they explicitly register to receive them using I_SET‐
161 SIG. If several processes register to receive this signal
162 for the same event on the same STREAM, each process shall
163 be signaled when the event occurs.
164 The ioctl() function with the I_SETSIG command shall fail
166 if:
167 EINVAL The value of arg is invalid.
169 EINVAL The value of arg is 0 and the calling process is not
171 registered to receive the SIGPOLL signal.
172 EAGAIN There were insufficient resources to store the sig‐
174 nal request.
175 I_GETSIG Returns the events for which the calling process is cur‐
177 rently registered to be sent a SIGPOLL signal. The events
178 are returned as a bitmask in an int pointed to by arg,
179 where the events are those specified in the description of
180 I_SETSIG above.
181 The ioctl() function with the I_GETSIG command shall fail
183 if:
184 EINVAL Process is not registered to receive the SIGPOLL
186 signal.
187 I_FIND Compares the names of all modules currently present in the
189 STREAM to the name pointed to by arg, and returns 1 if the
190 named module is present in the STREAM, or returns 0 if the
191 named module is not present.
192 The ioctl() function with the I_FIND command shall fail if:
194 EINVAL arg does not contain a valid module name.
196 I_PEEK Retrieves the information in the first message on the
198 STREAM head read queue without taking the message off the
199 queue. It is analogous to getmsg() except that this command
200 does not remove the message from the queue. The arg argu‐
201 ment points to a strpeek structure.
202 The application shall ensure that the maxlen member in the
204 ctlbuf and databuf strbuf structures is set to the number
205 of bytes of control information and/or data information,
206 respectively, to retrieve. The flags member may be marked
207 RS_HIPRI or 0, as described by getmsg(). If the process
208 sets flags to RS_HIPRI, for example, I_PEEK shall only look
209 for a high-priority message on the STREAM head read queue.
210 I_PEEK returns 1 if a message was retrieved, and returns 0
212 if no message was found on the STREAM head read queue, or
213 if the RS_HIPRI flag was set in flags and a high-priority
214 message was not present on the STREAM head read queue. It
215 does not wait for a message to arrive. On return, ctlbuf
216 specifies information in the control buffer, databuf speci‐
217 fies information in the data buffer, and flags contains the
218 value RS_HIPRI or 0.
219 I_SRDOPT Sets the read mode using the value of the argument arg.
221 Read modes are described in read(). Valid arg flags are:
222 RNORM Byte-stream mode, the default.
224 RMSGD Message-discard mode.
226 RMSGN Message-nondiscard mode.
228 The bitwise-inclusive OR of RMSGD and RMSGN shall return
230 [EINVAL]. The bitwise-inclusive OR of RNORM and either
231 RMSGD or RMSGN shall result in the other flag overriding
232 RNORM which is the default.
233 In addition, treatment of control messages by the STREAM
235 head may be changed by setting any of the following flags
236 in arg:
237 RPROTNORM Fail read() with [EBADMSG] if a message con‐
239 taining a control part is at the front of the
240 STREAM head read queue.
241 RPROTDAT Deliver the control part of a message as data
243 when a process issues a read().
244 RPROTDIS Discard the control part of a message, deliver‐
246 ing any data portion, when a process issues a
247 read().
248 The ioctl() function with the I_SRDOPT command shall fail
250 if:
251 EINVAL The arg argument is not valid.
253 I_GRDOPT Returns the current read mode setting, as described above,
255 in an int pointed to by the argument arg. Read modes are
256 described in read().
257 I_NREAD Counts the number of data bytes in the data part of the
259 first message on the STREAM head read queue and places this
260 value in the int pointed to by arg. The return value for
261 the command shall be the number of messages on the STREAM
262 head read queue. For example, if 0 is returned in arg, but
263 the ioctl() return value is greater than 0, this indicates
264 that a zero-length message is next on the queue.
265 I_FDINSERT Creates a message from specified buffer(s), adds informa‐
267 tion about another STREAM, and sends the message down‐
268 stream. The message contains a control part and an optional
269 data part. The data and control parts to be sent are dis‐
270 tinguished by placement in separate buffers, as described
271 below. The arg argument points to a strfdinsert structure.
272 The application shall ensure that the len member in the
274 ctlbuf strbuf structure is set to the size of a t_uscalar_t
275 plus the number of bytes of control information to be sent
276 with the message. The fildes member specifies the file
277 descriptor of the other STREAM, and the offset member,
278 which must be suitably aligned for use as a t_uscalar_t,
279 specifies the offset from the start of the control buffer
280 where I_FDINSERT shall store a t_uscalar_t whose interpre‐
281 tation is specific to the STREAM end. The application shall
282 ensure that the len member in the databuf strbuf structure
283 is set to the number of bytes of data information to be
284 sent with the message, or to 0 if no data part is to be
285 sent.
286 The flags member specifies the type of message to be cre‐
288 ated. A normal message is created if flags is set to 0, and
289 a high-priority message is created if flags is set to
290 RS_HIPRI. For non-priority messages, I_FDINSERT shall block
291 if the STREAM write queue is full due to internal flow con‐
292 trol conditions. For priority messages, I_FDINSERT does
293 not block on this condition. For non-priority messages,
294 I_FDINSERT does not block when the write queue is full and
295 O_NONBLOCK is set. Instead, it fails and sets errno to
296 [EAGAIN].
297 I_FDINSERT also blocks, unless prevented by lack of inter‐
299 nal resources, waiting for the availability of message
300 blocks in the STREAM, regardless of priority or whether
301 O_NONBLOCK has been specified. No partial message is sent.
302 The ioctl() function with the I_FDINSERT command shall fail
304 if:
305 EAGAIN A non-priority message is specified, the O_NONBLOCK
307 flag is set, and the STREAM write queue is full due
308 to internal flow control conditions.
309 EAGAIN or ENOSR
311 Buffers cannot be allocated for the message that is
312 to be created.
313 EINVAL One of the following:
315 -- The fildes member of the strfdinsert struc‐
317 ture is not a valid, open STREAM file
318 descriptor.
319 -- The size of a t_uscalar_t plus offset is
321 greater than the len member for the buffer
322 specified through ctlbuf.
323 -- The offset member does not specify a prop‐
325 erly-aligned location in the data buffer.
326 -- An undefined value is stored in flags.
328 ENXIO Hangup received on the STREAM identified by either
330 the fildes argument or the fildes member of the
331 strfdinsert structure.
332 ERANGE The len member for the buffer specified through
334 databuf does not fall within the range specified by
335 the maximum and minimum packet sizes of the topmost
336 STREAM module; or the len member for the buffer
337 specified through databuf is larger than the maximum
338 configured size of the data part of a message; or
339 the len member for the buffer specified through ctl‐
340 buf is larger than the maximum configured size of
341 the control part of a message.
342 I_STR Constructs an internal STREAMS ioctl() message from the
344 data pointed to by arg, and sends that message downstream.
345 This mechanism is provided to send ioctl() requests to
347 downstream modules and drivers. It allows information to be
348 sent with ioctl(), and returns to the process any informa‐
349 tion sent upstream by the downstream recipient. I_STR shall
350 block until the system responds with either a positive or
351 negative acknowledgement message, or until the request
352 times out after some period of time. If the request times
353 out, it shall fail with errno set to [ETIME].
354 At most, one I_STR can be active on a STREAM. Further I_STR
356 calls shall block until the active I_STR completes at the
357 STREAM head. The default timeout interval for these
358 requests is 15 seconds. The O_NONBLOCK flag has no effect
359 on this call.
360 To send requests downstream, the application shall ensure
362 that arg points to a strioctl structure.
363 The ic_cmd member is the internal ioctl() command intended
365 for a downstream module or driver and ic_timout is the num‐
366 ber of seconds (−1=infinite, 0=use implementation-defined
367 timeout interval, >0=as specified) an I_STR request shall
368 wait for acknowledgement before timing out. ic_len is the
369 number of bytes in the data argument, and ic_dp is a
370 pointer to the data argument. The ic_len member has two
371 uses: on input, it contains the length of the data argument
372 passed in, and on return from the command, it contains the
373 number of bytes being returned to the process (the buffer
374 pointed to by ic_dp should be large enough to contain the
375 maximum amount of data that any module or the driver in the
376 STREAM can return).
377 The STREAM head shall convert the information pointed to by
379 the strioctl structure to an internal ioctl() command mes‐
380 sage and send it downstream.
381 The ioctl() function with the I_STR command shall fail if:
383 EAGAIN or ENOSR
385 Unable to allocate buffers for the ioctl() message.
386 EINVAL The ic_len member is less than 0 or larger than the
388 maximum configured size of the data part of a mes‐
389 sage, or ic_timout is less than −1.
390 ENXIO Hangup received on fildes.
392 ETIME A downstream ioctl() timed out before acknowledge‐
394 ment was received.
395 An I_STR can also fail while waiting for an acknowledgement
397 if a message indicating an error or a hangup is received at
398 the STREAM head. In addition, an error code can be
399 returned in the positive or negative acknowledgement mes‐
400 sage, in the event the ioctl() command sent downstream
401 fails. For these cases, I_STR shall fail with errno set to
402 the value in the message.
403 I_SWROPT Sets the write mode using the value of the argument arg.
405 Valid bit settings for arg are:
406 SNDZERO Send a zero-length message downstream when a
408 write() of 0 bytes occurs. To not send a zero-
409 length message when a write() of 0 bytes
410 occurs, the application shall ensure that this
411 bit is not set in arg (for example, arg would
412 be set to 0).
413 The ioctl() function with the I_SWROPT command shall fail
415 if:
416 EINVAL arg is not the above value.
418 I_GWROPT Returns the current write mode setting, as described above,
420 in the int that is pointed to by the argument arg.
421 I_SENDFD Creates a new reference to the open file description asso‐
423 ciated with the file descriptor arg, and writes a message
424 on the STREAMS-based pipe fildes containing this reference,
425 together with the user ID and group ID of the calling
426 process.
427 The ioctl() function with the I_SENDFD command shall fail
429 if:
430 EAGAIN The sending STREAM is unable to allocate a message
432 block to contain the file pointer; or the read queue
433 of the receiving STREAM head is full and cannot
434 accept the message sent by I_SENDFD.
435 EBADF The arg argument is not a valid, open file descrip‐
437 tor.
438 EINVAL The fildes argument is not connected to a STREAM
440 pipe.
441 ENXIO Hangup received on fildes.
443 The ioctl() function with the I_SENDFD command may fail if:
445 EINVAL The arg argument is equal to the fildes argument.
447 I_RECVFD Retrieves the reference to an open file description from a
449 message written to a STREAMS-based pipe using the I_SENDFD
450 command, and allocates a new file descriptor in the calling
451 process that refers to this open file description. The arg
452 argument is a pointer to a strrecvfd data structure as
453 defined in <stropts.h>.
454 The fd member is a file descriptor. The uid and gid members
456 are the effective user ID and effective group ID, respec‐
457 tively, of the sending process.
458 If O_NONBLOCK is not set, I_RECVFD shall block until a mes‐
460 sage is present at the STREAM head. If O_NONBLOCK is set,
461 I_RECVFD shall fail with errno set to [EAGAIN] if no mes‐
462 sage is present at the STREAM head.
463 If the message at the STREAM head is a message sent by an
465 I_SENDFD, a new file descriptor shall be allocated for the
466 open file descriptor referenced in the message. The new
467 file descriptor is placed in the fd member of the strrecvfd
468 structure pointed to by arg.
469 The ioctl() function with the I_RECVFD command shall fail
471 if:
472 EAGAIN A message is not present at the STREAM head read
474 queue and the O_NONBLOCK flag is set.
475 EBADMSG
477 The message at the STREAM head read queue is not a
478 message containing a passed file descriptor.
479 EMFILE All file descriptors available to the process are
481 currently open.
482 ENXIO Hangup received on fildes.
484 I_LIST Allows the process to list all the module names on the
486 STREAM, up to and including the topmost driver name. If arg
487 is a null pointer, the return value shall be the number of
488 modules, including the driver, that are on the STREAM
489 pointed to by fildes. This lets the process allocate
490 enough space for the module names. Otherwise, it should
491 point to a str_list structure.
492 The sl_nmods member indicates the number of entries the
494 process has allocated in the array. Upon return, the
495 sl_modlist member of the str_list structure shall contain
496 the list of module names, and the number of entries that
497 have been filled into the sl_modlist array is found in the
498 sl_nmods member (the number includes the number of modules
499 including the driver). The return value from ioctl() shall
500 be 0. The entries are filled in starting at the top of the
501 STREAM and continuing downstream until either the end of
502 the STREAM is reached, or the number of requested modules
503 (sl_nmods) is satisfied.
504 The ioctl() function with the I_LIST command shall fail if:
506 EINVAL The sl_nmods member is less than 1.
508 EAGAIN or ENOSR
510 Unable to allocate buffers.
511 I_ATMARK Allows the process to see if the message at the head of the
513 STREAM head read queue is marked by some module downstream.
514 The arg argument determines how the checking is done when
515 there may be multiple marked messages on the STREAM head
516 read queue. It may take on the following values:
517 ANYMARK Check if the message is marked.
519 LASTMARK Check if the message is the last one marked on
521 the queue.
522 The bitwise-inclusive OR of the flags ANYMARK and LASTMARK
524 is permitted.
525 The return value shall be 1 if the mark condition is satis‐
527 fied; otherwise, the value shall be 0.
528 The ioctl() function with the I_ATMARK command shall fail
530 if:
531 EINVAL Invalid arg value.
533 I_CKBAND Checks if the message of a given priority band exists on
535 the STREAM head read queue. This shall return 1 if a mes‐
536 sage of the given priority exists, 0 if no such message
537 exists, or −1 on error. arg should be of type int.
538 The ioctl() function with the I_CKBAND command shall fail
540 if:
541 EINVAL Invalid arg value.
543 I_GETBAND Returns the priority band of the first message on the
545 STREAM head read queue in the integer referenced by arg.
546 The ioctl() function with the I_GETBAND command shall fail
548 if:
549 ENODATA
551 No message on the STREAM head read queue.
552 I_CANPUT Checks if a certain band is writable. arg is set to the
554 priority band in question. The return value shall be 0 if
555 the band is flow-controlled, 1 if the band is writable, or
556 −1 on error.
557 The ioctl() function with the I_CANPUT command shall fail
559 if:
560 EINVAL Invalid arg value.
562 I_SETCLTIME This request allows the process to set the time the STREAM
564 head shall delay when a STREAM is closing and there is data
565 on the write queues. Before closing each module or driver,
566 if there is data on its write queue, the STREAM head shall
567 delay for the specified amount of time to allow the data to
568 drain. If, after the delay, data is still present, it shall
569 be flushed. The arg argument is a pointer to an integer
570 specifying the number of milliseconds to delay, rounded up
571 to the nearest valid value. If I_SETCLTIME is not performed
572 on a STREAM, an implementation-defined default timeout
573 interval is used.
574 The ioctl() function with the I_SETCLTIME command shall
576 fail if:
577 EINVAL Invalid arg value.
579 I_GETCLTIME Returns the close time delay in the integer pointed to by
581 arg.
582 Multiplexed STREAMS Configurations
584 The following commands are used for connecting and disconnecting multi‐
585 plexed STREAMS configurations. These commands use an implementation-
586 defined default timeout interval.
587 I_LINK Connects two STREAMs, where fildes is the file descriptor
589 of the STREAM connected to the multiplexing driver, and arg
590 is the file descriptor of the STREAM connected to another
591 driver. The STREAM designated by arg is connected below the
592 multiplexing driver. I_LINK requires the multiplexing
593 driver to send an acknowledgement message to the STREAM
594 head regarding the connection. This call shall return a
595 multiplexer ID number (an identifier used to disconnect the
596 multiplexer; see I_UNLINK) on success, and −1 on failure.
597 The ioctl() function with the I_LINK command shall fail if:
599 ENXIO Hangup received on fildes.
601 ETIME Timeout before acknowledgement message was received
603 at STREAM head.
604 EAGAIN or ENOSR
606 Unable to allocate STREAMS storage to perform the
607 I_LINK.
608 EBADF The arg argument is not a valid, open file descrip‐
610 tor.
611 EINVAL The fildes argument does not support multiplexing;
613 or arg is not a STREAM or is already connected down‐
614 stream from a multiplexer; or the specified I_LINK
615 operation would connect the STREAM head in more than
616 one place in the multiplexed STREAM.
617 An I_LINK can also fail while waiting for the multiplexing
619 driver to acknowledge the request, if a message indicating
620 an error or a hangup is received at the STREAM head of
621 fildes. In addition, an error code can be returned in the
622 positive or negative acknowledgement message. For these
623 cases, I_LINK fails with errno set to the value in the mes‐
624 sage.
625 I_UNLINK Disconnects the two STREAMs specified by fildes and arg.
627 fildes is the file descriptor of the STREAM connected to
628 the multiplexing driver. The arg argument is the multi‐
629 plexer ID number that was returned by the I_LINK ioctl()
630 command when a STREAM was connected downstream from the
631 multiplexing driver. If arg is MUXID_ALL, then all STREAMs
632 that were connected to fildes shall be disconnected. As in
633 I_LINK, this command requires acknowledgement.
634 The ioctl() function with the I_UNLINK command shall fail
636 if:
637 ENXIO Hangup received on fildes.
639 ETIME Timeout before acknowledgement message was received
641 at STREAM head.
642 EAGAIN or ENOSR
644 Unable to allocate buffers for the acknowledgement
645 message.
646 EINVAL Invalid multiplexer ID number.
648 An I_UNLINK can also fail while waiting for the multiplex‐
650 ing driver to acknowledge the request if a message indicat‐
651 ing an error or a hangup is received at the STREAM head of
652 fildes. In addition, an error code can be returned in the
653 positive or negative acknowledgement message. For these
654 cases, I_UNLINK shall fail with errno set to the value in
655 the message.
656 I_PLINK Creates a persistent connection between two STREAMs, where
658 fildes is the file descriptor of the STREAM connected to
659 the multiplexing driver, and arg is the file descriptor of
660 the STREAM connected to another driver. This call shall
661 create a persistent connection which can exist even if the
662 file descriptor fildes associated with the upper STREAM to
663 the multiplexing driver is closed. The STREAM designated
664 by arg gets connected via a persistent connection below the
665 multiplexing driver. I_PLINK requires the multiplexing
666 driver to send an acknowledgement message to the STREAM
667 head. This call shall return a multiplexer ID number (an
668 identifier that may be used to disconnect the multiplexer;
669 see I_PUNLINK) on success, and −1 on failure.
670 The ioctl() function with the I_PLINK command shall fail
672 if:
673 ENXIO Hangup received on fildes.
675 ETIME Timeout before acknowledgement message was received
677 at STREAM head.
678 EAGAIN or ENOSR
680 Unable to allocate STREAMS storage to perform the
681 I_PLINK.
682 EBADF The arg argument is not a valid, open file descrip‐
684 tor.
685 EINVAL The fildes argument does not support multiplexing;
687 or arg is not a STREAM or is already connected down‐
688 stream from a multiplexer; or the specified I_PLINK
689 operation would connect the STREAM head in more than
690 one place in the multiplexed STREAM.
691 An I_PLINK can also fail while waiting for the multiplexing
693 driver to acknowledge the request, if a message indicating
694 an error or a hangup is received at the STREAM head of
695 fildes. In addition, an error code can be returned in the
696 positive or negative acknowledgement message. For these
697 cases, I_PLINK shall fail with errno set to the value in
698 the message.
699 I_PUNLINK Disconnects the two STREAMs specified by fildes and arg
701 from a persistent connection. The fildes argument is the
702 file descriptor of the STREAM connected to the multiplexing
703 driver. The arg argument is the multiplexer ID number that
704 was returned by the I_PLINK ioctl() command when a STREAM
705 was connected downstream from the multiplexing driver. If
706 arg is MUXID_ALL, then all STREAMs which are persistent
707 connections to fildes shall be disconnected. As in I_PLINK,
708 this command requires the multiplexing driver to acknowl‐
709 edge the request.
710 The ioctl() function with the I_PUNLINK command shall fail
712 if:
713 ENXIO Hangup received on fildes.
715 ETIME Timeout before acknowledgement message was received
717 at STREAM head.
718 EAGAIN or ENOSR
720 Unable to allocate buffers for the acknowledgement
721 message.
722 EINVAL Invalid multiplexer ID number.
724 An I_PUNLINK can also fail while waiting for the multiplex‐
726 ing driver to acknowledge the request if a message indicat‐
727 ing an error or a hangup is received at the STREAM head of
728 fildes. In addition, an error code can be returned in the
729 positive or negative acknowledgement message. For these
730 cases, I_PUNLINK shall fail with errno set to the value in
731 the message.
732
734 Upon successful completion, ioctl() shall return a value other than −1
735 that depends upon the STREAMS device control function. Otherwise, it
736 shall return −1 and set errno to indicate the error.
737
739 Under the following general conditions, ioctl() shall fail if:
740 EBADF The fildes argument is not a valid open file descriptor.
742 EINTR A signal was caught during the ioctl() operation.
744 EINVAL The STREAM or multiplexer referenced by fildes is linked
746 (directly or indirectly) downstream from a multiplexer.
747 If an underlying device driver detects an error, then ioctl() shall
749 fail if:
750 EINVAL The request or arg argument is not valid for this device.
752 EIO Some physical I/O error has occurred.
754 ENOTTY The file associated with the fildes argument is not a STREAMS
756 device that accepts control functions.
757 ENXIO The request and arg arguments are valid for this device driver,
759 but the service requested cannot be performed on this particular
760 sub-device.
761 ENODEV The fildes argument refers to a valid STREAMS device, but the
763 corresponding device driver does not support the ioctl() func‐
764 tion.
765 If a STREAM is connected downstream from a multiplexer, any ioctl()
767 command except I_UNLINK and I_PUNLINK shall set errno to [EINVAL].
768 The following sections are informative.
770
772 None.
773
775 The implementation-defined timeout interval for STREAMS has histori‐
776 cally been 15 seconds.
777
779 None.
780
782 The ioctl() function may be removed in a future version.
783
785 Section 2.6, STREAMS, close(), fcntl(), getmsg(), open(), pipe(),
786 poll(), putmsg(), read(), sigaction(), write()
787 The Base Definitions volume of POSIX.1‐2008, <stropts.h>
789
791 Portions of this text are reprinted and reproduced in electronic form
792 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
793 -- Portable Operating System Interface (POSIX), The Open Group Base
794 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
795 cal and Electronics Engineers, Inc and The Open Group. (This is
796 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
797 event of any discrepancy between this version and the original IEEE and
798 The Open Group Standard, the original IEEE and The Open Group Standard
799 is the referee document. The original Standard can be obtained online
800 at http://www.unix.org/online.html .
801 Any typographical or formatting errors that appear in this page are
803 most likely to have been introduced during the conversion of the source
804 files to man page format. To report such errors, see https://www.ker‐
805 nel.org/doc/man-pages/reporting_bugs.html .
806IEEE/The Open Group 2013 IOCTL(3P)