STREAMS Programming Guide

Controlling Flow and Priorities

The I_FLUSHBAND, I_CKBAND, I_GETBAND, I_CANPUT, and I_ATMARK ioctl(2)s support multiple bands of data flow. The I_FLUSHBAND ioctl(2) allows a user to flush a particular band of messages. "Flush Handling" discusses it in more detail.

The I_CKBAND ioctl(2) checks if a message of a given priority exists on the Stream-head read queue. Its interface is:


ioctl(fd, I_CKBAND, pri); 

The call returns 1 if a message of priority pri exists on the Stream-head read queue and 0 if no message of priority pri exists. If an error occurs, -1 is returned. Note that pri should be of type int.

The I_GETBAND ioctl(2) checks the priority of the first message on the Stream-head read queue. The interface is:

ioctl (fd, I_GETBAND, prip); 

The call results in the integer referenced by prip being set to the priority band of the message on the front of the Stream-head read queue.

The I_CANPUT ioctl(2) checks if a certain band is writable. Its interface is:


ioctl (fd, I_CANPUT, pri); 

The return value is 0 if the priority band pri is flow controlled, 1 if the band is writable, and -1 on error.

A module or driver can mark a message. This supports Transmission Control Protocol's (TCP) ability to indicate to the user the last byte of out-of-band data. Once marked, a message sent to the Stream-head causes the Stream-head to remember the message. A user can check if the message on the front of its Stream-head read queue is marked or not with the I_ATMARK ioctl(2). If a user is reading data from the Stream-head, there are multiple messages on the read queue, and one of those messages is marked, the read(2) terminates when it reaches the marked message and returns the data only up to the marked message. Get the rest of the data with successive reads. Chapter 4, STREAMS Driver and Module Interfaces discusses this in more detail.

The I_ATMARK ioctl(2) has the format:


ioctl (fd, I_ATMARK, flag); 

where flag can be either ANYMARK or LASTMARK. ANYMARK indicates that the user wants to check if any message is marked. LASTMARK indicates that the user wants to see if the message is the one and only one marked in the queue. If the test succeeds, 1 is returned. On failure, 0 is returned. If an error occurs, -1 is returned.