unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



 stream(2)							   stream(2)




 NAME
      stream - STREAMS enhancements to standard system calls

 DESCRIPTION
      The open(), close(), read(), readv(), write(), writev(), ioctl(),
      select(), and signal() system calls are enhanced to support STREAMS.
      The new functionality is described below for each system call.

    Open Enhancements
      When calling open for a STREAMS device, the oflag parameter can only
      be constructed from the O_NONBLOCK flag values that are OR-ed with the
      O_RDONLY, O_WRONLY, or O_RDWR flag values.  The values of the other
      flags are not applicable to STREAMS devices and have no effect on
      them.

      The values of the O_NONBLOCK flags affect the operations of STREAMS-
      based device drivers, when the read(), write(), getmsg(), getpmsg(),
      putmsg(), or putpmsg() functions are used.  After the stream is open,
      these flags can be modified by calling fcntl() (see the fcntl(2) man
      page). The effects of the flags are device specific.

      The open of a STREAMS device may fail for one or more of the following
      STREAMS-specific conditions:

	   EIO	       A hangup occurred while the open() function was
		       attempting to open the stream.

	   EAGAIN      The system was unable to allocate a stream.

	   ENODEV      The device has not been generated into the system as
		       a STREAMS device.

	   ENXIO       The open routine of one of the modules or drivers in
		       the stream failed.

    Close Enhancements
      When all file descriptors associated with a STREAMS device have been
      closed, the stream is dismantled.	 If the file descriptor is
      associated with a stream that is subject to persistent links, the
      close() function will succeed immediately, but the stream will remain
      open.  See I_PLINK documentation in streamio(7).	Dismantling includes
      popping any modules on the stream and closing the driver.	 If
      O_NONBLOCK flag is set, and there are no signals posted for the
      stream, the close() function waits for output to drain on each
      module's or driver's non-empty write queue. close() waits for each
      module or driver for the amount of time set by the I_SETCLTIME ioctl()
      (see the streamio(7) man page).  The default is 15 seconds per module
      or driver.  If the O_NONBLOCK flag is set, or there are any pending
      signals, the function does not wait for output to drain and dismantles
      the stream immediately.  If a STREAMS device is closed, and the
      calling process had previously registered to recieve a SIGPOLL signal



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






 stream(2)							   stream(2)




      for events associated with that device (see "Signal Enhancements"
      below), close() unregisters the calling process for the events
      associated with the stream.

    Read and Readv Enhancements
      In this section, read() refers to both read() and readv().  For
      STREAMS devices, the read() function operates in accordance with the
      read mode of the file. STREAMS has three read modes: byte-stream mode,
      message-nondiscard mode, and message-discard mode. The default is
      byte-stream mode; however, the user can change this by issuing the
      I_SRDOPT ioctl() call.  The user can also test for the current read
      mode by issuing the I_GRDOPT ioctl() call.  See the streamio(7) man
      page for more information about these ioctl() calls.  The read()
      function's behavior in each of the read modes of a STREAMS device is
      as follows:

	   +  In byte-stream mode, the function retrieves data from the
	      stream associated with the file descriptor until it has
	      retrieved nbyte bytes, or until there is no more data to be
	      retrieved.

	   +  In message-nondiscard mode, the function retrieves data until
	      it reaches a message boundary.  If it does not retrieve all of
	      the data in the message, it places the remaining data back on
	      the stream.  This data can be retrieved by a subsequent
	      read(), getmsg(), or getpmsg() call.

	   +  In message-discard mode, the function retrieves data until it
	      has retrieved nbytes, or until it has reached a message
	      boundary.	 However, unread data remaining in the message is
	      discarded and is not available for reading by a subsequent
	      read(), getmsg(), or getpmsg() call.

      When attempting to read a STREAMS device and encountering a zero-byte
      message:

	   +  If the read mode is byte-stream, the read() function returns
	      the number of bytes of data read before encountering the
	      zero-byte message.  If data was read before receiving the
	      zero-byte message, read() returns the zero-byte message to the
	      stream so it can be processed by a subsequent read(),
	      getmsg(), or getpmsg() call.  If no data was read, read()
	      consumes the message.

	   +  If the read mode is message-discard or message-nondiscard, the
	      read() function returns zero, and then consumes the message.

      The read() function reads the data at the front of the stream head
      read queue.  It reads both priority band and normal data.





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






 stream(2)							   stream(2)




      The read() function processes control messages according to the
      STREAMS read flags: RPROTNORM, RPROTDAT, and RPROTDIS.  The default is
      for RPROTNORM to be set; however, the user can change this by issuing
      the I_SRDOPT ioctl() call.  The read() function's behavior for each
      read flag is described below:

	   +  If RPROTNORM is set, a read from a stream can only process
	      data messages.  It cannot process any type of control message
	      and fails if such a message is encountered at the stream head.

	   +  If RPROTDAT is set, read() processes both data and control
	      messages.	 The read() function delivers data in both data and
	      control messages.

	   +  If RPROTDIS is set, read() consumes any control messages and
	      retrieves data from data messages only.

      The following is also true for reads to STREAMS devices.	If the
      O_NONBLOCK flag is clear, and no message is waiting to be read on the
      stream, the read() function blocks until a message arrives at the
      stream head.  If the O_NONBLOCK flag is set, and no message is waiting
      to be read on the stream, the read() function fails and returns
      ERANGE.

      A read from a STREAMS device may fail for one or more of the following
      STREAMS-specific conditions:

	   EAGAIN      No message is waiting to be read on the stream, and
		       the O_NONBLOCK flag is set.

	   EBADMSG     A message is waiting to be read, but it is not a data
		       message and the RPROTNORM flag is set.

	   EINVAL      The stream is linked to a multiplexor.

      A read from a STREAMS device also fails if an error message is
      received at the stream head.  In this case, errno is set to the value
      returned in the error message.

      If a hangup occurs on the stream being read, the read() function
      continues its operations until the stream read queues are empty.
      Thereafter, it returns a value of 0 (zero).

    Write and Writev Enhancements
      In this section, write() refers to both write() and writev().  When
      writing to a STREAMS device, the write() function sends ordinary,
      priority band zero, data.	 Other aspects of the write() function's
      behavior are determined by the packet size that the stream will
      accept.





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






 stream(2)							   stream(2)




      If nbytes is not within the top module's minimum and maximum packet
      size range, write() will return ERANGE. Two exceptions exist, however,
      in which write() does not return an error.  The first exception is if
      nbytes is too large and either the maximum packet size is infinite or
      the minimum packet size is less than or equal to zero.  The second
      exception occurs if nbytes is too small and the minimum packet size is
      less than or equal to zero.  With either exception, write() does not
      return ERANGE, and transfers the data.

      The write() function may send the user's data buffer in multiple
      messages.	 The maximum amount of data that write() sends in one
      message is the lower value of the top module's maximum packet size and
      STRMSGSZ.	 If the maximum packet size is infinite, write() compares
      half of the top module's high water mark to STRMSGSZ instead.  If the
      high water mark is less than or equal to zero, the page size is used.

      If a zero-length buffer (nbytes is 0) is passed to write(), zero bytes
      are sent to the stream and zero bytes are returned.

      The following is also true for writes to STREAMS devices.	 If the
      O_NONBLOCK flag is clear, and the stream cannot accept data (the
      stream head write queue is full due to flow control conditions), the
      write() function blocks until data can be accepted.  If the O_NONBLOCK
      flag is set, and the stream cannot accept data, the write() function
      fails, and returns EAGAIN.  If the O_NONBLOCK flag is set, and the
      stream cannot accept data, but part of the buffer has already been
      written, the write() function terminates and returns the number of
      bytes written.

      A write to a STREAMS device may fail for one or more of the following
      STREAMS-specific conditions:

	   EAGAIN      The O_NONBLOCK flag is set, and the stream cannot
		       accept write() data because it is flow controlled.

	   EINVAL      The write() function attempts to write to a stream
		       that is linked below a multiplexor.

	   ENXIO       A hangup occurs on a stream while the write()
		       function is writing to the stream.

	   ERANGE      The nbytes parameter is not within the allowable
		       range.

      The write() system call will also fail if an error message has been
      received at the stream head of the stream to which the write()
      function is attempting to write.	In this case, the function returns
      with errno set to the value included in the error message.

    Ioctl Enhancements




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






 stream(2)							   stream(2)




      Refer to the streamio(7) man page for a description of STREAMS ioctl()
      functionality.

    Select Enhancements
      The select() system call checks the status of STREAMS devices.
      select() does not provide as much information for STREAMS devices as
      poll().  A program calls select() so that it can wait for events on
      both STREAMS and non-STREAMS devices.  If select() returns an event
      for a STREAMS device, the program can call poll() to get more
      information.  Refer to the poll(2) man page for more information about
      poll().

      select() returns a read event if a poll() POLLIN, POLLERR, POLLNVAL or
      POLLHUP event exists on the stream.  In other words, select() returns
      a read event if a normal or priority band message is waiting to be
      read, if a read error exists at the stream head, if a write error
      exists at the stream head, if the stream is linked under a
      multiplexor, or if a hang-up has occurred.

      select() returns a write event if a poll() POLLOUT, POLLWRNORM,
      POLLERR, or POLLNVAL event exists on the stream.	This means that
      select() returns a write event if normal data can be written without
      blocking because of flow control, a read error exists at the stream
      head, a write error exists at the stream head, or the stream is linked
      under a multiplexor.

      select() returns an exception event if a poll() POLLPRI event exists
      on the stream.  More specifically, select() returns an exception event
      if a high-priority message is waiting to be read.

    Signal Enhancements
      A new signal, SIGPOLL, has been added for STREAMS. Processes register
      to receive a SIGPOLL signal for events that occur on a STREAMS device
      (see the signal(2) man page and I_SETSIG in the streamio(7) man page).
      The default action is to ignore the signal, not to terminate the
      process.

 SEE ALSO
      close(2), fcntl(2), getmsg(2), open(2), poll(2), putmsg(2), read(2),
      signal(2), select(2), write(2), streamio(7), and STREAMS/UX for HP9000
      Reference Manual.













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