NIT_BUF(4M)

NAME
nit_buf - STREAMS NIT buffering module

CONFIG
pseudo-device    nbuf

SYNOPSIS
#include <sys/ioctl.h>
#include <net/nit_buf.h>
ioctl(fd, I_PUSH, "nbuf");

DESCRIPTION

nit_buf is a STREAMS module that buffers incoming messages, thereby reducing the number of system calls and associated overhead required to read and process them. Although designed to be used in conjunction with the other components of NIT (see nit(4P)), nit_buf is a general-purpose module and can be used anywhere STREAMS input buffering is required.

  Read-side Behavior
nit_buf collects incoming M_DATA and M_PROTO messages into chunks, passing each chunk upward when either the chunk becomes full or the current read timeout expires. When a message arrives, it is processed in two steps. First, the message is prepared for inclusion in a chunk, and then it is added to the current chunk. The following paragraphs discuss each step in turn.

Upon receiving a message from below, nit_buf immediately converts all leading M_PROTO blocks in the message to M_DATA blocks, altering only the message type field and leaving the contents alone. It then prepends a header to the converted message. This header is defined as follows.
    struct nit_bufhdr {
    	u_int	nhb_msglen;
    	u_int	nhb_totlen;
    };
The first field of this header gives the length in bytes of the converted message. The second field gives the distance in bytes from the start of the message in the current chunk (described below) to the start of the next message in the chunk; the value reflects any padding necessary to insure correct data alignment for the host machine and includes the length of the header itself.

After preparing a message, nit_buf attempts to add it to the end of the current chunk, using the chunk size and timeout values to govern the addition. (The chunk size and timeout values are set and inspected using the ioctl calls described below.) If adding the new message would make the current chunk grow larger than the chunk size, nit_buf closes off the current chunk, passing it up to the next module in line, and starts a new chunk, seeding it with a zero-length message. If adding the message would still make the current chunk overflow, the module passes it upward in an over-size chunk of its own. Otherwise, the module concatenates the message to the end of the current chunk.

To ensure that messages do not languish forever in an accumulating chunk, nit_buf maintains a read timeout. Whenever this timeout expires, the module closes off the current chunk, regardless of its length, and passes it upward; if no incoming messages have arrived, the chunk passed upward will have zero length. Whenever the module passes a chunk upward, it restarts the timeout period. These two rules insure that nit_buf minimizes the number of chunks it produces during periods of intense message activity and that it periodically disposes of all messages during slack intervals.

nit_buf handles other message types as follows. Upon receiving an M_FLUSH message specifying that the read queue be flushed, the module does so, clearing the currently accumulating chunk as well, and passes the message on to the module or driver above. It passes all other messages through unaltered to its upper neighbor.

  Write-side Behavior
nit_buf intercepts M_IOCTL messages for the ioctls described below. Upon receiving an M_FLUSH message specifying that the write queue be flushed, the module does so and passes the message on to the module or driver below. The module passes all other messages through unaltered to its lower neighbor.

IOCTLS
nit_buf responds to the following ioctls.

NIOCSTIME
    Set the read timeout value to the value referred to by the struct timeval pointer given as argument. Setting the timeout value to zero has the side-effect of forcing the chunk size to zero as well, so that the module will pass all incoming messages upward immediately upon arrival.

NIOCGTIME
    Return the read timeout in the struct timeval pointed to by the argument. If the timeout has been cleared with the NIOCCTIME ioctl, return with an ERANGE error.

NIOCCTIME
    Clear the read timeout, effectively setting its value to infinity.

NIOCSCHUNK
    Set the chunk size to the value referred to by the u_int pointer given as argument.

NIOCGCHUNK
    Return the chunk size in the u_int pointed to by the argument.

WARNING
The module name ``nbuf'' used in the system configuration file and as argument to the I_PUSH ioctl is provisional and subject to change.

SEE ALSO
nit(4P), nit_if(4M), nit_pf(4M)