NIT_BUF(4M) DEVICES AND NETWORK INTERFACES NIT_BUF(4M) NAME nit_buf - STREAMS NIT buffering module CONFIG pseudo-device nbuf SYNOPSIS #include #include 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 dis- cuss 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 Sun Release 4.1 Last change: 29 December 1987 1 NIT_BUF(4M) DEVICES AND NETWORK INTERFACES NIT_BUF(4M) the current chunk, passing it up to the next module in line, and starts a new chunk, seeding it with a zero-length mes- sage. 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 accu- mulating 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 pro- duces during periods of intense message activity and that it periodically disposes of all messages during slack inter- vals. 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 accu- mulating 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 argu- ment. 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. Sun Release 4.1 Last change: 29 December 1987 2 NIT_BUF(4M) DEVICES AND NETWORK INTERFACES NIT_BUF(4M) 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) Sun Release 4.1 Last change: 29 December 1987 3