stream.2 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

stream(2) stream(2)

NAME

stream: open(), close(), read(), readv(), write(), writev(), ioctl(), select(), signal() - STREAMS enhance-

ments to standard system calls

DESCRIPTION

The

open(), close(), read(),

readv(), write(), writev(), ioctl(), select(), and sig-

nal() 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 oﬂag parameter can only be constructed from the

O_NONBLOCK ﬂag values that are OR-ed with the

O_RDONLY, O_WRONLY,orO_RDWR ﬂag values. The

values of the other ﬂags are not applicable to STREAMS devices and have no effect on them.

The values of the

O_NONBLOCK ﬂags affect the operations of STREAMS-based device drivers, when the

read(), write(), getmsg(), getpmsg()

, putmsg(),orputpmsg() functions are used. After the

stream is open, these ﬂags can be modiﬁed by calling

fcntl() (see the fcntl (2) man page). The effects of

the ﬂags are device speciﬁc.

The open of a STREAMS device may fail for one or more of the following STREAMS-speciﬁc 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 ﬁle descriptors associated with a STREAMS device have been closed, the stream is dismantled.

If the ﬁle 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 ﬂag 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 ﬂag is set, or there are any pending signals, the func-

tion 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 for events associ-

ated 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() func-

tion operates in accordance with the read mode of the ﬁle. 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 ﬁle descrip-

tor 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(),orgetpmsg() 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(),orgetpmsg() 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 mes-

sage, read() returns the zero-byte message to the stream so it can be processed by a

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (4 pages)

PAGE 1
stream(2) stream(2) NAME stream: open(), close(), read(), readv(), write(), writev(), ioctl(), select(), signal() - 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.
PAGE 2
stream(2) stream(2) 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. The read() function processes control messages according to the STREAMS read flags: RPROTNORM, RPROTDAT, and RPROTDIS.
PAGE 3
stream(2) stream(2) 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.
PAGE 4
(Notes) A (Notes) sA 4 Hewlett-Packard Company −1− HP-UX 11i Version 3: September 2010