SEQ file is a Tinker Archive.Tinker is a software tools for Molecular Design.SEQ file type contains the primary sequence of a biopolymer in the standard one-letter code with 50 residues per line. The.seq or sequence file extension is found in files which are editable text file that normally contains a DNA sequence. The term editable in this type of file means that the data can be manipulated and the results can sometimes be derived from it.
Linux kernel seq_file HOWTO
Randy Dunlap <rddunlap@osdl.org>
v0: 2003-02-22
v1: 2003-03-14
Parts of this seq_file HOWTO were contributed by Andries Brouwer (aeb%win!tue!nl).
[Another seq_file reference is 'Driver porting: The seq_file interface' at <http://lwn.net/Articles/22355/>, which is part of the LWN.net series 'Porting Drivers to 2.5' that is located at <http://lwn.net/Articles/driver-porting/>.]
Introduction
The 'seq_file' interface to the /proc filesystem was introduced in Linux 2.4.15-pre3 and Linux 2.4.13-ac8. It provides a safer interface to the /proc filesystem than previous procfs methods because it protects against overflow of the output buffer and easily handles procfs files that are larger than one page. It also provides methods for traversing a list of kernel items and iterating on that list. It provides procfs output facilities that are less error-prone than the previous procfs interfaces.
Overview:
seq_file operates by using 'pull' methods, pulling or asking for data from seq_file operations methods, whereas the previous procfs methods pushed data into output buffers.
seq_file Creation and Data Structures
Apps That Open Seq Files
A seq_file-type /proc file is created by using create_proc_entry() and setting the resulting proc_dir_entry->proc_fops pointer to the desired struct file_operations. E.g. (from linux/mm/swapfile.c):
struct file_operations for the seq_file-type proc file describes 4 I/O methods, e.g.:
The last 3 are reusable seq_file-supplied methods. The open method is what must be supplied for each proc file, and that open()function only needs to call seq_open() with a pointer to a struct seq_operations descriptor. E.g. (still from linux/mm/swapfile.c):
struct seq_file seq_operations swaps_op supplies 4 methods for producing seq_file output: start(), next(), stop(), and show(). These are described below. The structure typically looks like:
seq_file Methods
The seq_file routines never take any locks between the ->open() and ->stop() functions, so seq_file callers are free to use anything -- spinlocks, etc.
The seq_file interface does require more data structures to be setup to point to methods that are used during seq_file access. In return for this, you (we) get much safer /proc output methods. These four methods are in struct seq_operations:
The .start method is used to initialize data for walking through a list of kernel items. This list can be an array, a linked list, a hash table, etc. Its actual data type doesn't matter. This function should lock whatever needs to be locked for safety and return an entry by number (0 for the first entry). This method should also honor file offset semantics by using the 'loff_t *pos' (second) parameter. The 'entry number' value is passed to the stop, next, and show methods as the 'void *v' parameter. In case of error, return ERR_PTR(error_code).
If you need to show a header line or something, then return SEQ_START_TOKEN in your start() and recognise that in next() and show(). IOW, pos 0 will be the header line, and pos 1 will correspond to the first actual item on your list, and so on. See net/netlink/af_netlink.c for a simple example.
If there is any locking that needs to be done to iterate through the kernel list, the lock(s) can be acquired in the .start method. However, if the .show method is very time-consuming and the .show method lends itself to locking there, that may be a better place for it.
struct seq_file contains a 'void *private' that can be used by the struct seq_operations functions to hold any private data that needs to be available to all of these related methods. For example, the .start method might allocate some memory and save its address in seq_file.private so that the .next and .show methods can use it, then the .stop method would free that memory.
The .stop method is called after the .next method has nothing more to do. This method is used for cleanups, unlocking, freeing resources, etc. The .stop method is always called if the .start method was called, even if the .start method fails, so that all cleanups can be done in .stop.
The .next method is the iterator for the items (list, array, table, etc.) that is being traversed for /proc file output. It advances to the next item of interest to be shown in the /proc output file and indicates when there are no more items by returning NULL or an error (like -ENOMEM or -EACCES). If there are more items to be shown, it returns the next element (entry) of the sequence by entry number.
The .show method is used to show an entry (write output to the /proc file) by using seq_...() as you would use stdio functions. It can write static headings or variable data into the seq_file output buffer. It uses seq_{putc, puts, printf, ...} to format the output (see below). In case of error, return a negative error_code; otherwise return 0.
seq_file Output Routines
The seq_file output methods are:
Simplified seq_file Methods
Open Seq 1 File
If you only need a single function entry (call) to produce all the desired proc-fs output, just use single_open() and single_release().
Open Seq File
single_open() gets a parameter that is the 'show' function for the data that is to be written to /proc. The 'show' function does everything that is needed to write the data, all in one function call. This is useful either for writing small amounts of data to /proc, for cases in which the output is not iterative, or for cases in which recursion is more appropriate, since the non-single methods don't fit well with recursive techniques. Examples of appropriate uses of single_open() 'show' functions are:
CategoryDocs