1IOCTL(3P)                  POSIX Programmer's Manual                 IOCTL(3P)
2
3
4

PROLOG

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
11

NAME

13       ioctl — control a STREAMS device (STREAMS)
14

SYNOPSIS

16       #include <stropts.h>
17
18       int ioctl(int fildes, int request, ... /* arg */);
19

DESCRIPTION

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
27       The fildes argument is an open file descriptor that refers to a device.
28
29       The request argument selects the control function to be  performed  and
30       shall depend on the STREAMS device being addressed.
31
32       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
37       The ioctl() commands applicable to STREAMS, their arguments, and  error
38       conditions that apply to each individual command are described below.
39
40       The following ioctl() commands, with error values indicated, are appli‐
41       cable to all STREAMS files:
42
43       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
47                   The ioctl() function with the I_PUSH command shall fail if:
48
49                   EINVAL Invalid module name.
50
51                   ENXIO  Open function of new module failed.
52
53                   ENXIO  Hangup received on fildes.
54
55       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
59                   The ioctl() function with the I_POP command shall fail if:
60
61                   EINVAL No module present in the STREAM.
62
63                   ENXIO  Hangup received on fildes.
64
65       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
71                   The ioctl() function with the I_LOOK command shall fail if:
72
73                   EINVAL No module present in the STREAM.
74
75       I_FLUSH     Flushes read and/or write queues, depending on the value of
76                   arg.  Valid arg values are:
77
78                   FLUSHR      Flush all read queues.
79
80                   FLUSHW      Flush all write queues.
81
82                   FLUSHRW     Flush all read and all write queues.
83
84                   The  ioctl()  function  with the I_FLUSH command shall fail
85                   if:
86
87                   EINVAL Invalid arg value.
88
89                   EAGAIN or ENOSR
90                          Unable to allocate buffers for flush message.
91
92                   ENXIO  Hangup received on fildes.
93
94       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
99       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
107                   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
112                   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
117                   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
122                   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
126                   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
132                   S_WRNORM    Equivalent to S_OUTPUT.
133
134                   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
140                   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
144                   S_ERROR     Notification of an error condition has  reached
145                               the STREAM head.
146
147                   S_HANGUP    Notification of a hangup has reached the STREAM
148                               head.
149
150                   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
155                   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
159                   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
165                   The  ioctl()  function with the I_SETSIG command shall fail
166                   if:
167
168                   EINVAL The value of arg is invalid.
169
170                   EINVAL The value of arg is 0 and the calling process is not
171                          registered to receive the SIGPOLL signal.
172
173                   EAGAIN There  were insufficient resources to store the sig‐
174                          nal request.
175
176       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
182                   The ioctl() function with the I_GETSIG command  shall  fail
183                   if:
184
185                   EINVAL Process  is  not  registered  to receive the SIGPOLL
186                          signal.
187
188       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
193                   The ioctl() function with the I_FIND command shall fail if:
194
195                   EINVAL arg does not contain a valid module name.
196
197       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
203                   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
211                   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
220       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
223                   RNORM       Byte-stream mode, the default.
224
225                   RMSGD       Message-discard mode.
226
227                   RMSGN       Message-nondiscard mode.
228
229                   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
234                   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
238                   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
242                   RPROTDAT    Deliver the control part of a message  as  data
243                               when a process issues a read().
244
245                   RPROTDIS    Discard the control part of a message, deliver‐
246                               ing any data portion, when a process  issues  a
247                               read().
248
249                   The  ioctl()  function with the I_SRDOPT command shall fail
250                   if:
251
252                   EINVAL The arg argument is not valid.
253
254       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
258       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
266       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
273                   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
287                   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
298                   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
303                   The ioctl() function with the I_FDINSERT command shall fail
304                   if:
305
306                   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
310                   EAGAIN or ENOSR
311                          Buffers cannot be allocated for the message that  is
312                          to be created.
313
314                   EINVAL One of the following:
315
316                               --  The fildes member of the strfdinsert struc‐
317                                   ture is  not  a  valid,  open  STREAM  file
318                                   descriptor.
319
320                               --  The  size  of  a t_uscalar_t plus offset is
321                                   greater than the len member for the  buffer
322                                   specified through ctlbuf.
323
324                               --  The  offset member does not specify a prop‐
325                                   erly-aligned location in the data buffer.
326
327                               --  An undefined value is stored in flags.
328
329                   ENXIO  Hangup received on the STREAM identified  by  either
330                          the  fildes  argument  or  the  fildes member of the
331                          strfdinsert structure.
332
333                   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
343       I_STR       Constructs an internal STREAMS  ioctl()  message  from  the
344                   data pointed to by arg, and sends that message downstream.
345
346                   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
355                   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
361                   To send requests downstream, the application  shall  ensure
362                   that arg points to a strioctl structure.
363
364                   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
378                   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
382                   The ioctl() function with the I_STR command shall fail if:
383
384                   EAGAIN or ENOSR
385                          Unable to allocate buffers for the ioctl() message.
386
387                   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
391                   ENXIO  Hangup received on fildes.
392
393                   ETIME  A  downstream  ioctl() timed out before acknowledge‐
394                          ment was received.
395
396                   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
404       I_SWROPT    Sets the write mode using the value of  the  argument  arg.
405                   Valid bit settings for arg are:
406
407                   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
414                   The ioctl() function with the I_SWROPT command  shall  fail
415                   if:
416
417                   EINVAL arg is not the above value.
418
419       I_GWROPT    Returns the current write mode setting, as described above,
420                   in the int that is pointed to by the argument arg.
421
422       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
428                   The ioctl() function with the I_SENDFD command  shall  fail
429                   if:
430
431                   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
436                   EBADF  The arg argument is not a valid, open file  descrip‐
437                          tor.
438
439                   EINVAL The  fildes  argument  is  not connected to a STREAM
440                          pipe.
441
442                   ENXIO  Hangup received on fildes.
443
444                   The ioctl() function with the I_SENDFD command may fail if:
445
446                   EINVAL The arg argument is equal to the fildes argument.
447
448       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
455                   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
459                   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
464                   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
470                   The ioctl() function with the I_RECVFD command  shall  fail
471                   if:
472
473                   EAGAIN A  message  is  not  present at the STREAM head read
474                          queue and the O_NONBLOCK flag is set.
475
476                   EBADMSG
477                          The message at the STREAM head read queue is  not  a
478                          message containing a passed file descriptor.
479
480                   EMFILE All  file  descriptors  available to the process are
481                          currently open.
482
483                   ENXIO  Hangup received on fildes.
484
485       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
493                   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
505                   The ioctl() function with the I_LIST command shall fail if:
506
507                   EINVAL The sl_nmods member is less than 1.
508
509                   EAGAIN or ENOSR
510                          Unable to allocate buffers.
511
512       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
518                   ANYMARK     Check if the message is marked.
519
520                   LASTMARK    Check if the message is the last one marked  on
521                               the queue.
522
523                   The  bitwise-inclusive OR of the flags ANYMARK and LASTMARK
524                   is permitted.
525
526                   The return value shall be 1 if the mark condition is satis‐
527                   fied; otherwise, the value shall be 0.
528
529                   The  ioctl()  function with the I_ATMARK command shall fail
530                   if:
531
532                   EINVAL Invalid arg value.
533
534       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
539                   The  ioctl()  function with the I_CKBAND command shall fail
540                   if:
541
542                   EINVAL Invalid arg value.
543
544       I_GETBAND   Returns the priority band  of  the  first  message  on  the
545                   STREAM head read queue in the integer referenced by arg.
546
547                   The  ioctl() function with the I_GETBAND command shall fail
548                   if:
549
550                   ENODATA
551                          No message on the STREAM head read queue.
552
553       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
558                   The  ioctl()  function with the I_CANPUT command shall fail
559                   if:
560
561                   EINVAL Invalid arg value.
562
563       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
575                   The ioctl() function with  the  I_SETCLTIME  command  shall
576                   fail if:
577
578                   EINVAL Invalid arg value.
579
580       I_GETCLTIME Returns  the  close time delay in the integer pointed to by
581                   arg.
582
583   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
588       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
598                   The ioctl() function with the I_LINK command shall fail if:
599
600                   ENXIO  Hangup received on fildes.
601
602                   ETIME  Timeout before acknowledgement message was  received
603                          at STREAM head.
604
605                   EAGAIN or ENOSR
606                          Unable  to  allocate  STREAMS storage to perform the
607                          I_LINK.
608
609                   EBADF  The arg argument is not a valid, open file  descrip‐
610                          tor.
611
612                   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
618                   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
626       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
635                   The ioctl() function with the I_UNLINK command  shall  fail
636                   if:
637
638                   ENXIO  Hangup received on fildes.
639
640                   ETIME  Timeout  before acknowledgement message was received
641                          at STREAM head.
642
643                   EAGAIN or ENOSR
644                          Unable to allocate buffers for  the  acknowledgement
645                          message.
646
647                   EINVAL Invalid multiplexer ID number.
648
649                   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
657       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
671                   The  ioctl()  function  with the I_PLINK command shall fail
672                   if:
673
674                   ENXIO  Hangup received on fildes.
675
676                   ETIME  Timeout before acknowledgement message was  received
677                          at STREAM head.
678
679                   EAGAIN or ENOSR
680                          Unable  to  allocate  STREAMS storage to perform the
681                          I_PLINK.
682
683                   EBADF  The arg argument is not a valid, open file  descrip‐
684                          tor.
685
686                   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
692                   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
700       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
711                   The ioctl() function with the I_PUNLINK command shall  fail
712                   if:
713
714                   ENXIO  Hangup received on fildes.
715
716                   ETIME  Timeout  before acknowledgement message was received
717                          at STREAM head.
718
719                   EAGAIN or ENOSR
720                          Unable to allocate buffers for  the  acknowledgement
721                          message.
722
723                   EINVAL Invalid multiplexer ID number.
724
725                   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

