I_LIST ioctl(2)Example

The I_LIST ioctl(2) lists the drivers and module in a stream.

Example 8-13 List a Stream's Drivers and Modules

#include <stdio.h>
#include <string.h>
#include <stropts.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/types.h>
#include <sys/socket.h>

main(int argc, const char **argv)
{
		int               s, i;
		int               mods;
		struct str_list   mod_list;
		struct str_mlist *mlist;

		/* Get a socket... */
		if((s = socket(AF_INET, SOCK_STREAM, 0)) <= 0) {
			perror("socket: ");
			exit(1);
		}

		/* Determine the number of modules in the stream. */
		if((mods = ioctl(s, I_LIST, 0)) < 0){
			perror("I_LIST ioctl");
		}
		if(mods == 0) {
			printf("No modules\n");
			exit(1);
		} else {
			printf("%d modules\n", mods);
		}
		/* Allocate memory for all of the module names... */
		mlist = (struct str_mlist *) calloc(mods, sizeof(struct str_mlist));
		if(mlist == 0){
			perror("malloc failure");
			exit(1);
		}
		mod_list.sl_modlist = mlist;
		mod_list.sl_nmods = mods;

		/* Do the ioctl and get the module names. */
		if(ioctl(s, I_LIST, &mod_list) < 0){
			perror("I_LIST ioctl fetch");
			exit(1);
		}

		/* Print out the name of the modules */
		for(i = 0; i < mods; i++) {
			printf("s: %s\n", mod_list.sl_modlist[i].l_name);
		}

		free(mlist);

		exit(0);
}

M_FLUSH Message Handling

All modules and drivers are expected to handle M_FLUSH messages. An M_FLUSH message can originate at the stream head or from a module or a driver. The user can cause data to be flushed from queued messages of a stream by submiting an I_FLUSH ioctl(2). Data can be flushed from the read side, write side, or both sides of a stream.

ioctl(fd,I_FLUSH, arg);

The first byte of the M_FLUSH message is an option flag. The following table describes the possible values for this flag.

Table 8-1 M_FLUSH Arguments and bi_flag Values

Flushing According to Priority Bands

In addition to being able to flush all the data from a queue, a specific band can be flushed using the I_FLUSHBAND ioctl(2).

ioctl(fd, I_FLUSHBAND, bandp); 

The ioctl(2) is passed a pointer to a bandinfo structure. The bi_pri field indicates the band priority to be flushed (from 0 to 255). The bi_flag field indicates the type of flushing to be done. The legal values for bi_flag are defined in Table 8-1. bandinfo has the following format:

struct bandinfo {
		unsigned char       bi_pri;
		in                  bi_flag;
};

See M_FLUSH for details on how modules and drivers should handle flush band requests.

Figure 8-1 and Figure 8-2 further demonstrate flushing the entire stream due to a line break. Figure 8-1 shows the flushing of the write side of a stream, and Figure 8-2 shows the flushing of the read side of a stream.

Figure 8-1 Flushing the Write Side of a Stream

The following discussion describes the sequence of events shown in Figure 8-1 (dotted lines mean flushed queues):

1. A break is detected by a driver.

2. The driver generates an M_BREAK message and sends it upstream.

3. The module translates the M_BREAK into an M_FLUSH message with FLUSHW set, then sends it upstream.

4. The stream head does not flush the write queue (no messages are ever queued there).

5. The stream head turns the message around (sends it down the write side).

6. The module flushes its write queue.

7. The message is passed downstream.

8. The driver flushes its write queue and frees the message.

Figure 8-2 shows flushing the read side of a stream.

Figure 8-2 Flushing the Read Side of a Stream

The following discussion describes the sequence of events.

1. After generating the first M_FLUSH message, the module generates an M_FLUSH with FLUSHR set and sends it downstream.

2. The driver flushes its read queue.

3. The driver turns the message around (sends it up the read side).

4. The module flushes its read queue.

5. The message is passed upstream.

6. The stream head flushes the read queue and frees the message.