unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 streamio(7)							 streamio(7)




 NAME
      streamio - STREAMS ioctl commands

 SYNOPSIS
      #include <&lt&lt&lt;sys/types.h>&gt&gt&gt;
      #include <&lt&lt&lt;stropts.h>&gt&gt&gt;

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

 DESCRIPTION
      STREAMS ioctl commands are a subset of the ioctl() system calls which
      perform a variety of control functions on streams.

      fildes is an open file descriptor that refers to a stream.  command
      determines 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.  The
      command and arg 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 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 fildes 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
      errors. In this case, the module or driver sends an error message to
      the stream head containing an error value. This causes subsequent
      system calls to fail with errno set to this value.

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

	   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 are multiple marked messages on
			  the stream head read queue.  It may take the
			  following values:

			  ANYMARK	 Checks if the message is marked.

			  LASTMARK	 Checks if the message is the last
					 one that is marked on the queue.

			  If both ANYMARK and LASTMARK are set, ANYMARK
			  supersedes LASTMARK.




 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  The return value is 1 if the mark condition is
			  satisfied and 0 otherwise.

	   I_CANPUT	  Checks 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.

	   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,
			  or -1 on error. arg should be an integer
			  containing the value of the priority band in
			  question.

	   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 control parts to be sent are distinguished by
			  placement in separate buffers, as described below.

			  arg points to a strfdinsert structure which
			  contains the following members:

			       struct strbuf	  ctlbuf;
			       struct strbuf	  databuf;
			       long		  options;
			       int		  fildes;
			       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. fildes in the
			  strfdinsert structure specifies the file
			  descriptor of the other stream.  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.  This
			  pointer will be the address of the read queue
			  structure of the driver for the streams
			  corresponding to fildes in the strfdinsert
			  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.
			  An ordinary (non-priority) message is created if



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  flags is set to 0, a high priority message is
			  created if flags is set to RS_HIPRI.	For normal
			  messages, I_FDINSERT will block if the stream
			  write queue is full due to internal flow control
			  conditions.  For high priority messages,
			  I_FDINSERT does not block on this condition.	For
			  normal messages, I_FDINSERT does not block when
			  the write queue is full and the O_NONBLOCK is set.
			  Instead, it fails and sets errno to EAGAIN.

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

			  I_FDINSERT can also fail if an error message was
			  received by the stream head of the stream
			  corresponding to fildes in the strfdinsert
			  structure.  In this case, errno will be set to the
			  value in the message.

	   I_FIND	  Compares the names of all modules currently
			  present on the stream to the name specified in
			  arg.	The command returns a value of 1 if the
			  module is present and a value of 0 (zero) if the
			  module is not present.

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

			       FLUSHRW	      Flush write and read queues.

			       FLUSHW	      Flush write queues.

			       FLUSHR	      Flush read queues.

			  If a pipe or FIFO does not have any modules
			  pushed, the read queue of the streams 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



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  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 of boths ends of the pipe are flushed.

			  Correct flushing 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.

	   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_option;

			  The value of the bi_option field can be FLUSHR,
			  FLUSHW, or FLUSHRW as described for the I_FLUSH
			  command.

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

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

	   I_SETCLTIME	  Allows the user to set the time that the stream
			  head will delay when a stream is closing, and
			  there is 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.  If, after the delay, data is still
			  present, data will be flushed. arg is a pointer to
			  the number of milliseconds to delay, rounded up to
			  the nearest valid value on the system.  The
			  default is fifteen seconds.

	   I_GETSIG	  Returns the events for which the calling process
			  has registered to receive a SIGPOLL signal.
			  Events are returned as in arg bitmask as defined
			  for the I_SETSIG command.

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




 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




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

	   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
			  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 -1 on failure.

	   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 not NULL, it should point to a
			  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];

			  sl_nmods indicates the number of entries the user
			  has allocated in the array.  On success, the
			  return value is 0, sl_modlist contains the list of
			  module names, and sl_nmods indicates the number of
			  entries that have been filled in.

	   I_LOOK	  Retrieves the name of the module located just
			  below the streams 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 FNAMESZ+1
			  bytes long.  A #include <&lt&lt&lt;stropts.h>&gt&gt&gt; declaration is
			  required.

	   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



 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  number 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_PEEK	  Allows the user process to look (peek) at the
			  contents of the first message on the stream head
			  read queue.  This is done without taking the
			  message off the queue.  The I_PEEK ioctl operates
			  the same way as the getmsg() function, except that
			  it does not remove the message.  The arg parameter
			  points to a strpeek structure (in the <&lt&lt&lt;stropts.h>&gt&gt&gt;
			  header file) with the following members:

			       struct strbuf	 ctlbuf;
			       struct strbuf	 databuf;
			       long		options;

			  The strbuf structure pointed to by ctlbuf and
			  databuf has the following members:

			       int   maxlen;
			       int   len;
			       char  *buf

			  The maxlen field of the strbuf structure must
			  specify the number of bytes of control or data
			  information to be retrieved.	The options field
			  can be set to RS_HIPRI or 0 (zero).  If this field
			  is set to RS_HIPRI, the I_PEEK ioctl looks for a
			  high priority message on the queue.  If the field
			  is set to 0, the I_PEEK ioctl looks at the first
			  message on the queue.

			  The I_PEEK returns a 1 if a message was retrieved,
			  and returns a value of 0 (zero) if no message was
			  found; it does not wait for a message.  Upon
			  successful completion, ctlbuf specifies control
			  information in the control buffer, databuf
			  specifies data information in the data buffer, and
			  options contains RS_HIPRI or 0 (zero).

	   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



 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  message to the stream head regarding the linking
			  operation.  This call creates a persistent link
			  which can exist even if the file descriptor
			  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.

			  The I_PLINK ioctl can also fail if it is waiting
			  for the multiplexing driver to acknowledge the
			  link request and an error (M_ERROR) message, or
			  hangup (M_HANGUP) message is received at the
			  stream head for fildes.  In addition, an error can
			  be returned in an M_IOACK or M_IONAK message.
			  When these occur, the I_PLINK fails with errno set
			  to the value in the message.

	   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.

	   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
			  which are persistent links to fildes are
			  disconnected.	 As in I_PLINK, this command
			  requires the multiplexing driver to acknowledge
			  the unlink.

	   I_PUSH	  Pushes the module whose name is pointed 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 streams heads of both
			  ends of the pipe.  It then calls the open routine
			  of the newly-pushed module.

	   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 a strrecvfd data structure
			  containing the following members:

			       int	  fd;
			       uid_t	  uid;



 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			       gid_t	  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_NONBLOCK is clear, I_RECVFD will block until
			  a message is present at the stream head.  If
			  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 a 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.

	   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 of the stream head at
			  the other end of the stream pipe to which it is
			  connected.

	   I_SETCLTIME	  Lets the user process set the time that the stream
			  head delays when the stream is closing and the
			  write queues contain data.  The arg parameter
			  contains a pointer to the number of milliseconds
			  to delay, rounded up to the nearest legal value on
			  the system.  The default time is 15 seconds.

			  Before STREAMS modules and drivers are closed, the
			  stream head delays for the specified amount of
			  time.	 This allows the data on the write queues to
			  drain.  If data is still present on the writes
			  queues after the delay, the queues are flushed.

	   I_SETSIG	  Informs the stream head that the user wants the
			  kernel to issue the SIGPOLL signal (see signal(2))



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  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, except where
			  noted, of the following constants:

			       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.

			       S_ERROR	      An M_ERROR message has reached
					      the stream head.

			       S_HANGUP	      An M_HANGUP message has
					      reached the stream head.

			       S_HIPRI	      A high priority message is
					      present on the stream head
					      read queue.  This is set even
					      if the message is of zero
					      length.

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

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

			       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_RDBAND	      A priority band message (band
					      > 0) has arrived on a stream
					      head read queue.	This is set
					      even if the message is of



 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




					      zero-length.

			       S_RDNORM	      An ordinary (non-priority)
					      message has arrived on a
					      stream head read queue.  This
					      is set even if the message is
					      of zero-length.

			       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_WRNORM	      This event is the same as
					      S_OUTPUT.

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

			  Processes that want to receive SIGPOLL signals
			  must explicitly register to receive them using
			  I_SETSIG.  If several processes register to
			  receive the 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.

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

			       RNORM	      Byte-stream mode (default).

			       RMSGD	      Message-discard mode.

			       RMSGN	      Message-nondiscard mode.

			  Setting both RMSGD and RMSGN is an error. RMSGD
			  and RMSGN override NORM.

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





 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			       RPROTNORM      Fail read with EBADMSG if a
					      control message is at the
					      front of the stream head read
					      queue.  This is the default
					      behavior.

			       RPROTDAT	      Deliver the control portion of
					      a message as data when a user
					      issues read.

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

	   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 downstream modules and drivers.  It
			  allows information 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.

			  At most, one I_STR can be active on a stream.
			  Further I_STR calls will block until the active
			  I_STR completes at the stream head.  The default
			  timeout intervals for these requests is 15
			  seconds.  The O_NONBLOCK (see open(2)) flags have
			  no effect on this call.

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

			       int     ic_cmd;
			       int     ic_timeout;
			       int     ic_len;
			       char    *ic_dp;

			  ic_cmd is the internal ioctl command intended for
			  the downstream module or driver and ic_timeout is
			  the number of seconds (-1 =infinite, 0 = use
			  default, >0 = as specified) an I_STR request will
			  wait for acknowledgement before timing out. The



 Hewlett-Packard Company	   - 11 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




			  default timeout is infinite. 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 driver
			  in the stream can return).  The stream head will
			  convert the information pointed to by strioctl
			  structure to an internal ioctl command message and
			  send it downstream.

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

			       SNDZERO	      Sends 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.

	   I_UNLINK	  Disconnects the two streams specified by fildes
			  and arg.  fildes is the file descriptor of the
			  stream connected to the multiplexing driver. arg
			  is the multiplexor ID number that was returned by
			  the I_LINK.  If arg is MUXID_ALL, then all streams
			  which were linked to fildes are disconnected.	 As
			  in I_LINK, this command requires the multiplexing
			  driver to acknowledge the unlink.

 RETURN VALUE
      Unless specified differently for a command, the return value for a
      STREAMS ioctl() call is 0 (zero) on success and -1 (minus one) on
      failure.

 ERRORS
      A STREAMS ioctl command fails without performing the function and with
      errno set to [EINVAL] if:

	   +  The stream referred to by fildes is linked below a
	      multiplexing driver.

	   +  The command parameter is not a valid value for the stream.

      In addition, if any of the following conditions occur, the STREAMS
      ioctl commands return the corresponding value:





 Hewlett-Packard Company	   - 12 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




      I_ATMARK

	   [EINVAL]	  arg has an illegal value.

      I_CANPUT

	   [EINVAL]	  arg has an illegal value.

      I_CKBAND

	   [EINVAL]	  arg has an illegal value.

      I_FDINSERT

	   [EINVAL]	  The fildes parameter in the strfdinsert structure
			  is an invalid open file descriptor.

	   [EINVAL]	  The size of the pointer plus offset exceeds the
			  value of the len field for the buffer specified
			  through ctlptr.

	   [EINVAL]	  offset does not specify a properly aligned
			  location in the data buffer.

	   [EINVAL]	  options contains an undefined value.

	   [EFAULT]	  arg points, or ctrlbuf or databuf is outside the
			  allocated address space.

	   [EAGAIN]	  The ioctl request failed because a non-priority
			  message was to be created, the O_NONBLOCK option
			  was set, and the stream's write queue was full
			  because of internal flow control conditions.

	   [ENOSR]	  Buffers could not be allocated for the message
			  that was to be created due to insufficient STREAMS
			  memory resources.

	   [ENXIO]	  A hangup was received on the stream specified by
			  fildes in the I_FDINSERT ioctl call or on the
			  stream specified by fildes in the strfdinsert.

	   [ERANGE]	  The value of the len field for the buffer
			  specified through databuf does not fall within the
			  range for the minimum and maximum sizes of packets
			  for the top-most module on the stream.

	   [ERANGE]	  The value of the len field for the buffer
			  specified through databuf is larger than the
			  maximum allowable size for the data part of a
			  message.



 Hewlett-Packard Company	   - 13 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




	   [ERANGE]	  The value of the len field for the buffer
			  specified through ctlbuf is larger than the
			  maximum allowable size for the control part of a
			  message.

			  The I_FDINSERT ioctl can also fail if an error
			  (M_ERROR) message was received by the stream
			  specified by the fildes field in the strfdinsert
			  structure.  In this case, errno is set to the
			  error value in the error message.

      I_FIND

	   [EINVAL]	  arg does not contain a valid module name.

	   [EFAULT]	  arg points outside the allocated address space.

      I_FLUSH

	   [ENOSR]	  Could not allocate buffers for flush operation
			  because of a lack of STREAMS memory resources.

	   [EINVAL]	  The arg parameter is an invalid value.

	   [ENXIO]	  A hangup was received on fildes.

      I_FLUSHBAND

	   [EINVAL]	  The bi_pr parameter value exceeds the maximum
			  band, or the bi_option parameter is not FLUSHR,
			  FLUSHW, or FLUSHRW.

      I_GETBAND

	   [ENODATA]	  No message exists on the stream head read queue.

      I_GETSIG

	   [EINVAL]	  User process is not registered to receive the
			  SIGPOLL signal.

	   [EFAULT]	  arg points outside the allocated address space.

      I_GRDOPT

	   [EFAULT]	  arg is pointing outside the allocated address
			  space.

      I_LINK





 Hewlett-Packard Company	   - 14 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




	   [EAGAIN]	  Temporarily unable to allocate storage to perform
			  the linking operation.

	   [EBADF]	  The arg parameter not a valid open file
			  descriptor.

	   [ENXIO]	  A hangup was received on fildes.

	   [EINVAL]	  The stream referred to by fildes does not support
			  multiplexing.

	   [EINVAL]	  The file referred to by arg is not a stream, or
			  the stream is already linked under a multiplexor.

	   [EINVAL]	  The link operation would cause a "cycle" in the
			  resulting multiplexing configuration.	 In other
			  words, the driver referred to by the arg parameter
			  is linked into this configuration at multiple
			  places

	   [ENOSR]	  Not enough STREAMS memory resources to allocate
			  storage for this command.

	   [ETIME]	  Acknowledgement message not received at stream
			  head before timeout.

		The I_LINK ioctl can also fail if an M_ERROR or M_HANGUP
		message is received at the stream head for fildes before
		receiving the driver acknowledgement.  In addition, an error
		can be returned in an M_IOCACK or M_IOCNAK message.  When
		these occur, the I_LINK ioctl fails with errno set to the
		value in the message.

      I_LIST

	   [EINVAL]	  sl_nmods is less than 1.

	   [EAGAIN]	  Could not allocate buffers.

      I_LOOK

	   [EINVAL]	  There are no modules in the stream.

	   [EFAULT]	  arg points outside the allocated address space.

      I_NREAD

	   [EFAULT]	  arg is pointing outside the allocated address
			  space.





 Hewlett-Packard Company	   - 15 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




      I_PEEK

	   [EINVAL]	  The options parameter is an illegal value.

	   [EFAULT]	  arg points, or ctrlbuf or databuf is, outside the
			  allocated address space.

	   [EBADMSG]	  Message to be looked at is not valid for the
			  I_PEEK command.

      I_PLINK

	   [ENXIO]	  A hangup was received on the stream referred to by
			  the fildes parameter.

	   [ETIME]	  A timeout occurred before an acknowledgement
			  message was received at the stream head.

	   [EAGAIN]	  Temporarily unable to allocate storage to perform
			  the linking operation.

	   [EBADF]	  arg is not a valid open file descriptor.

	   [EINVAL]	  The stream referred to by fildes does not support
			  multiplexing.

	   [EINVAL]	  The file referred to by arg is not a stream or is
			  already linked under a multiplexing driver.

	   [EINVAL]	  The link operation would cause a "cycle" in the
			  resulting multiplexing configuration.	 In other
			  words, the driver referred to by arg is linked
			  into the configuration at multiple places.

      I_POP

	   [EINVAL]	  There are not modules in the stream.

	   [ENXIO]	  Error value returned by the module being popped.

	   [ENXIO]	  A hangup was received on fildes.

      I_PUNLINK

	   [ENXIO]	  A hangup was received on fildes.

	   [ETIME]	  A timeout occurred before an acknowledgement
			  message was received at the stream head.

	   [EAGAIN]	  Temporarily unable to allocate storage to perform
			  the linking operation.



 Hewlett-Packard Company	   - 16 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




	   [EINVAL]	  arg is an invalid multiplexor ID number.

	   [EINVAL]	  fildes is the file descriptor of a pipe.

		An I_PUNLINK ioctl can also fail if it is waiting for the
		multiplexor to acknowledge the unlink request and an error
		(M_ERROR) message, or hangup (M_HANGUP) is received at the
		stream head for fildes.	 In addition, an error can be
		returned in an M_IOCACK or M_IOCNAK message.  When these
		occur, the P_UNLINK ioctl fails with errno set to the value
		in the message.

      I_PUSH

	   [EINVAL]	  An invalid module name was used.

	   [EFAULT]	  arg points outside the allocated address space.

	   [ENXIO]	  Error value returned by the module being pushed.
			  The push has failed.

	   [ENXIO]	  A hangup was received on fildes.

      I_RECVFD

	   [EAGAIN]	  The O_NONBLOCK option was set, and a message was
			  not present on the stream head read queue.

	   [EFAULT]	  The arg parameter points outside the allocated
			  address space.

	   [EBADMSG]	  The message present on the stream head read queue
			  did not contain a passed file descriptor.

	   [EMFILE]	  Too many open files.	No more file descriptors are
			  permitted to be opened.

	   [ENXIO]	  A hangup was received on fildes.

      I_SENDFD

	   [EAGAIN]	  The sending stream head could not allocate a
			  message block for the file pointer.

	   [EAGAIN]	  The read queue of the receiving stream head was
			  full and could not accept the message.

	   [EBADF]	  The arg parameter is not a valid open file
			  descriptor.





 Hewlett-Packard Company	   - 17 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




	   [EINVAL]	  The fildes parameter does not refer to a stream.

	   [ENXIO]	  A hangup was received on fildes.

      I_SETCLTIME

	   [EINVAL]	  arg has an illegal value.

      I_SETSIG

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

	   [EAGAIN]	  A data structure to store the signal request could
			  not be allocated.

      I_SRDOPT

	   [EINVAL]	  arg contains an illegal value.

      I_STR

	   [EINVAL]	  The ic_len field is less than 0 (zero) bytes or
			  larger than the maximum allowable size of the data
			  part of a message (ic_dp).

	   [EINVAL]	  The ic_timeout field is less than -1.

	   [EFAULT]	  arg points, or the buffer area specified by ic_dp
			  or ic_len is, outside the allocated address space.

	   [ENOSR]	  Buffers could not be allocated for the ioctl
			  request because of a lack of STREAMS memory
			  resources.

	   [ENXIO]	  A hangup was received on the stream referred to by
			  fildes.

	   [ETIME]	  The ioctl request timed out before an
			  acknowledgement was received.

		The I_STR ioctl can also fail if the stream head receives a
		message indicating an error (M_ERROR) or a hangup
		(M_HANGUP).  In addition, an error can be returned in an
		M_IOCACK or M_IOCNAK message.  In these cases, the ioctl
		fails with errno set to the error value in the message.

      I_SWROPT

	   [EINVAL]	  The arg parameter is an illegal value.




 Hewlett-Packard Company	   - 18 -   HP-UX Release 11i: November 2000






 streamio(7)							 streamio(7)




      I_UNLINK

	   [ENXIO]	  A hangup was received on fildes.

	   [ETIME]	  A timeout occurred before an acknowledgement
			  message was received at the stream head.

	   [EINVAL]	  arg is an invalid multiplexor ID  number, or
			  fildes is already linked under a multiplexing
			  driver.

		An I_UNLINK ioctl can also fail if it is waiting for the
		multiplexor to acknowledge the unlink request and an error
		(M_ERROR) message, or hangup (M_HANGUP) is received at the
		stream head for fildes.	 In addition, an error can be
		returned in M_IOCACK or M_IOCNAK message.  When this occurs,
		the I_UNLINK ioctl fails with errno set to the value in the
		message.

 SEE ALSO
      close(2), fcntl(2), getmsg(2), ioctl(2), open(2), poll(2), putmsg(2),
      read(2), write(2), signal(5).
































 Hewlett-Packard Company	   - 19 -   HP-UX Release 11i: November 2000