RETURN VALUE

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

ERRORS

739       Under the following general conditions, ioctl() shall fail if:
740
741       EBADF  The fildes argument is not a valid open file descriptor.
742
743       EINTR  A signal was caught during the ioctl() operation.
744
745       EINVAL The  STREAM  or  multiplexer  referenced  by  fildes  is  linked
746              (directly or indirectly) downstream from a multiplexer.
747
748       If an underlying device driver detects an  error,  then  ioctl()  shall
749       fail if:
750
751       EINVAL The request or arg argument is not valid for this device.
752
753       EIO    Some physical I/O error has occurred.
754
755       ENOTTY The  file  associated  with the fildes argument is not a STREAMS
756              device that accepts control functions.
757
758       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
762       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
766       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
769       The following sections are informative.
770

EXAMPLES

772       None.
773

APPLICATION USAGE

775       The  implementation-defined  timeout  interval for STREAMS has histori‐
776       cally been 15 seconds.
777

RATIONALE

779       None.
780

FUTURE DIRECTIONS

782       The ioctl() function may be removed in a future version.
783

SEE ALSO

785       Section 2.6,  STREAMS,  close(),  fcntl(),  getmsg(),  open(),  pipe(),
786       poll(), putmsg(), read(), sigaction(), write()
787
788       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
802       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 .
806
807
808
809IEEE/The Open Group                  2013                            IOCTL(3P)
Impressum