Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
streamio(7I)			Ioctl Requests			  streamio(7I)

NAME
       streamio	- STREAMS ioctl	commands

SYNOPSIS
       #include	<sys/types.h>
       #include	<stropts.h>
       #include	<sys/conf.h>

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

DESCRIPTION
       STREAMS (see intro(3)) ioctl commands are a subset of the ioctl(2) com-
       mands and perform a variety of control functions	on streams.

       The fildes argument is an open file descriptor that refers to a stream.
       The command argument determines the control function to be performed as
       described below.	The arg	 argument  represents  additional  information
       that  is	 needed	by this	command. The type of arg depends upon the com-
       mand, but it is generally an integer or a pointer to a command-specific
       data  structure.	  The command and arg arguments	are interpreted	by the
       STREAM head. Certain combinations of these arguments may	be passed to a
       module or driver	in the stream.

       Since these STREAMS commands are	ioctls,	they are subject to the	errors
       described in ioctl(2).  In addition to those errors, the	call will fail
       with errno set to EINVAL, without processing a control function,	if the
       STREAM referenced by fildes is linked below a multiplexor, or  if  com-
       mand is not a valid value for a stream.

       Also,  as described in ioctl(2),	STREAMS	modules	and drivers can	detect
       errors. In this case, the module	or driver sends	an  error  message  to
       the  STREAM  head  containing  an  error	value.	This causes subsequent
       calls to	fail with errno	set to this value.

