Unix/Linux Go Back    


Linux 2.6 - man page for ioctl (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


IOCTL(P)			    POSIX Programmer's Manual				 IOCTL(P)

NAME
       ioctl - control a STREAMS device (STREAMS)

SYNOPSIS
       #include <stropts.h>

       int ioctl(int fildes, int request, ... /* arg */);

DESCRIPTION
       The  ioctl() function shall perform a variety of control functions on STREAMS devices. For
       non-STREAMS devices, the functions performed by this call  are  unspecified.  The  request
       argument  and an optional third argument (with varying type) shall be passed to and inter-
       preted by the appropriate part of the STREAM associated with fildes.

       The fildes argument is an open file descriptor that refers to a device.

       The request argument selects the control function to be performed and shall depend on  the
       STREAMS device being addressed.

       The arg argument represents additional information that is needed by this specific STREAMS
       device to perform the requested function. The type of arg depends upon the particular con-
       trol  request,  but  it	shall be either an integer or a pointer to a device-specific data
       structure.

       The ioctl() commands applicable to STREAMS, their arguments,  and  error  conditions  that
       apply to each individual command are described below.

       The following ioctl() commands, with error values indicated, are applicable to all STREAMS
       files:

       I_PUSH Pushes the module whose name is pointed to by arg  onto  the  top  of  the  current
	      STREAM, just below the STREAM head. It then calls the open() function of the newly-
	      pushed module.

       The ioctl() function with the I_PUSH command shall fail if:

       EINVAL
	      Invalid module name.

       ENXIO
	      Open function of new module failed.

       ENXIO
	      Hangup received on fildes.

       I_POP  Removes the module just below the STREAM head of the STREAM pointed to  by  fildes.
	      The arg argument should be 0 in an I_POP request.

       The ioctl() function with the I_POP command shall fail if:

       EINVAL
	      No module present in the STREAM.

       ENXIO
	      Hangup received on fildes.

       I_LOOK Retrieves  the  name of the module just below the STREAM head of the STREAM pointed
	      to by fildes, and places it in a character string pointed to  by	arg.  The  buffer
	      pointed  to  by  arg  should  be	at least FMNAMESZ+1 bytes long, where FMNAMESZ is
	      defined in <stropts.h>.

       The ioctl() function with the I_LOOK command shall fail if:

       EINVAL
	      No module present in the STREAM.

       I_FLUSH
	      Flushes read and/or write queues, depending on the value of arg.	Valid arg  values
	      are:

       FLUSHR
	      Flush all read queues.

       FLUSHW
	      Flush all write queues.

       FLUSHRW
	      Flush all read and all write queues.

       The ioctl() function with the I_FLUSH command shall fail if:

       EINVAL
	      Invalid arg value.

       EAGAIN or ENOSR

	      Unable to allocate buffers for flush message.

       ENXIO
	      Hangup received on fildes.

       I_FLUSHBAND
	      Flushes a particular band of messages. The arg argument points to a bandinfo struc-
	      ture. The bi_flag member may be one of FLUSHR,  FLUSHW,  or  FLUSHRW  as	described
	      above. The bi_pri member determines the priority band to be flushed.

       I_SETSIG
	      Requests	that  the  STREAMS  implementation send the SIGPOLL signal to the calling
	      process when a particular event has occurred on the STREAM associated with  fildes.
	      I_SETSIG	supports  an  asynchronous processing capability in STREAMS. The value of
	      arg is a bitmask that specifies the events for which the	process  should  be  sig-
	      naled.  It  is  the  bitwise-inclusive  OR of any combination of the following con-
	      stants:

       S_RDNORM
	      A normal (priority band set to 0) message has arrived at the head of a STREAM  head
	      read queue. A signal shall be generated even if the message is of zero length.

       S_RDBAND
	      A  message  with	a non-zero priority band has arrived at the head of a STREAM head
	      read queue. A signal shall be generated even if the message is of zero length.

       S_INPUT
	      A message, other than a high-priority message, has arrived at the head of a  STREAM
	      head read queue. A signal shall be generated even if the message is of zero length.

       S_HIPRI
	      A  high-priority	message is present on a STREAM head read queue. A signal shall be
	      generated even if the message is of zero length.

       S_OUTPUT
	      The write queue for normal data (priority band 0) just below the STREAM head is  no
	      longer  full. This notifies the process that there is room on the queue for sending
	      (or writing) normal data downstream.

       S_WRNORM
	      Equivalent to S_OUTPUT.

       S_WRBAND
	      The write queue for a non-zero priority band just  below	the  STREAM  head  is  no
	      longer  full. This notifies the process that there is room on the queue for sending
	      (or writing) priority data downstream.

       S_MSG
	      A STREAMS signal message that contains the SIGPOLL signal has reached the front  of
	      the STREAM head read queue.

       S_ERROR
	      Notification of an error condition has reached the STREAM head.

       S_HANGUP
	      Notification of a hangup has reached the STREAM head.

       S_BANDURG
	      When used in conjunction with S_RDBAND, SIGURG is generated instead of SIGPOLL when
	      a priority message reaches the front of the STREAM head read queue.

       If arg is 0, the calling process shall be unregistered and shall not receive further  SIG-
       POLL signals for the stream associated with fildes.

       Processes  that wish to receive SIGPOLL signals shall ensure that they explicitly register
       to receive them using I_SETSIG. If several processes register to receive this  signal  for
       the same event on the same STREAM, each process shall be signaled when the event occurs.

       The ioctl() function with the I_SETSIG command shall fail if:

       EINVAL
	      The value of arg is invalid.

       EINVAL
	      The value of arg is 0 and the calling process is not registered to receive the SIG-
	      POLL signal.

       EAGAIN
	      There were insufficient resources to store the signal request.

       I_GETSIG
	      Returns the events for which the calling process is currently registered to be sent
	      a SIGPOLL signal. The events are returned as a bitmask in an int pointed to by arg,
	      where the events are those specified in the description of I_SETSIG above.

       The ioctl() function with the I_GETSIG command shall fail if:

       EINVAL
	      Process is not registered to receive the SIGPOLL signal.

       I_FIND Compares the names of all modules currently present  in  the  STREAM  to	the  name
	      pointed  to  by arg, and returns 1 if the named module is present in the STREAM, or
	      returns 0 if the named module is not present.

       The ioctl() function with the I_FIND command shall fail if:

       EINVAL
	      arg does not contain a valid module name.

       I_PEEK Retrieves the information in the first message on the STREAM head read queue  with-
	      out  taking the message off the queue. It is analogous to getmsg() except that this
	      command does not remove the message from the queue. The arg argument  points  to	a
	      strpeek structure.

       The  application  shall	ensure	that  the  maxlen member in the ctlbuf and databuf strbuf
       structures is set to the number of bytes of control information and/or  data  information,
       respectively,  to  retrieve. The flags member may be marked RS_HIPRI or 0, as described by
       getmsg(). If the process sets flags to RS_HIPRI, for example, I_PEEK shall only look for a
       high-priority message on the STREAM head read queue.

       I_PEEK  returns 1 if a message was retrieved, and returns 0 if no message was found on the
       STREAM head read queue, or if the RS_HIPRI flag was set in flags and a high-priority  mes-
       sage  was  not  present	on  the STREAM head read queue. It does not wait for a message to
       arrive. On return, ctlbuf specifies information in the control buffer,  databuf	specifies
       information in the data buffer, and flags contains the value RS_HIPRI or 0.

       I_SRDOPT
	      Sets the read mode using the value of the argument arg. Read modes are described in
	      read() . Valid arg flags are:

       RNORM
	      Byte-stream mode, the default.

       RMSGD
	      Message-discard mode.

       RMSGN
	      Message-nondiscard mode.

       The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL].  The	bitwise-inclusive
       OR  of  RNORM  and  either  RMSGD or RMSGN shall result in the other flag overriding RNORM
       which is the default.

       In addition, treatment of control messages by the STREAM head may be  changed  by  setting
       any of the following flags in arg:

       RPROTNORM
	      Fail  read()  with [EBADMSG] if a message containing a control part is at the front
	      of the STREAM head read queue.

       RPROTDAT
	      Deliver the control part of a message as data when a process issues a read().

       RPROTDIS
	      Discard the control part of a message, delivering any data portion, when a  process
	      issues a read().

       The ioctl() function with the I_SRDOPT command shall fail if:

       EINVAL
	      The arg argument is not valid.

       I_GRDOPT
	      Returns  the current read mode setting, as described above, in an int pointed to by
	      the argument arg. Read modes are described in read() .

       I_NREAD
	      Counts the number of data bytes in the data part of the first message on the STREAM
	      head  read  queue  and  places  this value in the int pointed to by arg. The return
	      value for the command shall be the number of  messages  on  the  STREAM  head  read
	      queue.  For  example,  if  0  is	returned  in arg, but the ioctl() return value is
	      greater than 0, this indicates that a zero-length message is next on the queue.

       I_FDINSERT
	      Creates a message from specified buffer(s), adds information about another  STREAM,
	      and  sends  the  message	downstream.  The  message  contains a control part and an
	      optional data part. The data and control parts to  be  sent  are	distinguished  by
	      placement  in  separate  buffers,  as described below. The arg argument points to a
	      strfdinsert structure.

       The application shall ensure that the len member in the ctlbuf strbuf structure is set  to
       the  size of a t_uscalar_t plus the number of bytes of control information to be sent with
       the message. The fildes member specifies the file descriptor of the other STREAM, and  the
       offset member, which must be suitably aligned for use as a t_uscalar_t, specifies the off-
       set from the start of the control buffer where I_FDINSERT shall store a t_uscalar_t  whose
       interpretation  is  specific  to the STREAM end. The application shall ensure that the len
       member in the databuf strbuf structure is set to the number of bytes of	data  information
       to be sent with the message, or to 0 if no data part is to be sent.

       The flags member specifies the type of message to be created.  A normal message is created
       if flags is set to 0, and a high-priority message is created if flags is set to	RS_HIPRI.
       For non-priority messages, I_FDINSERT shall block if the STREAM write queue is full due to
       internal flow control conditions.  For priority messages, I_FDINSERT  does  not	block  on
       this  condition. For non-priority messages, I_FDINSERT does not block when the write queue
       is full and O_NONBLOCK is set. Instead, it fails and sets errno to [EAGAIN].

       I_FDINSERT also blocks, unless prevented by lack of internal resources,	waiting  for  the
       availability of message blocks in the STREAM, regardless of priority or whether O_NONBLOCK
       has been specified.  No partial message is sent.

       The ioctl() function with the I_FDINSERT command shall fail if:

       EAGAIN
	      A non-priority message is specified, the O_NONBLOCK flag is  set,  and  the  STREAM
	      write queue is full due to internal flow control conditions.

       EAGAIN or ENOSR

	      Buffers cannot be allocated for the message that is to be created.

       EINVAL
	      One of the following:

		      * The  fildes  member  of  the  strfdinsert  structure is not a valid, open
			STREAM file descriptor.

		      * The size of a t_uscalar_t plus offset is greater than the len member  for
			the buffer specified through ctlbuf.

		      * The  offset  member  does  not specify a properly-aligned location in the
			data buffer.

		      * An undefined value is stored in flags.

       ENXIO
	      Hangup received on the STREAM identified by  either  the	fildes	argument  or  the
	      fildes member of the strfdinsert structure.

       ERANGE
	      The  len	member	for the buffer specified through databuf does not fall within the
	      range specified by the maximum and minimum packet sizes of the topmost STREAM  mod-
	      ule;  or the len member for the buffer specified through databuf is larger than the
	      maximum configured size of the data part of a message; or the len  member  for  the
	      buffer  specified  through ctlbuf is larger than the maximum configured size of the
	      control part of a message.

       I_STR  Constructs an internal STREAMS ioctl() message from the data pointed to by arg, and
	      sends that message downstream.

       This  mechanism is provided to send ioctl() requests to downstream modules and drivers. It
       allows information to be sent with ioctl(), and returns to  the	process  any  information
       sent  upstream  by  the	downstream recipient. I_STR shall block until the system responds
       with either a positive or negative acknowledgement message, or until the request times out
       after  some  period  of	time.  If  the request times out, it shall fail with errno set to
       [ETIME].

       At most, one I_STR can be active on a STREAM. Further I_STR calls shall	block  until  the
       active I_STR completes at the STREAM head. The default timeout interval for these requests
       is 15 seconds.  The O_NONBLOCK flag has no effect on this call.

       To send requests downstream, the application shall ensure that arg points  to  a  strioctl
       structure.

       The  ic_cmd  member  is	the  internal ioctl() command intended for a downstream module or
       driver and ic_timout is the number of seconds (-1=infinite,  0=use  implementation-defined
       timeout	interval, >0=as specified) an I_STR request shall wait for acknowledgement before
       timing out. ic_len is the number of bytes in the data argument, and ic_dp is a pointer  to
       the data argument. The ic_len member has two uses: on input, it contains the length of the
       data argument passed in, and on return from the command, it contains the number	of  bytes
       being  returned	to  the process (the buffer pointed to by ic_dp should be large enough to
       contain the maximum amount of data that any  module  or	the  driver  in  the  STREAM  can
       return).

       The  STREAM  head shall convert the information pointed to by the strioctl structure to an
       internal ioctl() command message and send it downstream.

       The ioctl() function with the I_STR command shall fail if:

       EAGAIN or ENOSR

	      Unable to allocate buffers for the ioctl() message.

       EINVAL
	      The ic_len member is less than 0 or larger than the maximum configured size of  the
	      data part of a message, or ic_timout is less than -1.

       ENXIO
	      Hangup received on fildes.

       ETIME
	      A downstream ioctl() timed out before acknowledgement was received.

       An  I_STR  can  also  fail while waiting for an acknowledgement if a message indicating an
       error or a hangup is received at the STREAM head.  In  addition,  an  error  code  can  be
       returned  in  the  positive  or negative acknowledgement message, in the event the ioctl()
       command sent downstream fails. For these cases, I_STR shall fail with  errno  set  to  the
       value in the message.

       I_SWROPT
	      Sets the write mode using the value of the argument arg. Valid bit settings for arg
	      are:

       SNDZERO
	      Send a zero-length message downstream when a write() of 0 bytes occurs. To not send
	      a  zero-length  message  when  a	write()  of 0 bytes occurs, the application shall
	      ensure that this bit is not set in arg (for example, arg would be set to 0).

       The ioctl() function with the I_SWROPT command shall fail if:

       EINVAL
	      arg is not the above value.

       I_GWROPT
	      Returns the current write mode setting, as described above,  in  the  int  that  is
	      pointed to by the argument arg.

       I_SENDFD
	      Creates  a  new  reference  to  the  open file description associated with the file
	      descriptor arg, and writes a message on the STREAMS-based  pipe  fildes  containing
	      this reference, together with the user ID and group ID of the calling process.

       The ioctl() function with the I_SENDFD command shall fail if:

       EAGAIN
	      The  sending  STREAM  is	unable	to  allocate  a message block to contain the file
	      pointer; or the read queue of the receiving STREAM head is full and  cannot  accept
	      the message sent by I_SENDFD.

       EBADF
	      The arg argument is not a valid, open file descriptor.

       EINVAL
	      The fildes argument is not connected to a STREAM pipe.

       ENXIO
	      Hangup received on fildes.

       I_RECVFD
	      Retrieves  the  reference  to  an open file description from a message written to a
	      STREAMS-based pipe using the I_SENDFD command, and allocates a new file  descriptor
	      in  the calling process that refers to this open file description. The arg argument
	      is a pointer to a strrecvfd data structure as defined in <stropts.h>.

       The fd member is a file descriptor. The uid and gid members are the effective user ID  and
       effective group ID, respectively, of the sending process.

       If  O_NONBLOCK  is  not set, I_RECVFD shall block until a message is present at the STREAM
       head. If O_NONBLOCK is set, I_RECVFD shall fail with errno set to [EAGAIN] if  no  message
       is present at the STREAM head.

       If  the message at the STREAM head is a message sent by an I_SENDFD, a new file descriptor
       shall be allocated for the open file descriptor referenced in the message.  The	new  file
       descriptor is placed in the fd member of the strrecvfd structure pointed to by arg.

       The ioctl() function with the I_RECVFD command shall fail if:

       EAGAIN
	      A  message  is not present at the STREAM head read queue and the O_NONBLOCK flag is
	      set.

       EBADMSG
	      The message at the STREAM head read queue is not a message containing a passed file
	      descriptor.

       EMFILE
	      The  process  has  the maximum number of file descriptors currently open that it is
	      allowed.

       ENXIO
	      Hangup received on fildes.

       I_LIST Allows the process to list all the module names on the STREAM, up to and	including
	      the  topmost  driver  name. If arg is a null pointer, the return value shall be the
	      number of modules, including the driver, that are  on  the  STREAM  pointed  to  by
	      fildes.  This  lets  the process allocate enough space for the module names. Other-
	      wise, it should point to a str_list structure.

       The sl_nmods member indicates the number of entries  the  process  has  allocated  in  the
       array. Upon return, the sl_modlist member of the str_list structure shall contain the list
       of module names, and the number of entries that have been filled into the sl_modlist array
       is  found  in the sl_nmods member (the number includes the number of modules including the
       driver). The return value from ioctl() shall be 0. The entries are filled in  starting  at
       the  top  of  the  STREAM  and continuing downstream until either the end of the STREAM is
       reached, or the number of requested modules ( sl_nmods) is satisfied.

       The ioctl() function with the I_LIST command shall fail if:

       EINVAL
	      The sl_nmods member is less than 1.

       EAGAIN or ENOSR

	      Unable to allocate buffers.

       I_ATMARK
	      Allows the process to see if the message at the head of the STREAM head read  queue
	      is  marked  by some module downstream. The arg argument determines how the checking
	      is done when there may be multiple marked messages on the STREAM head  read  queue.
	      It may take on the following values:

       ANYMARK
	      Check if the message is marked.

       LASTMARK
	      Check if the message is the last one marked on the queue.

       The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is permitted.

       The return value shall be 1 if the mark condition is satisfied; otherwise, the value shall
       be 0.

       The ioctl() function with the I_ATMARK command shall fail if:

       EINVAL
	      Invalid arg value.

       I_CKBAND
	      Checks if the message of a given priority band  exists  on  the  STREAM  head  read
	      queue.  This shall return 1 if a message of the given priority exists, 0 if no such
	      message exists, or -1 on error.  arg should be of type int.

       The ioctl() function with the I_CKBAND command shall fail if:

       EINVAL
	      Invalid arg value.

       I_GETBAND
	      Returns the priority band of the first message on the STREAM head read queue in the
	      integer referenced by arg.

       The ioctl() function with the I_GETBAND command shall fail if:

       ENODATA
	      No message on the STREAM head read queue.

       I_CANPUT
	      Checks  if a certain band is writable. arg is set to the priority band in question.
	      The return value shall be 0 if the band  is  flow-controlled,  1	if  the  band  is
	      writable, or -1 on error.

       The ioctl() function with the I_CANPUT command shall fail if:

       EINVAL
	      Invalid arg value.

       I_SETCLTIME
	      This  request allows the process to set the time the STREAM head shall delay when a
	      STREAM is closing and there is data on the write queues. Before closing each module
	      or driver, if there is data on its write queue, the STREAM head shall delay for the
	      specified amount of time to allow the data to drain. If, after the delay,  data  is
	      still  present,  it  shall  be flushed. The arg argument is a pointer to an integer
	      specifying the number of milliseconds to delay, rounded up  to  the  nearest  valid
	      value.  If  I_SETCLTIME  is  not	performed  on a STREAM, an implementation-defined
	      default timeout interval is used.

       The ioctl() function with the I_SETCLTIME command shall fail if:

       EINVAL
	      Invalid arg value.

       I_GETCLTIME
	      Returns the close time delay in the integer pointed to by arg.

   Multiplexed STREAMS Configurations
       The following commands are used for connecting and disconnecting multiplexed STREAMS  con-
       figurations. These commands use an implementation-defined default timeout interval.

       I_LINK Connects	two  STREAMs, where fildes is the file descriptor of the STREAM connected
	      to the multiplexing driver, and arg is the file descriptor of the STREAM	connected
	      to another driver. The STREAM designated by arg is connected below the multiplexing
	      driver. I_LINK requires the multiplexing driver to send an acknowledgement  message
	      to  the  STREAM head regarding the connection. This call shall return a multiplexer
	      ID number (an identifier used to disconnect the multiplexer; see I_UNLINK) on  suc-
	      cess, and -1 on failure.

       The ioctl() function with the I_LINK command shall fail if:

       ENXIO
	      Hangup received on fildes.

       ETIME
	      Timeout before acknowledgement message was received at STREAM head.

       EAGAIN or ENOSR

	      Unable to allocate STREAMS storage to perform the I_LINK.

       EBADF
	      The arg argument is not a valid, open file descriptor.

       EINVAL
	      The  fildes  argument  does  not support multiplexing; or arg is not a STREAM or is
	      already connected downstream from a multiplexer; or the specified I_LINK	operation
	      would connect the STREAM head in more than one place in the multiplexed STREAM.

       An  I_LINK  can	also  fail  while  waiting for the multiplexing driver to acknowledge the
       request, if a message indicating an error or a hangup is received at the  STREAM  head  of
       fildes.	In  addition,  an error code can be returned in the positive or negative acknowl-
       edgement message. For these cases, I_LINK fails with errno set to the value  in	the  mes-
       sage.

       I_UNLINK
	      Disconnects  the	two  STREAMs  specified  by  fildes  and arg.  fildes is the file
	      descriptor of the STREAM connected to the multiplexing driver. The arg argument  is
	      the  multiplexer	ID  number that was returned by the I_LINK ioctl() command when a
	      STREAM was connected downstream from the multiplexing driver. If arg is  MUXID_ALL,
	      then  all  STREAMs  that	were  connected  to  fildes shall be disconnected.  As in
	      I_LINK, this command requires acknowledgement.

       The ioctl() function with the I_UNLINK command shall fail if:

       ENXIO
	      Hangup received on fildes.

       ETIME
	      Timeout before acknowledgement message was received at STREAM head.

       EAGAIN or ENOSR

	      Unable to allocate buffers for the acknowledgement message.

       EINVAL
	      Invalid multiplexer ID number.

       An I_UNLINK can also fail while waiting for the multiplexing  driver  to  acknowledge  the
       request	if  a  message	indicating an error or a hangup is received at the STREAM head of
       fildes. In addition, an error code can be returned in the positive  or  negative  acknowl-
       edgement  message. For these cases, I_UNLINK shall fail with errno set to the value in the
       message.

       I_PLINK
	      Creates a persistent connection between two  STREAMs,  where  fildes  is	the  file
	      descriptor  of the STREAM connected to the multiplexing driver, and arg is the file
	      descriptor of the STREAM connected to another driver. This call shall create a per-
	      sistent  connection  which  can exist even if the file descriptor fildes associated
	      with the upper STREAM to the multiplexing driver is closed. The  STREAM  designated
	      by  arg  gets  connected via a persistent connection below the multiplexing driver.
	      I_PLINK requires the multiplexing driver to send an acknowledgement message to  the
	      STREAM head. This call shall return a multiplexer ID number (an identifier that may
	      be used to disconnect the multiplexer; see I_PUNLINK) on success, and -1	on  fail-
	      ure.

       The ioctl() function with the I_PLINK command shall fail if:

       ENXIO
	      Hangup received on fildes.

       ETIME
	      Timeout before acknowledgement message was received at STREAM head.

       EAGAIN or ENOSR

	      Unable to allocate STREAMS storage to perform the I_PLINK.

       EBADF
	      The arg argument is not a valid, open file descriptor.

       EINVAL
	      The  fildes  argument  does  not support multiplexing; or arg is not a STREAM or is
	      already connected downstream from a multiplexer; or the specified I_PLINK operation
	      would connect the STREAM head in more than one place in the multiplexed STREAM.

       An  I_PLINK  can  also  fail  while waiting for the multiplexing driver to acknowledge the
       request, if a message indicating an error or a hangup is received at the  STREAM  head  of
       fildes.	In  addition,  an error code can be returned in the positive or negative acknowl-
       edgement message. For these cases, I_PLINK shall fail with errno set to the value  in  the
       message.

       I_PUNLINK
	      Disconnects  the	two STREAMs specified by fildes and arg from a persistent connec-
	      tion. The fildes argument is the file descriptor of the  STREAM  connected  to  the
	      multiplexing  driver.  The  arg  argument  is  the  multiplexer  ID number that was
	      returned by the I_PLINK ioctl() command when a STREAM was connected downstream from
	      the multiplexing driver. If arg is MUXID_ALL, then all STREAMs which are persistent
	      connections to fildes shall be disconnected. As in I_PLINK, this	command  requires
	      the multiplexing driver to acknowledge the request.

       The ioctl() function with the I_PUNLINK command shall fail if:

       ENXIO
	      Hangup received on fildes.

       ETIME
	      Timeout before acknowledgement message was received at STREAM head.

       EAGAIN or ENOSR

	      Unable to allocate buffers for the acknowledgement message.

       EINVAL
	      Invalid multiplexer ID number.

       An  I_PUNLINK  can  also fail while waiting for the multiplexing driver to acknowledge the
       request if a message indicating an error or a hangup is received at  the  STREAM  head  of
       fildes.	In  addition,  an error code can be returned in the positive or negative acknowl-
       edgement message. For these cases, I_PUNLINK shall fail with errno set to the value in the
       message.

