Driver porting: The seq_file interface

Driver porting: The seq_file interface

This article describes how to generate an infinite series of integers. It would have been much more practical if this article had talked about generating finite series of integers ... I had trouble getting the seq_file iterator to stop calling my functions.

I read this article and http://www.kernelnewbies.org/documents/seq_file_howto.txt. Nevertheless, I still wasted a lot of time trying to get it to work.

My notes:

you write the routines your_start, your_stop, your_next, and your_show

The pos parameter to your_start and your_next is an index into the set of items that you wish to enumerate. your_next must increment this index, as in ++*pos.

your_start must know the number of items in your set so that it can check the validity of *pos. your_start will be called again, even after your_next returns NULL and your_stop has been called.

Let's say that you want to count from 0 through 9. your_start is called with *pos==0. It returns a pointer to your iterator data structure. your_show is called, then your_next is called. This happens until your_next returns NULL or ERR_PTR(some-negative-error-code). your_stop is then called. At this point, your_start will be called *again*, with *pos==10 ... seems strange to me, but that is the behavior.

The iterator pointer returned by your_start/your_next can be whatever you want, including integer values. However, be advised that the values in the range -1000 <= n <= 0 are interpreted as error conditions/NULL. Therefore, you probably want to return a pointer.

The kernelnewbies.org seq_file_howto.txt document says your_start should return error codes like EACCES if the *pos position is out of bounds. Note that if you want to do this, then you must return -EACCES, not EACCES. Maybe that was obvious to experienced kernel hackers, but it certainly was not obvious to me. Do this by returning ERR_PTR(-EACCES). If this value is not negative, then the seq_file code will assume that you have returned a valid iterator pointer and it will call your_show.

It is probably easier to simply return NULL on error conditions (like *pos out of bounds) and not worry about it. When I tried to worry about it and do the right thing, it just caused trouble for me.

I spent some time looking at the seq_file code. Frankly, I was quite disappointed ... the implementation looked pretty ugly to me.

Michael

Hi,

Just wanted to say thanks for the comment. You've probably saved me a good few minutes trying
to work out why seq_file kept calling my code.

It must be said, the seq_file interface is one of the uglier APIs I've seen in the kernel.
Clear and easy to use it is not.