IOCTLS
       The following ioctl commands, with error	values indicated, are applica-
       ble 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. If	the STREAM  is
	     a	pipe,  the module will be inserted between the stream heads of
	     both ends of the pipe. It then calls  the	open  routine  of  the
	     newly-pushed  module. On failure, errno is	set to one of the fol-
	     lowing values:

	     EINVAL
		   Invalid module name.

	     EFAULT
		   arg points outside the allocated address space.

	     ENXIO Open	routine	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.  To remove a module from a pipe requires
	     that the module was pushed	on the side it is being	removed	 from.
	     arg should	be  0 in an I_POP request. On failure, errno is	set to
	     one of the	following values:

	     EINVAL
		   No module present in	the stream.

	     ENXIO Hangup received on fildes.

	     EPERM Attempt to  pop  through  an	 anchor	 by  an	 unpriviledged
		   process.

       I_ANCHOR
	     Positions	the stream anchor to be	at the STREAMS module directly
	     below the STREAM head. Once this has been done, only a privileged
	     process  may pop modules below the	anchor on the stream. arg must
	     be	0 in an	I_ANCHOR request. On failure, errno is set to the fol-
	     lowing value:

	     EINVAL
		   Request to put an anchor on a pipe.

       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  null	termi-
	     nated  character string pointed at	by arg.	 The buffer pointed to
	     by	arg should be at least FMNAMESZ+1 bytes	 long.	This  requires
	     the  declaration  #include	<sys/conf.h>. On failure, errno	is set
	     to	one of the following values:

	     EFAULT
		   arg points outside the allocated address space.

	     EINVAL
		   No module present in	stream.

       I_FLUSH
	     This request flushes all input and/or output queues, depending on
	     the value of arg. Legal arg values	are:

	     FLUSHR
		   Flush read queues.

	     FLUSHW
		   Flush write queues.

	     FLUSHRW
		   Flush read and write	queues.

       If  a  pipe or FIFO does	not have any modules pushed, the read queue of
       the STREAM head on either end is	flushed	depending on the value of arg.

       If FLUSHR is set	and fildes is a	pipe, the read queue for that  end  of
       the  pipe  is flushed and the write queue for the other end is flushed.
       If fildes is a FIFO, both queues	are flushed.

       If FLUSHW is set	and fildes is a	pipe and the other end of the pipe ex-
       ists,  the  read	queue for the other end	of the pipe is flushed and the
       write queue for this end	is flushed. If fildes is a FIFO,  both	queues
       of the FIFO are flushed.

       If FLUSHRW is set, all read queues are flushed, that is,	the read queue
       for the FIFO and	the read queue on both ends of the pipe	are flushed.

       Correct flush handling of  a  pipe  or  FIFO  with  modules  pushed  is
       achieved	 via the pipemod module.  This module should be	the first mod-
       ule pushed onto a pipe so that it is at the midpoint of	the  pipe  it-
       self.

	     On	failure, errno is set to one of	the following values:

	     ENOSR Unable  to allocate buffers for flush message due to	insuf-
		   ficient STREAMS memory resources.

	     EINVAL
		   Invalid arg value.

	     ENXIO Hangup received on fildes.

       I_FLUSHBAND
	     Flushes a particular band of messages. arg	points to  a  bandinfo
	     structure that has	the following members:

	     unsigned char bi_pri;
	     int bi_flag;

	     The bi_flag field may be one of FLUSHR, FLUSHW, or	FLUSHRW	as de-
	     scribed earlier.

       I_SETSIG
	     Informs the STREAM	head that the user wishes the kernel to	 issue
	     the  SIGPOLL  signal (see signal(3C)) 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  user
	     should  be	 signaled.  It is the bitwise OR of any	combination of
	     the following constants:

	     S_INPUT
		   Any message other than an M_PCPROTO has arrived on a	STREAM
		   head	read queue. This event is maintained for compatibility
		   with	previous releases. This	event is triggered even	if the
		   message is of zero length.

	     S_RDNORM
		   An  ordinary	(non-priority) message has arrived on a	STREAM
		   head	read queue. This event is triggered even if  the  mes-
		   sage	is of zero length.

	     S_RDBAND
		   A  priority band message (band > 0) has arrived on a	stream
		   head	read queue. This event is triggered even if  the  mes-
		   sage	is of zero length.

	     S_HIPRI
		   A  high priority message is present on the STREAM head read
		   queue. This event is	triggered even if the  message	is  of
		   zero	length.

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

	     S_WRNORM
		   This	event is the same as S_OUTPUT.

	     S_WRBAND
		   A priority band greater than	0 of a queue downstream	exists
		   and is writable.  This notifies the user that there is room
		   on  the  queue for sending (or writing) priority data down-
		   stream.

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

	     S_ERROR
		   An M_ERROR message has reached the STREAM head.

	     S_HANGUP
		   An M_HANGUP message 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.

       A user process may choose to be signaled	only of	high priority messages
       by setting the arg bitmask to the value S_HIPRI.

       Processes that wish to receive SIGPOLL signals must explicitly register
       to  receive  them  using	I_SETSIG. If several processes register	to re-
       ceive this signal for the same event on the same	stream,	 each  process
       will be signaled	when the event occurs.

	     If	the value of arg is zero, the calling process will be unregis-
	     tered and will not	receive	further	SIGPOLL	signals.  On  failure,
	     errno is set to one of the	following values:

	     EINVAL
		   arg value is	invalid	or arg is zero and process is not reg-
		   istered to receive the SIGPOLL signal.

	     EAGAIN
		   Allocation of a data	structure to store the signal  request
		   failed.

       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 pointed to by	arg, where the events are those	speci-
	     fied in the description of	I_SETSIG above.	On failure,  errno  is
	     set to one	of the following values:

	     EINVAL
		   Process not registered to receive the SIGPOLL signal.

	     EFAULT
		   arg points outside the allocated address space.

       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. It returns 0 if the named module	is not
	     present. On failure, errno	is set to one of the following values:

	     EFAULT
		   arg points outside the allocated address space.

	     EINVAL
		   arg does not	contain	a valid	module name.

       I_PEEK
	     Allows a user to retrieve the information in the first message on
	     the  STREAM  head	read  queue without taking the message off the
	     queue. I_PEEK is analogous	to getmsg(2) except that it  does  not
	     remove the	message	from the queue.	arg points to a	strpeek	struc-
	     ture, which contains the following	members:

	     struct strbuf ctlbuf;
	     struct strbuf  databuf;
	     long flags;

	     The maxlen	field in the ctlbuf and	databuf	strbuf structures (see
	     getmsg(2))	must be	set to the number of bytes of control informa-
	     tion and/or data information, respectively,  to  retrieve.	 flags
	     may be set	to RS_HIPRI or 0. If RS_HIPRI is set, I_PEEK will look
	     for a high	priority message on the	STREAM head read queue.	Other-
	     wise,  I_PEEK  will look for the first 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. 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.  On  failure,
	     errno is set to the following value:

	     EFAULT
		   arg	points,	 or  the  buffer  area	specified in ctlbuf or
		   databuf is, outside the allocated address space.

	     EBADMSG
		   Queued message to be	read is	not valid for I_PEEK.

	     EINVAL
		   Illegal value for flags.

       I_SRDOPT
	     Sets the read mode	(see read(2)) using the	value of the  argument
	     arg. Legal	arg values are:

	     RNORM Byte-stream mode, the default.

	     RMSGD Message-discard mode.

	     RMSGN Message-nondiscard mode.

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

	     RPROTNORM
		   Reject read() with EBADMSG if a control message is  at  the
		   front of the	STREAM head read queue.

	     RPROTDAT
		   Deliver  the	 control  portion  of a	message	as data	when a
		   user	issues read(). This is the default behavior.

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

	     On	failure, errno is set to the following value:

	     EINVAL
		   arg	is  not	 one  of the above legal values, or arg	is the
		   bitwise inclusive OR	of RMSGD and RMSGN.

       I_GRDOPT
	     Returns the current read mode setting in an int pointed to	by the
	     argument arg. Read	modes are described in read(). On failure, er-
	     rno is set	to the following value:

	     EFAULT
		   arg points outside the allocated address space.

       I_NREAD
	     Counts the	number of data bytes in	data blocks in the first  mes-
	     sage  on the STREAM head read queue, and places this value	in the
	     location pointed to by arg. The return value for the  command  is
	     the  number  of messages on the STREAM head read queue. For exam-
	     ple, if zero is returned in arg, but the ioctl  return  value  is
	     greater  than  zero, this indicates that a	zero-length message is
	     next on the queue.	On failure, errno  is  set  to	the  following
	     value:

	     EFAULT
		   arg points outside the allocated address space.

       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, which con-
	     tains the following members:

	     struct  strbuf  ctlbuf;
	     struct  strbuf databuf;
	     t_uscalar_t  flags;
	     int  fildes;
	     int  offset;

	     The len member in the ctlbuf  strbuf  structure  (see  putmsg(2))
	     must  be  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 offset from the start	of the control
	     buffer where I_FDINSERT will store	a  t_uscalar_t whose interpre-
	     tation  is	 specific  to  the  STREAM  end. The len member	in the
	     databuf strbuf structure must be 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-prior-
	     ity message is created if flags is	set to RS_HIPRI. For  non-pri-
	     ority  messages,  I_FDINSERT will 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_NDELAY  or  O_NONBLOCK is set. Instead, it fails	and sets errno
	     to	EAGAIN.

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

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

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

	     ENOSR Buffers  can	not be allocated for the message that is to be
		   created.

	     EFAULT
		   The arg argument points, or the buffer  area	 specified  in
		   ctlbuf or databuf is, outside the allocated address space.

	     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 ctlptr; the	offset
		   member  does	not specify a properly-aligned location	in the
		   data	buffer;	or an undefined	value is stored	in flags.

	     ENXIO Hangup received on the fildes argument of the ioctl call or
		   the fildes member of	the strfdinsert	structure.

	     ERANGE
		   The len field for the buffer	specified through databuf does
		   not fall within the range specified by the maximum and min-
		   imum	 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 mes-
		   sage; 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_FDINSERT	can also fail if an error message was received by  the
	     STREAM  head  of the STREAM corresponding to the fildes member of
	     the strfdinsert structure.	In this	case, errno will be set	to the
	     value in the 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	user ioctl requests  to	 down-
	     stream modules and	drivers. It allows information to be sent with
	     the ioctl,	and will return	to the user any	information  sent  up-
	     stream by the downstream recipient. I_STR blocks until the	system
	     responds with either a positive or	negative acknowledgement  mes-
	     sage, or until the	request	"times out" after some period of time.
	     If	the request times out, it fails	with errno set to ETIME.

	     To	send requests downstream, arg must point to a strioctl	struc-
	     ture which	contains the following members:

	     int  ic_cmd;
	     int  ic_timout;
	     int  ic_len;
	     char  *ic_dp;

	     ic_cmd  is	 the  internal ioctl command intended for a downstream
	     module or driver and ic_timout is the number of seconds (-1 = in-
	     finite, 0 = use default, >0 = as specified) an I_STR request will
	     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 field	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
	     user  (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).

	     At	most one I_STR can be active on	a stream.  Further I_STR calls
	     will block	until the active I_STR completes via  a	 positive   or
	     negative  acknowlegment,  a timeout, or an	error condition	at the
	     STREAM head.  By setting  the ic_timout
	      field  to	 0, the	 user is requesting STREAMS  to	 provide   the
	     "DEFAULT" timeout.	The default timeout is specific	to the STREAMS
	     implementation and	may vary depending on which release of Solaris
	     you  are using. For Solaris 8 (and	earlier	versions), the default
	     timeout is	fifteen	seconds.  The  O_NDELAY	 and  O_NONBLOCK  (see
	     open(2)) flags have no effect on this call.

	     The  STREAM  head	will convert the information pointed to	by the
	     strioctl structure	to an internal ioctl command message and  send
	     it	 downstream.  On failure, errno	is set to one of the following
	     values:

	     ENOSR Unable to allocate buffers for the ioctl message due	to in-
		   sufficient STREAMS memory resources.

	     EFAULT
		   Either  arg	points outside the allocated address space, or
		   the buffer area specified by	ic_dp and  ic_len  (separately
		   for	data  sent and data returned) is outside the allocated
		   address space.

	     EINVAL
		   ic_len is less than 0 or ic_len is 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 re-
		   ceived.

	     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  com-
	     mand sent downstream fails. For these cases, I_STR	will fail with
	     errno set to the value in the message.

       I_SWROPT
	     Sets the write mode using the value of the	 argument  arg.	 Legal
	     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,  this
       bit must	not be set in arg.

	     On	failure, errno may be set to the following value:

	     EINVAL
		   arg is not the above	legal 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
	     Requests the STREAM associated with fildes	 to  send  a  message,
	     containing	a file pointer,	to the stream head at the other	end of
	     a STREAM pipe. The	file pointer corresponds to arg, which must be
	     an	open file descriptor.

	     I_SENDFD converts arg into	the corresponding system file pointer.
	     It	allocates a message block and inserts the file pointer in  the
	     block.   The  user	 id  and  group	id associated with the sending
	     process are also inserted.	This message is	placed directly	on the
	     read  queue (see intro(3))	of the STREAM head at the other	end of
	     the STREAM	pipe to	which it is connected.
	      On failure, errno	is set to one of the following values:

	     EAGAIN
		   The sending STREAM is unable	to allocate a message block to
		   contain the file pointer.

	     EAGAIN
		   The	read  queue  of	 the receiving STREAM head is full and
		   cannot accept the message sent by I_SENDFD.

	     EBADF arg is not a	valid, open file descriptor.

	     EINVAL
		   fildes is not connected to a	STREAM pipe.

	     ENXIO Hangup received on fildes.

       I_RECVFD
	     Retrieves the file	descriptor associated with the message sent by
	     an	 I_SENDFD ioctl	over a STREAM pipe. arg	is a pointer to	a data
	     buffer large enough to hold an strrecvfd data structure  contain-
	     ing the following members:

	     int  fd;
	     uid_t  uid;
	     gid_t  gid;

	     fd	is an integer file descriptor. uid and gid are the user	id and
	     group id, respectively, of	the sending stream.

	     If	O_NDELAY and O_NONBLOCK	are clear (see open(2)), I_RECVFD will
	     block  until a message is present at the STREAM head. If O_NDELAY
	     or	O_NONBLOCK is set, I_RECVFD will 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 user file descriptor is allocated	for  the  file
	     pointer  contained	 in  the  message.  The	new file descriptor is
	     placed in the fd field of the strrecvfd structure.	The  structure
	     is	 copied	into the user data buffer pointed to by	arg.  On fail-
	     ure, errno	is set to one of the following values:

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

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

	     EFAULT
		   arg points outside the allocated address space.

	     EMFILE
		   NOFILES file	descriptors are	currently open.

	     ENXIO Hangup received on fildes.

	     EOVERFLOW
		   uid or gid is too large  to	be  stored  in	the  structure
		   pointed to by arg.

       I_LIST
	     Allows the	user to	list all the module names on the stream, up to
	     and including the topmost driver name. If arg is NULL, the	return
	     value is the number of modules, including the driver, that	are on
	     the STREAM	pointed	to by fildes. This allows the user to allocate
	     enough  space for the module names. If arg	is non-null, it	should
	     point to an str_list structure that has the following members:

	     int sl_nmods;
	     struct  str_mlist	*sl_modlist;

	     The str_mlist structure has the following member:

       char l_name[FMNAMESZ+1];

	      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	contains 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() is 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. On failure,	errno may be set to one	of the follow-
	      ing values:

	      EINVAL
		    The	sl_nmods member	is less	than 1.

	      EAGAIN
		    Unable to allocate buffers

       I_ATMARK
	     Allows the	user to	see if the current message on the stream  head
	     read  queue  is  ``marked'' by some module	downstream. arg	deter-
	     mines how the checking is done when there may be multiple	marked
	     messages on the STREAM head read queue. It	may take the following
	     values:

	     ANYMARK
		   Check if the	message	is marked.

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

	     The return	value is 1 if the mark condition is  satisfied	and  0
	     otherwise.	On failure, errno is set to the	following value:

	     EINVAL
		   Invalid arg value.

       I_CKBAND
	     Check  if	the  message  of  a  given priority band exists	on the
	     stream head read queue. This returns 1 if a message  of  a	 given
	     priority exists, 0	if not,	or -1 on error.	arg should be an inte-
	     ger containing the	value of the priority  band  in	 question.  On
	     failure, errno is set to the following value:

	     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.  On  failure,	 errno
	     is	set to the following value:

	     ENODATA
		   No message on the STREAM head read queue.

       I_CANPUT
	     Check  if	a certain band is writable. arg	is set to the priority
	     band in question. The return value	is 0 if	the priority band  arg
	     is	 flow  controlled,  1 if the band is writable, or -1 on	error.
	     On	failure, errno is set to the following value:

	     EINVAL
		   Invalid arg value.

       I_SETCLTIME
	     Allows the	user to	set the	time the STREAM	head will delay	when a
	     stream is closing and there are data on the write queues.
	      Before  closing each module and driver, the STREAM head will de-
	     lay for the specified amount of time to allow the data to	drain.
	     Note,  however, that the module or	driver may itself delay	in its
	     close routine; this delay is independent of the STREAM head's de-
	     lay  and  is  not	settable.  If, after the delay,	data are still
	     present, data will	be flushed. arg	is the number of  milliseconds
	     to	 delay,	 rounded  up to	the nearest legal value	on the system.
	     The default is fifteen seconds. On	failure, errno is set  to  the
	     following value:

	     EINVAL
		   Invalid arg value.

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

       I_SERROPT
	     Sets the error mode using the value of the	argument arg.

	     Normally STREAM head errors are persistent; once they are set due
	     to	an M_ERROR or M_HANGUP,	the error condition will remain	 until
	     the  STREAM is closed.  This option can be	used to	set the	STREAM
	     head into non-persistent error mode i.e. once the error has  been
	     returned	in   response  to  a  read(2),	getmsg(2),   ioctl(2),
	     write(2), or  putmsg(2) call the error condition will be cleared.
	     The error mode can	be controlled independently for	read and write
	     side errors. Legal	arg values are either none or one of:

	     RERRNORM
		   Persistent read errors, the default.

	     RERRNONPERSIST
		   Non-persistent read errors.

       OR'ed with either none or one of:

	     WERRNORM
		   Persistent write errors, the	default.

	     WERRNONPERSIST
		   Non-persistent write	errors.

		   When	no value is specified e.g. for the read	side error be-
		   havior  then	 the  behavior	for that side will be left un-
		   changed.

	     On	failure, errno is set to the following value:

	     EINVAL
		   arg is not one of the above legal values.

       I_GERROPT
	     Returns the current error mode setting in an int  pointed	to  by
	     the  argument arg.	Error modes are	described above	for I_SERROPT.
	     On	failure,errno is set to	the following value:

	     EFAULT
		   arg points outside the allocated address space.

       The following four commands are used for	connecting  and	 disconnecting
       multiplexed STREAMS configurations.

       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 gets connected below the	 multiplexing  driver.
	     I_LINK  requires  the multiplexing	driver to send an acknowledge-
	     ment message to the STREAM	head regarding the linking  operation.
	     This  call	returns	a multiplexor ID number	(an identifier used to
	     disconnect	the multiplexor, see I_UNLINK) on success, and	-1  on
	     failure. On failure, errno	is set to one of the following values:

	     ENXIO Hangup received on fildes.

	     ETIME Time	 out  before  acknowledgement  message was received at
		   STREAM head.

	     EAGAIN
		   Temporarily unable  to  allocate  storage  to  perform  the
		   I_LINK.

	     ENOSR Unable to allocate storage to perform the I_LINK due	to in-
		   sufficient STREAMS memory resources.

	     EBADF arg is not a	valid, open file descriptor.

	     EINVAL
		   fildes STREAM does not support multiplexing.

	     EINVAL
		   arg is not a	stream,	or is already linked  under  a	multi-
		   plexor.

	     EINVAL
		   The specified link operation	would cause a ``cycle''	in the
		   resulting configuration; that is, a driver would be	linked
		   into	the multiplexing configuration in more than one	place.

	     EINVAL
		   fildes is the file descriptor of a pipe or FIFO.

	     EINVAL
		   Either  the upper or	lower stream has a major number	>= the
		   maximum major number	on the system.

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

       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. arg is	the multiplexor	ID number that was returned by
	     the I_LINK. If arg	is -1, then all	streams	that  were  linked  to
	     fildes are	disconnected.  As in I_LINK, this command requires the
	     multiplexing driver to acknowledge	the unlink. On failure,	 errno
	     is	set to one of the following values:

	     ENXIO Hangup received on fildes.

	     ETIME Time	 out  before  acknowledgement  message was received at
		   STREAM head.

	     ENOSR Unable to allocate storage to perform the I_UNLINK  due  to
		   insufficient	STREAMS	memory resources.

	     EINVAL
		   arg	is  an	invalid	multiplexor ID number or fildes	is not
		   the STREAM on which the I_LINK that returned	arg  was  per-
		   formed.

	     EINVAL
		   fildes is the file descriptor of a pipe or FIFO.

	     An	  I_UNLINK  can	 also  fail while waiting for the multiplexing
	     driver to acknowledge the link 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	 nega-
	     tive  acknowledgement  message.   For these cases,	 I_UNLINK will
	     fail with errno set to the	value in the message.

       I_PLINK
	     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	gets connected via a persistent	link below the
	     multiplexing driver. I_PLINK requires the multiplexing driver  to
	     send  an acknowledgement message to the STREAM head regarding the
	     linking operation.	This call creates a persistent link that  con-
	     tinues  to	 exist	even  if the file descriptor fildes associated
	     with the upper STREAM to the multiplexing driver is closed.  This
	     call  returns  a multiplexor ID number (an	identifier that	may be
	     used to disconnect	the multiplexor, see  I_PUNLINK)  on  success,
	     and -1 on failure.	On failure, errno is set to one	of the follow-
	     ing values:

	     ENXIO Hangup received on fildes.

	     ETIME Time	out before acknowledgement message was received	at the
		   STREAM head.

	     EAGAIN
		   Unable to allocate STREAMS storage to perform the  I_PLINK.

	     EBADF arg is not a	valid, open file descriptor.

	     EINVAL
		   fildes does not support multiplexing.

	     EINVAL
		   arg	is  not	 a  STREAM or is already linked	under a	multi-
		   plexor.

	     EINVAL
		   The specified link operation	would cause a ``cycle''	in the
		   resulting  configuration;  that  is,	 if  a driver would be
		   linked into the multiplexing	configuration in more than one
		   place.

	     EINVAL
		   fildes is the file descriptor of a pipe or FIFO.

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

       I_PUNLINK
	     Disconnects the two streams specified by fildes and arg that  are
	     connected	with  a	persistent link. fildes	is the file descriptor
	     of	the STREAM connected to	the multiplexing driver.  arg  is  the
	     multiplexor  ID number that was returned by I_PLINK when a	STREAM
	     was linked	below the multiplexing driver.	If arg	is   MUXID_ALL
	     then  all streams that are	persistent links to fildes are discon-
	     nected. As	in  I_PLINK, this command  requires  the  multiplexing
	     driver to acknowledge the unlink. On failure, errno is set	to one
	     of	the following values:

	     ENXIO Hangup received on fildes.

	     ETIME Time	out before acknowledgement message was received	at the
		   STREAM head.

	     EAGAIN
		   Unable to allocate buffers for the acknowledgement message.

	     EINVAL
		   Invalid multiplexor ID number.

	     EINVAL
		   fildes is the file descriptor of a pipe or FIFO.

	     An	 I_PUNLINK  can	 also  fail while waiting for the multiplexing
	     driver to acknowledge the link 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	 nega-
	     tive  acknowledgement  message.   For these cases,	I_PUNLINK will
	     fail with errno set to the	value in the message.

RETURN VALUES
       Unless specified	otherwise above, the return value from	ioctl()	 is  0
       upon success and	 -1 upon failure, with errno set as indicated.

SEE ALSO
       intro(3),  close(2),  fcntl(2),	getmsg(2), ioctl(2), open(2), poll(2),
       putmsg(2), read(2), write(2), signal(3C), signal(3HEAD),

       STREAMS Programming Guide

SunOS 5.9			  19 Apr 1999			  streamio(7I)

NAME | SYNOPSIS | DESCRIPTION | IOCTLS | RETURN VALUES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=streamio&sektion=7i&manpath=SunOS+5.9>

home | help