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

FreeBSD Manual Pages

  
 
  

home | help
STREAMIO(4)		   Kernel Interfaces Manual		   STREAMIO(4)

NAME
       streamio	- STREAMS ioctl	commands

SYNOPSIS
       #include	<stropts.h>
       int ioctl (fd, command, arg)
       int fd, command;

DESCRIPTION
       STREAMS (see intro(2)) ioctl commands are a subset of ioctl(2) commands
       that perform a variety of control functions on STREAMS.	The  arguments
       command	and arg	are passed to the file designated by fd	and are	inter-
       preted by the streamhead.  Certain combinations of these	arguments  may
       be passed to a module or	driver in the stream.

       fd  is an open file descriptor that refers to a stream.	command	deter-
       mines the control function to be	performed  as  described  below.   arg
       represents  additional information that is needed by this command.  The
       type of arg depends upon	the command, but it is generally an integer or
       a pointer to a command-specific data structure.

       Since these STREAMS commands are	a subset of ioctl, they	are subject to
       the errors described there.  In addition	to those errors, the call will
       fail  with  errno set to	EINVAL,	without	processing a control function,
       if the stream referenced	by fd is linked	below  a  multiplexor,	or  if
       command is not a	valid value for	a stream.

       Also, as	described in ioctl, STREAMS modules and	drivers	can detect er-
       rors.  In this case, the	module or driver sends an error	message	to the
       stream  head  containing	 an error value.  Subsequent system calls will
       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
			   streamhead.	 It then calls the open	routine	of the
			   newly-pushed	module.

			   I_PUSH will fail if one of the following occurs:

			   EINVAL	       The module name is invalid.

			   EFAULT	       arg points  outside  the	 allo-
					       cated address space.

			   ENXIO	       The  open  routine  of  the new
					       module failed.

			   ENXIO	       A hangup	 is  received  on  the
					       stream referred to by fd.

       I_POP		   Removes  the	 module	 just below the	stream head of
			   the stream pointed to by fd.	 arg should be 0 in an
			   I_POP request.

			   I_POP will fail if one of the following occurs:

			   EINVAL	       No module is present on stream.

			   ENXIO	       A  hangup  is  received	on the
					       stream referred to by fd.

       I_LOOK		   Retrieves the name of the  module  just  below  the
			   stream  head	 of  the  stream pointed to by fd, 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.  An `#in-
			   clude <sys/conf.h>' declaration is required.

			   I_LOOK will fail if one of the following occurs:

			   EFAULT	       arg  points  outside  the allo-
					       cated  address  space  of   the
					       process.

			   EINVAL	       No module is present on 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.

			   I_FLUSH will	fail if	one of the following occurs:

			   EAGAIN	       No  buffers  could be allocated
					       for the flush message.

			   EINVAL	       The value of arg	is invalid.

			   ENXIO	       A hangup	 is  received  on  the
					       stream referred to by fd.

       I_SETSIG		   Informs  the	 stream	 head that the user wishes the
			   kernel to issue the SIGPOLL signal (see  sigvec(2))
			   when	 a particular event has	occurred on the	stream
			   associated with fd.	I_SETSIG supports an asynchro-
			   nous	 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 bit-
			   wise-OR of any combination of  the  following  con-
			   stants:

			   S_INPUT	       A  non-priority message has ar-
					       rived on	 a  stream  head  read
					       queue,  and  no	other messages
					       existed on  that	 queue	before
					       this  message was placed	there.
					       This is set even	if the message
					       is of zero length.

			   S_HIPRI	       A  priority  message is present
					       on the stream head read	queue.
					       This is set 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 down-
					       stream.

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

			   A user process may choose to	be  signaled  only  of
			   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 receive this  sig-
			   nal	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.

			   I_SETSIG will fail if one of	the following occurs:

			   EINVAL	       The value of arg	is invalid  or
					       arg  is zero and	the process is
					       not registered to  receive  the
					       SIGPOLL signal.

			   EAGAIN	       A  data	structure could	not be
					       allocated 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 pointed to by
			   arg,	where the events are those  specified  in  the
			   description of I_SETSIG above.

			   I_GETSIG will fail if one of	the following occurs:

			   EINVAL	       The  process  is	not registered
					       to receive the SIGPOLL signal.

			   EFAULT	       arg points  outside  the	 allo-
					       cated   address	space  of  the
					       process.

       I_FIND		   This	request	compares the names of all modules cur-
			   rently 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.

			   I_FIND will fail if one of the following occurs:

			   EFAULT	       arg points  outside  the	 allo-
					       cated   address	space  of  the
					       process.

			   EINVAL	       arg does	not point to  a	 valid
					       module name.

       I_PEEK		   This	request	allows a user to retrieve the informa-
			   tion	in the first message on	the stream  head  read
			   queue  without  taking  the	message	off 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  num-
			   ber of bytes	of control information and/or data in-
			   formation, respectively, to retrieve.  If the  user
			   sets	flags to RS_HIPRI, I_PEEK will only look for a
			   priority message on the stream head read queue.

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

			   I_PEEK will fail if one of the following occurs:

			   EFAULT	       arg points, or the buffer  area
					       specified  in ctlbuf or databuf
					       is, outside the	allocated  ad-
					       dress space of the process.

       I_SRDOPT		   Sets	 the read mode 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.

			   Read	modes are described in read(2V).

			   I_SRDOPT will fail if one of	the following occurs:

			   EINVAL	       arg is not one of the above le-
					       gal values.

       I_GRDOPT		   Returns  the	 current  read	mode setting in	an int
			   pointed to by the argument arg.  Read modes are de-
			   scribed in read(2V).

			   I_GRDOPT will fail if one of	the following occurs:

			   EFAULT	       arg  points  outside  the allo-
					       cated  address  space  of   the
					       process.

       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 return value for the command is the  num-
			   ber of messages on the stream head read queue.  For
			   example, 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.

			   I_NREAD will	fail if	one of the following occurs:

			   EFAULT	       arg points  outside  the	 allo-
					       cated   address	space  of  the
					       process.

       I_FDINSERT	   creates a message from  user	 specified  buffer(s),
			   adds	information about another stream and sends the
			   message downstream.	The message contains a control
			   part	 and an	optional data part.  The data and con-
			   trol	parts to be sent are distinguished  by	place-
			   ment	in separate buffers, as	described below.

			   arg	points	to  a strfdinsert structure which con-
			   tains the following members:

				struct strbuf  ctlbuf;
				struct strbuf  databuf;
				long	  flags;
				int	  fd;
				int	  offset;

			   The len field in the	ctlbuf strbuf  structure  (see
			   putmsg(2))  must  be	 set  to the size of a pointer
			   plus	the number of bytes of control information  to
			   be  sent  with  the message.	 fd specifies the file
			   descriptor of the other stream  and	offset,	 which
			   must	be word-aligned, specifies the number of bytes
			   beyond the beginning	of the	control	 buffer	 where
			   I_FDINSERT  will store a pointer to the fd stream's
			   driver read queue structure.	 The len field in  the
			   databuf  strbuf structure must be set to the	number
			   of bytes of data information	to be  sent  with  the
			   message or zero if no data part is to be sent.

			   flags  specifies the	type of	message	to be created.
			   A non-priority message is created if	flags  is  set
			   to 0, and a 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 internal	flow control conditions.   For
			   priority  messages,	I_FDINSERT  does  not block on
			   this	condition.  For	non-priority messages, I_FDIN-
			   SERT	 does  not  block when the write queue is full
			   and O_NDELAY	is set.	 Instead, it  fails  and  sets
			   errno to EAGAIN.

			   I_FDINSERT also blocks, unless prevented by lack of
			   internal resources, waiting for the availability of
			   message  blocks in the stream, regardless of	prior-
			   ity or whether O_NDELAY  has	 been  specified.   No
			   partial message is sent.

			   I_FDINSERT  will  fail  if one of the following oc-
			   curs:

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

			   EAGAIN	       Buffers could not be  allocated
					       for  the	message	that was to be
					       created.

			   EFAULT	       arg points, or the buffer  area
					       specified  in ctlbuf or databuf
					       is, outside the	allocated  ad-
					       dress space of the process.

			   EINVAL	       fd in the strfdinsert structure
					       is not  a  valid,  open	stream
					       file  descriptor; the size of a
					       pointer plus offset is  greater
					       than the	len field for the buf-
					       fer specified  through  ctlptr;
					       offset does not specify a prop-
					       erly-aligned  location  in  the
					       data buffer; an undefined value
					       is pointed to by	flags.

			   ENXIO	       A hangup	 is  received  on  the
					       stream referred to by fd.

			   ERANGE	       The  len	 field	for the	buffer
					       specified through databuf  does
					       not fall	within the range spec-
					       ified by	the maximum and	 mini-
					       mum packet sizes	of the topmost
					       stream module, or the len field
					       for    the   buffer   specified
					       through databuf is larger  than
					       the  maximum configured size of
					       the data	part of	a message,  or
					       the  len	 field	for the	buffer
					       specified  through  ctlbuf   is
					       larger than the maximum config-
					       ured 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 permit a process to
			   specify timeouts and	variable-sized amounts of data
			   when	sending	an ioctl request to downstream modules
			   and drivers.	 It allows information to be sent with
			   the ioctl, and will return to the user any informa-
			   tion	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.

			   At most, one	I_STR can be active on a stream.  Fur-
			   ther	I_STR calls will block until the active	 I_STR
			   completes  at the stream head.  The default timeout
			   interval for	these requests	is  15	seconds.   The
			   O_NDELAY  (see open(2V)) flag has no	effect on this
			   call.

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

				int  ic_cmd;	    /* downstream command */
				int  ic_timout;	    /* ACK/NAK timeout */
				int  ic_len;	    /* length of data arg */
				char *ic_dp;	    /* ptr to data arg */

			   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
			   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 re-
			   turned 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).

			   The	 stream	 head  will  convert  the  information
			   pointed to by the strioctl structure	to an internal
			   ioctl command message and send it downstream.

			   I_STR will fail if one of the following occurs:

			   EAGAIN	       Buffers	could not be allocated
					       for the ioctl message.

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

			   EINVAL	       ic_len is less than 0 or	ic_len
					       is larger than the maximum con-
					       figured	size  of the data part
					       of a message  or	 ic_timout  is
					       less than -1.

			   ENXIO	       A  hangup  is  received	on the
					       stream referred to by fd.

			   ETIME	       A downstream  ioctl  timed  out
					       before  acknowledgement was re-
					       ceived.

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

       I_SENDFD		   Requests  the  stream  associated with fd 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	 inte-
			   ger file descriptor.

			   I_SENDFD converts arg into the corresponding	system
			   file	pointer.  It allocates a message block and in-
			   serts  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(2)) of the stream head
			   at  the other end of	the stream pipe	to which it is
			   connected.

			   I_SENDFD will fail if one of	the following occurs:

			   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	       fd is not connected to a	stream
					       pipe.

			   ENXIO	       A  hangup  is  received	on the
					       stream referred to by fd.

       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;
				unsigned short uid;
				unsigned short gid;
				char fill[8];

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

			   If O_NDELAY is not  set  (see  open(2V)),  I_RECVFD
			   will	 block	until  a  message  is  present	at the
			   streamhead.	If O_NDELAY is set, I_RECVFD will fail
			   with	 errno	set to EAGAIN if no message is present
			   at the streamhead.

			   If the message at the stream	head is	a message sent
			   by an I_SENDFD, a new user file descriptor is allo-
			   cated for the file pointer contained	 in  the  mes-
			   sage.   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.

			   I_RECVFD will fail if one of	the following occurs:

			   EAGAIN	       A  message  was	not present at
					       the stream head read queue, and
					       the O_NDELAY flag is set.

			   EBADMSG	       The  message at the stream head
					       read queue was  not  a  message
					       containing  a  passed  file de-
					       scriptor.

			   EFAULT	       arg points  outside  the	 allo-
					       cated   address	space  of  the
					       process.

			   EMFILE	       Too many	 descriptors  are  ac-
					       tive.

			   ENXIO	       A  hangup  is  received	on the
					       stream referred to by fd.

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

       I_LINK		   Connects two	streams, where fd 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	multi-
			   plexing driver.   I_LINK  causes  the  multiplexing
			   driver  to  send  an	acknowledgement	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 a -1	on failure.

			   I_LINK will fail if one of the following occurs:

			   ENXIO	       A  hangup  is  received	on the
					       stream referred to by fd.

			   ETIME	       The ioctl timed out  before  an
					       acknowledgement was received.

			   EAGAIN	       Storage	could not be allocated
					       to perform the I_LINK.

			   EBADF	       arg is not a valid,  open  file
					       descriptor.

			   EINVAL	       The  stream  referred  to by fd
					       does not	support	multiplexing.

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

			   EINVAL	       The  specified  link  operation
					       would  cause  a	"cycle"	in the
					       resulting  configuration;  that
					       is,  if	a given	stream head is
					       linked into a multiplexing con-
					       figuration  in  more  than  one
					       place.

			   An I_LINK can also fail while waiting for the  mul-
			   tiplexing  driver  to acknowledge the link request,
			   if a	message	indicating an error or a hangup	is re-
			   ceived  at  the stream head of fd.  In addition, an
			   error code can be returned in the positive or nega-
			   tive	 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	fd and
			   arg.	 fd is the file	descriptor of the stream  con-
			   nected to the multiplexing driver.  arg is the mul-
			   tiplexor ID number that was returned	by  the	 ioctl
			   I_LINK  command  when a stream was linked below the
			   multiplexing	 driver.   If  arg  is	-1,  then  all
			   streams  which  were	linked to fd are disconnected.
			   As in I_LINK, this command requires the  multiplex-
			   ing driver to acknowledge the unlink.

			   I_UNLINK will fail if one of	the following occurs:

			   ENXIO	       A  hangup  is  received	on the
					       stream referred to by fd.

			   ETIME	       The ioctl timed out  before  an
					       acknowledgement was received.

			   EAGAIN	       Buffers	could not be allocated
					       for  the	 acknowledgement  mes-
					       sage.

			   EINVAL	       The  multiplexor	 ID number was
					       invalid.

			   An I_UNLINK can also	fail  while  waiting  for  the
			   multiplexing	 driver	 to  acknowledge  the link re-
			   quest, if a message indicating an error or a	hangup
			   is received at the stream head of fd.  In addition,
			   an error code can be	returned in  the  positive  or
			   negative acknowledgement message.  For these	cases,
			   I_UNLINK will fail with errno set to	the  value  in
			   the message.

SEE ALSO
       close(2V), fcntl(2V), getmsg(2),	intro(2), ioctl(2), open(2V), poll(2),
       putmsg(2), read(2V), sigvec(2), write(2V)

       STREAMS Programmer's Guide
       STREAMS Primer

			       24 November 1987			   STREAMIO(4)

NAME | SYNOPSIS | DESCRIPTION | IOCTLS | SEE ALSO

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

home | help