Deprecated create_proc_entry¶

Note that the above article uses create_proc_entry which was removed inkernel 3.10. Current versions require the following update:

-   entry = create_proc_entry("sequence", 0, NULL);-   if (entry)-           entry->proc_fops = &ct_file_ops;+   entry = proc_create("sequence", 0, NULL, &ct_file_ops);

The iterator interface¶

Modules implementing a virtual file with seq_file must implement aniterator object that allows stepping through the data of interestduring a “session” (roughly one read() system call). If the iteratoris able to move to a specific position - like the file they implement,though with freedom to map the position number to a sequence locationin whatever way is convenient - the iterator need only existtransiently during a session. If the iterator cannot easily find anumerical position but works well with a first/next interface, theiterator can be stored in the private data area and continue from onesession to the next.

A seq_file implementation that is formatting firewall rules from atable, for example, could provide a simple iterator that interpretsposition N as the Nth rule in the chain. A seq_file implementationthat presents the content of a, potentially volatile, linked listmight record a pointer into that list, providing that can be donewithout risk of the current location being removed.

Positioning can thus be done in whatever way makes the most sense forthe generator of the data, which need not be aware of how a positiontranslates to an offset in the virtual file. The one obvious exceptionis that a position of zero should indicate the beginning of the file.

The /proc/sequence iterator just uses the count of the next number itwill output as its position.

Four functions must be implemented to make the iterator work. Thefirst, called start(), starts a session and takes a position as anargument, returning an iterator which will start reading at thatposition. The pos passed to start() will always be either zero, orthe most recent pos used in the previous session.

For our simple sequence example,the start() function looks like:

static void *ct_seq_start(struct seq_file *s, loff_t *pos){        loff_t *spos = kmalloc(sizeof(loff_t), GFP_KERNEL);        if (! spos)                return NULL;        *spos = *pos;        return spos;}

The entire data structure for this iterator is a single loff_t valueholding the current position. There is no upper bound for the sequenceiterator, but that will not be the case for most other seq_fileimplementations; in most cases the start() function should check for a“past end of file” condition and return NULL if need be.

For more complicated applications, the private field of the seq_filestructure can be used to hold state from session to session. There isalso a special value which can be returned by the start() functioncalled SEQ_START_TOKEN; it can be used if you wish to instruct yourshow() function (described below) to print a header at the top of theoutput. SEQ_START_TOKEN should only be used if the offset is zero,however.

The next function to implement is called, amazingly, next(); its job is tomove the iterator forward to the next position in the sequence. Theexample module can simply increment the position by one; more usefulmodules will do what is needed to step through some data structure. Thenext() function returns a new iterator, or NULL if the sequence iscomplete. Here’s the example version:

static void *ct_seq_next(struct seq_file *s, void *v, loff_t *pos){        loff_t *spos = v;        *pos = ++*spos;        return spos;}

The stop() function closes a session; its job, of course, is to cleanup. If dynamic memory is allocated for the iterator, stop() is theplace to free it; if a lock was taken by start(), stop() must releasethat lock. The value that*pos was set to by the last next() callbefore stop() is remembered, and used for the first start() call ofthe next session unless lseek() has been called on the file; in thatcase next start() will be asked to start at position zero:

static void ct_seq_stop(struct seq_file *s, void *v){        kfree(v);}

Finally, the show() function should format the object currently pointed toby the iterator for output. The example module’s show() function is:

static int ct_seq_show(struct seq_file *s, void *v){        loff_t *spos = v;        seq_printf(s, "%lld\n", (long long)*spos);        return 0;}

If all is well, the show() function should return zero. A negative errorcode in the usual manner indicates that something went wrong; it will bepassed back to user space. This function can also return SEQ_SKIP, whichcauses the current item to be skipped; if the show() function has alreadygenerated output before returning SEQ_SKIP, that output will be dropped.

We will look at seq_printf() in a moment. But first, the definition of theseq_file iterator is finished by creating a seq_operations structure withthe four functions we have just defined:

static const struct seq_operations ct_seq_ops = {        .start = ct_seq_start,        .next  = ct_seq_next,        .stop  = ct_seq_stop,        .show  = ct_seq_show};

This structure will be needed to tie our iterator to the /proc file ina little bit.

It’s worth noting that the iterator value returned by start() andmanipulated by the other functions is considered to be completely opaque bythe seq_file code. It can thus be anything that is useful in steppingthrough the data to be output. Counters can be useful, but it could also bea direct pointer into an array or linked list. Anything goes, as long asthe programmer is aware that things can happen between calls to theiterator function. However, the seq_file code (by design) will not sleepbetween the calls to start() and stop(), so holding a lock during that timeis a reasonable thing to do. The seq_file code will also avoid taking anyother locks while the iterator is active.

Formatted output¶

The seq_file code manages positioning within the output created by theiterator and getting it into the user’s buffer. But, for that to work, thatoutput must be passed to the seq_file code. Some utility functions havebeen defined which make this task easy.

