ioctl man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

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

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

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 interpreted 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 control 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 appli‐
       cable 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 structure.	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	 asyn‐
	      chronous processing capability in STREAMS. The value of arg is a
	      bitmask that specifies the events for which the  process	should
	      be  signaled.  It is the bitwise-inclusive OR of any combination
	      of the following constants:

       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 gener‐
	      ated 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 SIGPOLL 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 pro‐
       cesses 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 SIGPOLL 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 mod‐
	      ule 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 without 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 mes‐
       sage was found on the STREAM head read queue, or if the	RS_HIPRI  flag
       was  set	 in  flags  and a high-priority message 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 por‐
	      tion, 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 mes‐
	      sage 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 mes‐
	      sage 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  mem‐
       ber, which must be suitably aligned for use as a t_uscalar_t, specifies
       the offset 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 inter‐
       nal 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,  regard‐
       less  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  cre‐
	      ated.

       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 ctl‐
			buf.

		      * 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 module; 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 maxi‐
	      mum 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 mod‐
       ules 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 down‐
       stream 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  tim‐
       ing  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 stri‐
       octl structure to an internal ioctl() command message and send it down‐
       stream.

       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 con‐
	      figured 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  mes‐
       sage 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 down‐
       stream 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 con‐
	      tain 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 mes‐
	      sage 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 con‐
	      taining 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 mod‐
	      ule names. Otherwise, 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 num‐
       ber 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  permit‐
       ted.

       The  return value shall be 1 if the mark condition is satisfied; other‐
       wise, 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 multi‐
       plexed STREAMS configurations. 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 acknowledge‐
	      ment 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 success, 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  acknowledgement  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 multiplex‐
	      ing 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  acknowl‐
	      edgement.

       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 acknowledgement 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
	      persistent  connection which can exist even if the file descrip‐
	      tor 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 acknowledge‐
	      ment message to the STREAM head. This call shall return a multi‐
	      plexer  ID  number (an identifier that may be used to disconnect
	      the multiplexer; see I_PUNLINK) on success, and -1 on failure.

       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 acknowledgement 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 connection. The fildes argument is the file  descrip‐
	      tor  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 dis‐
	      connected. 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 acknowledgement 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 indicate 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() func‐
	      tion.

       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 histori‐
       cally 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 original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			      IOCTL(P)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net