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 in-
		       serted 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
		       following values:

		       EINVAL	       Invalid module name.

		       EFAULT	       arg  points  outside  the allocated ad-
				       dress space.

		       ENXIO	       Open routine of new module failed.

		       ENXIO	       Hangup received on fildes.

		       ENOTSUP	       Pushing a module	is  not	 supported  on
				       this stream.

       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 re-
		       quest. 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
				       unprivileged process.

		       ENOTSUP	       Removal is not supported.

       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 following
		       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 terminated 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  ad-
				       dress 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 exists, 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 module pushed onto	a pipe so that
		       it is at	the midpoint of	the pipe itself.

		       On failure, errno is set	to one of the  following  val-
		       ues:

		       ENOSR	       Unable  to  allocate  buffers for flush
				       message	due  to	 insufficient  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 described 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 process-
		       ing  capability	in STREAMS. The	value of arg is	a bit-
		       mask that specifies  the	 events	 for  which  the  user
		       should  be signaled. It is the bitwise OR of any	combi-
		       nation 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  compati-
				       bility  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
				       message 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
				       message 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 downstream.

		       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 ex-
		       plicitly	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 will be
		       signaled	when the event occurs.

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

		       EINVAL	       arg value is invalid or arg is zero and
				       process	is  not	 registered 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 specified 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 ad-
				       dress 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  re-
		       turns 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  ad-
				       dress 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  structure,
		       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 information 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  re-
		       turns 0 if no message was found on the STREAM head read
		       queue. It does not wait for a message to	arrive.	On re-
		       turn,  ctlbuf specifies information in the control buf-
		       fer, 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	speci-
				       fied  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.

		       RPROTNORM       Deliver the control portion of  a  mes-
				       sage as data when a user	issues read().
				       This is the default behavior.

		       RPROTDIS	       Discard the control portion of  a  mes-
				       sage, 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  val-
				       ues, 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,  errno  is  set  to	the  following
		       value:

		       EFAULT	       arg  points  outside  the allocated ad-
				       dress space.

       I_NREAD	       Counts the number of data bytes in data blocks  in  the
		       first message on	the STREAM head	read queue, and	places
		       this value in the location pointed to by	arg.  The  re-
		       turn value for the command is the number	of messages on
		       the STREAM head read queue. For example,	if zero	is re-
		       turned  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 fol-
		       lowing value:

		       EFAULT	       arg points outside  the	allocated  ad-
				       dress space.

       I_FDINSERT      Creates a message from specified	buffer(s), adds	infor-
		       mation about another STREAM and sends the message down-
		       stream.	The message contains a control part and	an op-
		       tional 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 contains 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_us-
		       calar_t	whose interpretation 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-priority	message	is created if flags is
		       set to RS_HIPRI.	For non-priority messages,  I_FDINSERT
		       will block if the STREAM	write queue is full due	to in-
		       ternal 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 in-
		       ternal  resources, waiting for the availability of mes-
		       sage 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_NONBLOCK 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 prop-
				       erly-aligned location in	the data  buf-
				       fer; 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
				       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_FDINSERT  can	also  fail if an error message was re-
		       ceived 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  mes-
		       sage.

       I_STR		Constructs  an internal	STREAMS	ioctl message from the
		       data pointed to by arg, and sends  that	message	 down-
		       stream.

		       This  mechanism is provided to send user	ioctl requests
		       to downstream modules and drivers. It  allows  informa-
		       tion  to	be sent	with the ioctl,	and will return	to the
		       user any	information sent upstream  by  the  downstream
		       recipient.  I_STR blocks	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 fails	with errno set
		       to ETIME.

		       To  send	requests downstream, arg must point to a stri-
		       octl structure 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 =	infinite, 0 = use  default,  >0	 =  as
		       specified)  an I_STR request will wait for acknowledge-
		       ment 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  de-
		       fault  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  insufficient
				       STREAMS memory resources.

		       EFAULT	       Either arg points outside the allocated
				       address space, or the buffer area spec-
				       ified 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 ac-
				       knowledgement was received.

		       An I_STR	can also fail while waiting  for  an  acknowl-
		       edgement	 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 ac-
		       knowledgement message, in the event the	ioctl  command
		       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 descrip-
		       tor.

		       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  in-
		       serted.	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	 allo-
				       cate  a	message	 block	to contain the
				       file pointer.

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

		       EBADF	       arg is not a valid, open	file  descrip-
				       tor.

		       EINVAL	       fildes  is  not	connected  to a	STREAM
				       pipe.

		       ENXIO	       Hangup received on fildes.

       I_RECVFD	       Retrieves the file descriptor associated	with the  mes-
		       sage  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 containing the	following mem-
		       bers:

		       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 str-
		       recvfd structure. The structure is copied into the user
		       data buffer pointed to by arg. On failure, 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  ad-
				       dress 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 fol-
		       lowing 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	 down-
		       stream  until  either the end of	the STREAM is reached,
		       or the number of	requested modules (sl_nmods) is	satis-
		       fied.  On  failure, errno may be	set to one of the fol-
		       lowing 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 determines how  the  checking  is  done
		       when  there  may	 be  multiple  marked  messages	on the
		       STREAM head read	queue. It may take the following  val-
		       ues:

		       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	satis-
		       fied  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 integer 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 delay for the specified
		       amount of time to allow the data	to drain.  Note,  how-
		       ever, that the module or	driver may itself delay	in its
		       close routine; this delay is independent	of the	STREAM
		       head's  delay and is not	settable. If, after the	delay,
		       data are	still present, data will be flushed. arg is  a
		       pointer	to  an	integer	 containing the	number of mil-
		       liseconds 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	condi-
		       tion will remain	until the STREAM is closed.  This  op-
		       tion  can  be used to set the STREAM head into non-per-
		       sistent error mode i.e. once the	 error	has  been  re-
		       turned  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 indepen-
		       dently for read and write side errors. Legal arg	values
		       are either none or one of:

		       RERRNORM		       Persistent read errors, the de-
					       fault.

		       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	behav-
					       ior  then the behavior for that
					       side will be left unchanged.

		       On failure, errno is set	to the following value:

		       EINVAL	       arg is not one of the above legal  val-
				       ues.

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

		       EFAULT	       arg points outside  the	allocated  ad-
				       dress space.

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

       I_LINK	       Connects	two streams, where fildes is the file descrip-
		       tor 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  re-
		       quires  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 insufficient STREAMS
				       memory resources.

		       EBADF	       arg is not a valid, open	file  descrip-
				       tor.

		       EINVAL	       fildes  STREAM  does not	support	multi-
				       plexing.

		       EINVAL	       arg is not  a  stream,  or  is  already
				       linked under a multiplexor.

		       EINVAL	       The   specified	link  operation	 would
				       cause a ``cycle'' in the	resulting con-
				       figuration;  that is, a driver would be
				       linked into the multiplexing configura-
				       tion 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 num-
				       ber on the system.

		       An I_LINK can also fail while waiting  for  the	multi-
		       plexing	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  negative  acknowl-
		       edgement	 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 con-
		       nected to the multiplexing driver. arg  is  the	multi-
		       plexor  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	multi-
		       plexing	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  negative  acknowl-
		       edgement	 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 descrip-
		       tor 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  re-
		       garding the linking operation. This call	creates	a per-
		       sistent link that continues 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  suc-
		       cess,  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 the STREAM head.

		       EAGAIN	       Unable  to  allocate STREAMS storage to
				       perform the  I_PLINK.

		       EBADF	       arg is not a valid, open	file  descrip-
				       tor.

		       EINVAL	       fildes does not support multiplexing.

		       EINVAL	       arg  is	not  a	STREAM	or  is already
				       linked under a multiplexor.

		       EINVAL	       The  specified  link  operation	 would
				       cause a ``cycle'' in the	resulting con-
				       figuration; that	is, if a driver	 would
				       be linked into the multiplexing config-
				       uration 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	multi-
		       plexing 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 negative acknowl-
		       edgement	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 mul-
		       tiplexing 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  mul-
		       tiplexing 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 ac-
				       knowledgement 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	multi-
		       plexing 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 negative acknowl-
		       edgement	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.h(3HEAD),

       STREAMS Programming Guide

SunOS 5.10			  12 Dec 2003			  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.10>

home | help