Most code will simply use seq_printf(), which works pretty much likeprintk(), but which requires the seq_file pointer as an argument.

For straight character output, the following functions may be used:

seq_putc(struct seq_file *m, char c);seq_puts(struct seq_file *m, const char *s);seq_escape(struct seq_file *m, const char *s, const char *esc);

The first two output a single character and a string, just like one wouldexpect.seq_escape() is like seq_puts(), except that any character in swhich is in the string esc will be represented in octal form in the output.

There are also a pair of functions for printing filenames:

int seq_path(struct seq_file *m, const struct path *path,             const char *esc);int seq_path_root(struct seq_file *m, const struct path *path,                  const struct path *root, const char *esc)

Here, path indicates the file of interest, and esc is a set of characterswhich should be escaped in the output. A call toseq_path() will outputthe path relative to the current process’s filesystem root. If a differentroot is desired, it can be used with seq_path_root(). If it turns out thatpath cannot be reached from root, seq_path_root() returns SEQ_SKIP.

A function producing complicated output may want to check:

bool seq_has_overflowed(struct seq_file *m);

and avoid further seq_<output> calls if true is returned.

A true return from seq_has_overflowed means that the seq_file buffer willbe discarded and the seq_show function will attempt to allocate a largerbuffer and retry printing.

Making it all work¶

So far, we have a nice set of functions which can produce output within theseq_file system, but we have not yet turned them into a file that a usercan see. Creating a file within the kernel requires, of course, thecreation of a set of file_operations which implement the operations on thatfile. The seq_file interface provides a set of canned operations which domost of the work. The virtual file author still must implement the open()method, however, to hook everything up. The open function is often a singleline, as in the example module:

static int ct_open(struct inode *inode, struct file *file){        return seq_open(file, &ct_seq_ops);}

Here, the call toseq_open() takes the seq_operations structure we createdbefore, and gets set up to iterate through the virtual file.

On a successful open,seq_open() stores the struct seq_file pointer infile->private_data. If you have an application where the same iterator canbe used for more than one file, you can store an arbitrary pointer in theprivate field of the seq_file structure; that value can then be retrievedby the iterator functions.

There is also a wrapper function toseq_open() called seq_open_private(). Itkmallocs a zero filled block of memory and stores a pointer to it in theprivate field of the seq_file structure, returning 0 on success. Theblock size is specified in a third parameter to the function, e.g.:

static int ct_open(struct inode *inode, struct file *file){        return seq_open_private(file, &ct_seq_ops,                                sizeof(struct mystruct));}

There is also a variant function, __seq_open_private(), which is functionallyidentical except that, if successful, it returns the pointer to the allocatedmemory block, allowing further initialisation e.g.:

static int ct_open(struct inode *inode, struct file *file){        struct mystruct *p =                __seq_open_private(file, &ct_seq_ops, sizeof(*p));        if (!p)                return -ENOMEM;        p->foo = bar; /* initialize my stuff */                ...        p->baz = true;        return 0;}

A corresponding close function, seq_release_private() is available whichfrees the memory allocated in the corresponding open.

The other operations of interest - read(), llseek(), and release() - areall implemented by the seq_file code itself. So a virtual file’sfile_operations structure will look like:

static const struct file_operations ct_file_ops = {        .owner   = THIS_MODULE,        .open    = ct_open,        .read    = seq_read,        .llseek  = seq_lseek,        .release = seq_release};

There is also a seq_release_private() which passes the contents of theseq_file private field tokfree() before releasing the structure.

The final step is the creation of the /proc file itself. In the examplecode, that is done in the initialization code in the usual way:

static int ct_init(void){        struct proc_dir_entry *entry;        proc_create("sequence", 0, NULL, &ct_file_ops);        return 0;}module_init(ct_init);

And that is pretty much it.

seq_list¶

If your file will be iterating through a linked list, you may find theseroutines useful:

struct list_head *seq_list_start(struct list_head *head,                                 loff_t pos);struct list_head *seq_list_start_head(struct list_head *head,                                      loff_t pos);struct list_head *seq_list_next(void *v, struct list_head *head,                                loff_t *ppos);

These helpers will interpret pos as a position within the list and iterateaccordingly. Your start() and next() functions need only invoke theseq_list_* helpers with a pointer to the appropriate list_head structure.

The extra-simple version¶

For extremely simple virtual files, there is an even easier interface. Amodule can define only the show() function, which should create all theoutput that the virtual file will contain. The file’s open() method thencalls:

int single_open(struct file *file,                int (*show)(struct seq_file *m, void *p),                void *data);

When output time comes, the show() function will be called once. The datavalue given to single_open() can be found in the private field of theseq_file structure. When using single_open(), the programmer should usesingle_release() instead ofseq_release() in the file_operations structureto avoid a memory leak.