RETURN VALUE
       Upon  successful  completion, ioctl() shall return a value other than -1 that depends upon
       the STREAMS device control function. Otherwise, it shall return -1 and set errno to  indi-
       cate the error.

ERRORS
       Under the following general conditions, ioctl() shall fail if:

       EBADF  The fildes argument is not a valid open file descriptor.

       EINTR  A signal was caught during the ioctl() operation.

       EINVAL The  STREAM  or multiplexer referenced by fildes is linked (directly or indirectly)
	      downstream from a multiplexer.

       If an underlying device driver detects an error, then ioctl() shall fail if:

       EINVAL The request or arg argument is not valid for this device.

       EIO    Some physical I/O error has occurred.

       ENOTTY The fildes argument is not associated with a STREAMS device  that  accepts  control
	      functions.

       ENXIO  The  request  and  arg  arguments are valid for this device driver, but the service
	      requested cannot be performed on this particular sub-device.

       ENODEV The fildes argument refers to a valid STREAMS device, but the corresponding  device
	      driver does not support the ioctl() function.

       If  a  STREAM  is  connected  downstream  from  a  multiplexer, any ioctl() command except
       I_UNLINK and I_PUNLINK shall set errno to [EINVAL].

       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       The implementation-defined timeout interval for STREAMS has historically been 15 seconds.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       STREAMS , close() , fcntl() , getmsg() , open() , pipe() , poll() , putmsg()  ,	read()	,
       sigaction() , write() , the Base Definitions volume of IEEE Std 1003.1-2001, <stropts.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					 IOCTL(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:06 AM.