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
20 The ioctl() function shall perform a variety of control functions on
21 STREAMS devices. For non-STREAMS devices, the functions performed by
22 this call are unspecified. The request argument and an optional third
23 argument (with varying type) shall be passed to and interpreted by the
24 appropriate part of the STREAM associated with fildes.
25 The fildes argument is an open file descriptor that refers to a device.
27 The request argument selects the control function to be performed and
29 shall depend on the STREAMS device being addressed.
30 The arg argument represents additional information that is needed by
32 this specific STREAMS device to perform the requested function. The
33 type of arg depends upon the particular control request, but it shall
34 be either an integer or a pointer to a device-specific data structure.
35 The ioctl() commands applicable to STREAMS, their arguments, and error
37 conditions that apply to each individual command are described below.
38 The following ioctl() commands, with error values indicated, are appli‐
40 cable to all STREAMS files:
41 I_PUSH Pushes the module whose name is pointed to by arg onto the
43 top of the current STREAM, just below the STREAM head. It
44 then calls the open() function of the newly-pushed module.
45 The ioctl() function with the I_PUSH command shall fail if:
47 EINVAL Invalid module name.
49 ENXIO Open function of new module failed.
51 ENXIO Hangup received on fildes.
53 I_POP Removes the module just below the STREAM head of the STREAM
55 pointed to by fildes. The arg argument should be 0 in an
56 I_POP request.
57 The ioctl() function with the I_POP command shall fail if:
59 EINVAL No module present in the STREAM.
61 ENXIO Hangup received on fildes.
63 I_LOOK Retrieves the name of the module just below the STREAM head
65 of the STREAM pointed to by fildes, and places it in a
66 character string pointed to by arg. The buffer pointed to
67 by arg should be at least FMNAMESZ+1 bytes long, where
68 FMNAMESZ is defined in <stropts.h>.
69 The ioctl() function with the I_LOOK command shall fail if:
71 EINVAL No module present in the STREAM.
73 I_FLUSH Flushes read and/or write queues, depending on the value of
75 arg. Valid arg values are:
76 FLUSHR Flush all read queues.
78 FLUSHW Flush all write queues.
80 FLUSHRW Flush all read and all write queues.
82 The ioctl() function with the I_FLUSH command shall fail
84 if:
85 EINVAL Invalid arg value.
87 EAGAIN or ENOSR
89 Unable to allocate buffers for flush message.
90 ENXIO Hangup received on fildes.
92 I_FLUSHBAND Flushes a particular band of messages. The arg argument
94 points to a bandinfo structure. The bi_flag member may be
95 one of FLUSHR, FLUSHW, or FLUSHRW as described above. The
96 bi_pri member determines the priority band to be flushed.
97 I_SETSIG Requests that the STREAMS implementation send the SIGPOLL
99 signal to the calling process when a particular event has
100 occurred on the STREAM associated with fildes. I_SETSIG
101 supports an asynchronous processing capability in STREAMS.
102 The value of arg is a bitmask that specifies the events for
103 which the process should be signaled. It is the bitwise-
104 inclusive OR of any combination of the following constants:
105 S_RDNORM A normal (priority band set to 0) message has
107 arrived at the head of a STREAM head read
108 queue. A signal shall be generated even if the
109 message is of zero length.
110 S_RDBAND A message with a non-zero priority band has
112 arrived at the head of a STREAM head read
113 queue. A signal shall be generated even if the
114 message is of zero length.
115 S_INPUT A message, other than a high-priority message,
117 has arrived at the head of a STREAM head read
118 queue. A signal shall be generated even if the
119 message is of zero length.
120 S_HIPRI A high-priority message is present on a STREAM
122 head read queue. A signal shall be generated
123 even if the message is of zero length.
124 S_OUTPUT The write queue for normal data (priority band
126 0) just below the STREAM head is no longer
127 full. This notifies the process that there is
128 room on the queue for sending (or writing) nor‐
129 mal data downstream.
130 S_WRNORM Equivalent to S_OUTPUT.
132 S_WRBAND The write queue for a non-zero priority band
134 just below the STREAM head is no longer full.
135 This notifies the process that there is room on
136 the queue for sending (or writing) priority
137 data downstream.
138 S_MSG A STREAMS signal message that contains the SIG‐
140 POLL signal has reached the front of the STREAM
141 head read queue.
142 S_ERROR Notification of an error condition has reached
144 the STREAM head.
145 S_HANGUP Notification of a hangup has reached the STREAM
147 head.
148 S_BANDURG When used in conjunction with S_RDBAND, SIGURG
150 is generated instead of SIGPOLL when a priority
151 message reaches the front of the STREAM head
152 read queue.
153 If arg is 0, the calling process shall be unregistered and
155 shall not receive further SIGPOLL signals for the stream
156 associated with fildes.
157 Processes that wish to receive SIGPOLL signals shall ensure
159 that they explicitly register to receive them using I_SET‐
160 SIG. If several processes register to receive this signal
161 for the same event on the same STREAM, each process shall
162 be signaled when the event occurs.
163 The ioctl() function with the I_SETSIG command shall fail
165 if:
166 EINVAL The value of arg is invalid.
168 EINVAL The value of arg is 0 and the calling process is not
170 registered to receive the SIGPOLL signal.
171 EAGAIN There were insufficient resources to store the sig‐
173 nal request.
174 I_GETSIG Returns the events for which the calling process is cur‐
176 rently registered to be sent a SIGPOLL signal. The events
177 are returned as a bitmask in an int pointed to by arg,
178 where the events are those specified in the description of
179 I_SETSIG above.
180 The ioctl() function with the I_GETSIG command shall fail
182 if:
183 EINVAL Process is not registered to receive the SIGPOLL
185 signal.
186 I_FIND Compares the names of all modules currently present in the
188 STREAM to the name pointed to by arg, and returns 1 if the
189 named module is present in the STREAM, or returns 0 if the
190 named module is not present.
191 The ioctl() function with the I_FIND command shall fail if:
193 EINVAL arg does not contain a valid module name.
195 I_PEEK Retrieves the information in the first message on the
197 STREAM head read queue without taking the message off the
198 queue. It is analogous to getmsg() except that this command
199 does not remove the message from the queue. The arg argu‐
200 ment points to a strpeek structure.
201 The application shall ensure that the maxlen member in the
203 ctlbuf and databuf strbuf structures is set to the number
204 of bytes of control information and/or data information,
205 respectively, to retrieve. The flags member may be marked
206 RS_HIPRI or 0, as described by getmsg(). If the process
207 sets flags to RS_HIPRI, for example, I_PEEK shall only look
208 for a high-priority message on the STREAM head read queue.
209 I_PEEK returns 1 if a message was retrieved, and returns 0
211 if no message was found on the STREAM head read queue, or
212 if the RS_HIPRI flag was set in flags and a high-priority
213 message was not present on the STREAM head read queue. It
214 does not wait for a message to arrive. On return, ctlbuf
215 specifies information in the control buffer, databuf speci‐
216 fies information in the data buffer, and flags contains the
217 value RS_HIPRI or 0.
218 I_SRDOPT Sets the read mode using the value of the argument arg.
220 Read modes are described in read(). Valid arg flags are:
221 RNORM Byte-stream mode, the default.
223 RMSGD Message-discard mode.
225 RMSGN Message-nondiscard mode.
227 The bitwise-inclusive OR of RMSGD and RMSGN shall return
229 [EINVAL]. The bitwise-inclusive OR of RNORM and either
230 RMSGD or RMSGN shall result in the other flag overriding
231 RNORM which is the default.
232 In addition, treatment of control messages by the STREAM
234 head may be changed by setting any of the following flags
235 in arg:
236 RPROTNORM Fail read() with [EBADMSG] if a message con‐
238 taining a control part is at the front of the
239 STREAM head read queue.
240 RPROTDAT Deliver the control part of a message as data
242 when a process issues a read().
243 RPROTDIS Discard the control part of a message, deliver‐
245 ing any data portion, when a process issues a
246 read().
247 The ioctl() function with the I_SRDOPT command shall fail
249 if:
250 EINVAL The arg argument is not valid.
252 I_GRDOPT Returns the current read mode setting, as described above,
254 in an int pointed to by the argument arg. Read modes are
255 described in read().
256 I_NREAD Counts the number of data bytes in the data part of the
258 first message on the STREAM head read queue and places this
259 value in the int pointed to by arg. The return value for
260 the command shall be the number of messages on the STREAM
261 head read queue. For example, if 0 is returned in arg, but
262 the ioctl() return value is greater than 0, this indicates
263 that a zero-length message is next on the queue.
264 I_FDINSERT Creates a message from specified buffer(s), adds informa‐
266 tion about another STREAM, and sends the message down‐
267 stream. The message contains a control part and an optional
268 data part. The data and control parts to be sent are dis‐
269 tinguished by placement in separate buffers, as described
270 below. The arg argument points to a strfdinsert structure.
271 The application shall ensure that the len member in the
273 ctlbuf strbuf structure is set to the size of a t_uscalar_t
274 plus the number of bytes of control information to be sent
275 with the message. The fildes member specifies the file
276 descriptor of the other STREAM, and the offset member,
277 which must be suitably aligned for use as a t_uscalar_t,
278 specifies the offset from the start of the control buffer
279 where I_FDINSERT shall store a t_uscalar_t whose interpre‐
280 tation is specific to the STREAM end. The application shall
281 ensure that the len member in the databuf strbuf structure
282 is set to the number of bytes of data information to be
283 sent with the message, or to 0 if no data part is to be
284 sent.
285 The flags member specifies the type of message to be cre‐
287 ated. A normal message is created if flags is set to 0, and
288 a high-priority message is created if flags is set to
289 RS_HIPRI. For non-priority messages, I_FDINSERT shall block
290 if the STREAM write queue is full due to internal flow con‐
291 trol conditions. For priority messages, I_FDINSERT does
292 not block on this condition. For non-priority messages,
293 I_FDINSERT does not block when the write queue is full and
294 O_NONBLOCK is set. Instead, it fails and sets errno to
295 [EAGAIN].
296 I_FDINSERT also blocks, unless prevented by lack of inter‐
298 nal resources, waiting for the availability of message
299 blocks in the STREAM, regardless of priority or whether
300 O_NONBLOCK has been specified. No partial message is sent.
301 The ioctl() function with the I_FDINSERT command shall fail
303 if:
304 EAGAIN A non-priority message is specified, the O_NONBLOCK
306 flag is set, and the STREAM write queue is full due
307 to internal flow control conditions.
308 EAGAIN or ENOSR
310 Buffers cannot be allocated for the message that is
311 to be created.
312 EINVAL One of the following:
314 -- The fildes member of the strfdinsert struc‐
316 ture is not a valid, open STREAM file
317 descriptor.
318 -- The size of a t_uscalar_t plus offset is
320 greater than the len member for the buffer
321 specified through ctlbuf.
322 -- The offset member does not specify a prop‐
324 erly-aligned location in the data buffer.
325 -- An undefined value is stored in flags.
327 ENXIO Hangup received on the STREAM identified by either
329 the fildes argument or the fildes member of the
330 strfdinsert structure.
331 ERANGE The len member for the buffer specified through
333 databuf does not fall within the range specified by
334 the maximum and minimum packet sizes of the topmost
335 STREAM module; or the len member for the buffer
336 specified through databuf is larger than the maximum
337 configured size of the data part of a message; or
338 the len member for the buffer specified through ctl‐
339 buf is larger than the maximum configured size of
340 the control part of a message.
341 I_STR Constructs an internal STREAMS ioctl() message from the
343 data pointed to by arg, and sends that message downstream.
344 This mechanism is provided to send ioctl() requests to
346 downstream modules and drivers. It allows information to be
347 sent with ioctl(), and returns to the process any informa‐
348 tion sent upstream by the downstream recipient. I_STR shall
349 block until the system responds with either a positive or
350 negative acknowledgement message, or until the request
351 times out after some period of time. If the request times
352 out, it shall fail with errno set to [ETIME].
353 At most, one I_STR can be active on a STREAM. Further I_STR
355 calls shall block until the active I_STR completes at the
356 STREAM head. The default timeout interval for these
357 requests is 15 seconds. The O_NONBLOCK flag has no effect
358 on this call.
359 To send requests downstream, the application shall ensure
361 that arg points to a strioctl structure.
362 The ic_cmd member is the internal ioctl() command intended
364 for a downstream module or driver and ic_timout is the num‐
365 ber of seconds (-1=infinite, 0=use implementation-defined
366 timeout interval, >0=as specified) an I_STR request shall
367 wait for acknowledgement before timing out. ic_len is the
368 number of bytes in the data argument, and ic_dp is a
369 pointer to the data argument. The ic_len member has two
370 uses: on input, it contains the length of the data argument
371 passed in, and on return from the command, it contains the
372 number of bytes being returned to the process (the buffer
373 pointed to by ic_dp should be large enough to contain the
374 maximum amount of data that any module or the driver in the
375 STREAM can return).
376 The STREAM head shall convert the information pointed to by
378 the strioctl structure to an internal ioctl() command mes‐
379 sage and send it downstream.
380 The ioctl() function with the I_STR command shall fail if:
382 EAGAIN or ENOSR
384 Unable to allocate buffers for the ioctl() message.
385 EINVAL The ic_len member is less than 0 or larger than the
387 maximum configured size of the data part of a mes‐
388 sage, or ic_timout is less than -1.
389 ENXIO Hangup received on fildes.
391 ETIME A downstream ioctl() timed out before acknowledge‐
393 ment was received.
394 An I_STR can also fail while waiting for an acknowledgement
396 if a message indicating an error or a hangup is received at
397 the STREAM head. In addition, an error code can be
398 returned in the positive or negative acknowledgement mes‐
399 sage, in the event the ioctl() command sent downstream
400 fails. For these cases, I_STR shall fail with errno set to
401 the value in the message.
402 I_SWROPT Sets the write mode using the value of the argument arg.
404 Valid bit settings for arg are:
405 SNDZERO Send a zero-length message downstream when a
407 write() of 0 bytes occurs. To not send a zero-
408 length message when a write() of 0 bytes
409 occurs, the application shall ensure that this
410 bit is not set in arg (for example, arg would
411 be set to 0).
412 The ioctl() function with the I_SWROPT command shall fail
414 if:
415 EINVAL arg is not the above value.
417 I_GWROPT Returns the current write mode setting, as described above,
419 in the int that is pointed to by the argument arg.
420 I_SENDFD Creates a new reference to the open file description asso‐
422 ciated with the file descriptor arg, and writes a message
423 on the STREAMS-based pipe fildes containing this reference,
424 together with the user ID and group ID of the calling
425 process.
426 The ioctl() function with the I_SENDFD command shall fail
428 if:
429 EAGAIN The sending STREAM is unable to allocate a message
431 block to contain the file pointer; or the read queue
432 of the receiving STREAM head is full and cannot
433 accept the message sent by I_SENDFD.
434 EBADF The arg argument is not a valid, open file descrip‐
436 tor.
437 EINVAL The fildes argument is not connected to a STREAM
439 pipe.
440 ENXIO Hangup received on fildes.
442 The ioctl() function with the I_SENDFD command may fail if:
444 EINVAL The arg argument is equal to the fildes argument.
446 I_RECVFD Retrieves the reference to an open file description from a
448 message written to a STREAMS-based pipe using the I_SENDFD
449 command, and allocates a new file descriptor in the calling
450 process that refers to this open file description. The arg
451 argument is a pointer to a strrecvfd data structure as
452 defined in <stropts.h>.
453 The fd member is a file descriptor. The uid and gid members
455 are the effective user ID and effective group ID, respec‐
456 tively, of the sending process.
457 If O_NONBLOCK is not set, I_RECVFD shall block until a mes‐
459 sage is present at the STREAM head. If O_NONBLOCK is set,
460 I_RECVFD shall fail with errno set to [EAGAIN] if no mes‐
461 sage is present at the STREAM head.
462 If the message at the STREAM head is a message sent by an
464 I_SENDFD, a new file descriptor shall be allocated for the
465 open file descriptor referenced in the message. The new
466 file descriptor is placed in the fd member of the strrecvfd
467 structure pointed to by arg.
468 The ioctl() function with the I_RECVFD command shall fail
470 if:
471 EAGAIN A message is not present at the STREAM head read
473 queue and the O_NONBLOCK flag is set.
474 EBADMSG
476 The message at the STREAM head read queue is not a
477 message containing a passed file descriptor.
478 EMFILE All file descriptors available to the process are
480 currently open.
481 ENXIO Hangup received on fildes.
483 I_LIST Allows the process to list all the module names on the
485 STREAM, up to and including the topmost driver name. If arg
486 is a null pointer, the return value shall be the number of
487 modules, including the driver, that are on the STREAM
488 pointed to by fildes. This lets the process allocate
489 enough space for the module names. Otherwise, it should
490 point to a str_list structure.
491 The sl_nmods member indicates the number of entries the
493 process has allocated in the array. Upon return, the
494 sl_modlist member of the str_list structure shall contain
495 the list of module names, and the number of entries that
496 have been filled into the sl_modlist array is found in the
497 sl_nmods member (the number includes the number of modules
498 including the driver). The return value from ioctl() shall
499 be 0. The entries are filled in starting at the top of the
500 STREAM and continuing downstream until either the end of
501 the STREAM is reached, or the number of requested modules
502 (sl_nmods) is satisfied.
503 The ioctl() function with the I_LIST command shall fail if:
505 EINVAL The sl_nmods member is less than 1.
507 EAGAIN or ENOSR
509 Unable to allocate buffers.
510 I_ATMARK Allows the process to see if the message at the head of the
512 STREAM head read queue is marked by some module downstream.
513 The arg argument determines how the checking is done when
514 there may be multiple marked messages on the STREAM head
515 read queue. It may take on the following values:
516 ANYMARK Check if the message is marked.
518 LASTMARK Check if the message is the last one marked on
520 the queue.
521 The bitwise-inclusive OR of the flags ANYMARK and LASTMARK
523 is permitted.
524 The return value shall be 1 if the mark condition is satis‐
526 fied; otherwise, the value shall be 0.
527 The ioctl() function with the I_ATMARK command shall fail
529 if:
530 EINVAL Invalid arg value.
532 I_CKBAND Checks if the message of a given priority band exists on
534 the STREAM head read queue. This shall return 1 if a mes‐
535 sage of the given priority exists, 0 if no such message
536 exists, or -1 on error. arg should be of type int.
537 The ioctl() function with the I_CKBAND command shall fail
539 if:
540 EINVAL Invalid arg value.
542 I_GETBAND Returns the priority band of the first message on the
544 STREAM head read queue in the integer referenced by arg.
545 The ioctl() function with the I_GETBAND command shall fail
547 if:
548 ENODATA
550 No message on the STREAM head read queue.
551 I_CANPUT Checks if a certain band is writable. arg is set to the
553 priority band in question. The return value shall be 0 if
554 the band is flow-controlled, 1 if the band is writable, or
555 -1 on error.
556 The ioctl() function with the I_CANPUT command shall fail
558 if:
559 EINVAL Invalid arg value.
561 I_SETCLTIME This request allows the process to set the time the STREAM
563 head shall delay when a STREAM is closing and there is data
564 on the write queues. Before closing each module or driver,
565 if there is data on its write queue, the STREAM head shall
566 delay for the specified amount of time to allow the data to
567 drain. If, after the delay, data is still present, it shall
568 be flushed. The arg argument is a pointer to an integer
569 specifying the number of milliseconds to delay, rounded up
570 to the nearest valid value. If I_SETCLTIME is not performed
571 on a STREAM, an implementation-defined default timeout
572 interval is used.
573 The ioctl() function with the I_SETCLTIME command shall
575 fail if:
576 EINVAL Invalid arg value.
578 I_GETCLTIME Returns the close time delay in the integer pointed to by
580 arg.
581 Multiplexed STREAMS Configurations
583 The following commands are used for connecting and disconnecting multi‐
584 plexed STREAMS configurations. These commands use an implementation-
585 defined default timeout interval.
586 I_LINK Connects two STREAMs, where fildes is the file descriptor
588 of the STREAM connected to the multiplexing driver, and arg
589 is the file descriptor of the STREAM connected to another
590 driver. The STREAM designated by arg is connected below the
591 multiplexing driver. I_LINK requires the multiplexing
592 driver to send an acknowledgement message to the STREAM
593 head regarding the connection. This call shall return a
594 multiplexer ID number (an identifier used to disconnect the
595 multiplexer; see I_UNLINK) on success, and -1 on failure.
596 The ioctl() function with the I_LINK command shall fail if:
598 ENXIO Hangup received on fildes.
600 ETIME Timeout before acknowledgement message was received
602 at STREAM head.
603 EAGAIN or ENOSR
605 Unable to allocate STREAMS storage to perform the
606 I_LINK.
607 EBADF The arg argument is not a valid, open file descrip‐
609 tor.
610 EINVAL The fildes argument does not support multiplexing;
612 or arg is not a STREAM or is already connected down‐
613 stream from a multiplexer; or the specified I_LINK
614 operation would connect the STREAM head in more than
615 one place in the multiplexed STREAM.
616 An I_LINK can also fail while waiting for the multiplexing
618 driver to acknowledge the request, if a message indicating
619 an error or a hangup is received at the STREAM head of
620 fildes. In addition, an error code can be returned in the
621 positive or negative acknowledgement message. For these
622 cases, I_LINK fails with errno set to the value in the mes‐
623 sage.
624 I_UNLINK Disconnects the two STREAMs specified by fildes and arg.
626 fildes is the file descriptor of the STREAM connected to
627 the multiplexing driver. The arg argument is the multi‐
628 plexer ID number that was returned by the I_LINK ioctl()
629 command when a STREAM was connected downstream from the
630 multiplexing driver. If arg is MUXID_ALL, then all STREAMs
631 that were connected to fildes shall be disconnected. As in
632 I_LINK, this command requires acknowledgement.
633 The ioctl() function with the I_UNLINK command shall fail
635 if:
636 ENXIO Hangup received on fildes.
638 ETIME Timeout before acknowledgement message was received
640 at STREAM head.
641 EAGAIN or ENOSR
643 Unable to allocate buffers for the acknowledgement
644 message.
645 EINVAL Invalid multiplexer ID number.
647 An I_UNLINK can also fail while waiting for the multiplex‐
649 ing driver to acknowledge the request if a message indicat‐
650 ing an error or a hangup is received at the STREAM head of
651 fildes. In addition, an error code can be returned in the
652 positive or negative acknowledgement message. For these
653 cases, I_UNLINK shall fail with errno set to the value in
654 the message.
655 I_PLINK Creates a persistent connection between two STREAMs, where
657 fildes is the file descriptor of the STREAM connected to
658 the multiplexing driver, and arg is the file descriptor of
659 the STREAM connected to another driver. This call shall
660 create a persistent connection which can exist even if the
661 file descriptor fildes associated with the upper STREAM to
662 the multiplexing driver is closed. The STREAM designated
663 by arg gets connected via a persistent connection below the
664 multiplexing driver. I_PLINK requires the multiplexing
665 driver to send an acknowledgement message to the STREAM
666 head. This call shall return a multiplexer ID number (an
667 identifier that may be used to disconnect the multiplexer;
668 see I_PUNLINK) on success, and -1 on failure.
669 The ioctl() function with the I_PLINK command shall fail
671 if:
672 ENXIO Hangup received on fildes.
674 ETIME Timeout before acknowledgement message was received
676 at STREAM head.
677 EAGAIN or ENOSR
679 Unable to allocate STREAMS storage to perform the
680 I_PLINK.
681 EBADF The arg argument is not a valid, open file descrip‐
683 tor.
684 EINVAL The fildes argument does not support multiplexing;
686 or arg is not a STREAM or is already connected down‐
687 stream from a multiplexer; or the specified I_PLINK
688 operation would connect the STREAM head in more than
689 one place in the multiplexed STREAM.
690 An I_PLINK can also fail while waiting for the multiplexing
692 driver to acknowledge the request, if a message indicating
693 an error or a hangup is received at the STREAM head of
694 fildes. In addition, an error code can be returned in the
695 positive or negative acknowledgement message. For these
696 cases, I_PLINK shall fail with errno set to the value in
697 the message.
698 I_PUNLINK Disconnects the two STREAMs specified by fildes and arg
700 from a persistent connection. The fildes argument is the
701 file descriptor of the STREAM connected to the multiplexing
702 driver. The arg argument is the multiplexer ID number that
703 was returned by the I_PLINK ioctl() command when a STREAM
704 was connected downstream from the multiplexing driver. If
705 arg is MUXID_ALL, then all STREAMs which are persistent
706 connections to fildes shall be disconnected. As in I_PLINK,
707 this command requires the multiplexing driver to acknowl‐
708 edge the request.
709 The ioctl() function with the I_PUNLINK command shall fail
711 if:
712 ENXIO Hangup received on fildes.
714 ETIME Timeout before acknowledgement message was received
716 at STREAM head.
717 EAGAIN or ENOSR
719 Unable to allocate buffers for the acknowledgement
720 message.
721 EINVAL Invalid multiplexer ID number.
723 An I_PUNLINK can also fail while waiting for the multiplex‐
725 ing driver to acknowledge the request if a message indicat‐
726 ing an error or a hangup is received at the STREAM head of
727 fildes. In addition, an error code can be returned in the
728 positive or negative acknowledgement message. For these
729 cases, I_PUNLINK shall fail with errno set to the value in
730 the message.
731
733 Upon successful completion, ioctl() shall return a value other than -1
734 that depends upon the STREAMS device control function. Otherwise, it
735 shall return -1 and set errno to indicate the error.
736
738 Under the following general conditions, ioctl() shall fail if:
739 EBADF The fildes argument is not a valid open file descriptor.
741 EINTR A signal was caught during the ioctl() operation.
743 EINVAL The STREAM or multiplexer referenced by fildes is linked
745 (directly or indirectly) downstream from a multiplexer.
746 If an underlying device driver detects an error, then ioctl() shall
748 fail if:
749 EINVAL The request or arg argument is not valid for this device.
751 EIO Some physical I/O error has occurred.
753 ENOTTY The file associated with the fildes argument is not a STREAMS
755 device that accepts control functions.
756 ENXIO The request and arg arguments are valid for this device driver,
758 but the service requested cannot be performed on this particular
759 sub-device.
760 ENODEV The fildes argument refers to a valid STREAMS device, but the
762 corresponding device driver does not support the ioctl() func‐
763 tion.
764 If a STREAM is connected downstream from a multiplexer, any ioctl()
766 command except I_UNLINK and I_PUNLINK shall set errno to [EINVAL].
767 The following sections are informative.
769
771 None.
772
774 The implementation-defined timeout interval for STREAMS has histori‐
775 cally been 15 seconds.
776
778 None.
779
781 The ioctl() function may be removed in a future version.
782
784 Section 2.6, STREAMS, close(), fcntl(), getmsg(), open(), pipe(),
785 poll(), putmsg(), read(), sigaction(), write()
786 The Base Definitions volume of POSIX.1‐2017, <stropts.h>
788
790 Portions of this text are reprinted and reproduced in electronic form
791 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
792 table Operating System Interface (POSIX), The Open Group Base Specifi‐
793 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
794 Electrical and Electronics Engineers, Inc and The Open Group. In the
795 event of any discrepancy between this version and the original IEEE and
796 The Open Group Standard, the original IEEE and The Open Group Standard
797 is the referee document. The original Standard can be obtained online
798 at http://www.opengroup.org/unix/online.html .
799 Any typographical or formatting errors that appear in this page are
801 most likely to have been introduced during the conversion of the source
802 files to man page format. To report such errors, see https://www.ker‐
803 nel.org/doc/man-pages/reporting_bugs.html .
804IEEE/The Open Group 2017 IOCTL(3P)