How to open a SEQ file: The best way to open an SEQ file is to simply double-click it and let the default assoisated application open the file. If you are unable to open the file this way, it may be because you do not have the correct application associated with the extension to view or edit the SEQ file. .seq files are easily converted to fasta format in a text editor. Simply add a line before the sequence with the format: sequence-id. Open the files in the text editor (make sure its an ASCI.
How to open SEQ files. If you cannot open the SEQ file on your computer - there may be several reasons. The first and most important reason (the most common) is the lack of a suitable software that supports SEQ among those that are installed on your device. A very simple way to solve this problem is to find and download the appropriate application. .seq files are plain text files containing your sequence in FASTA format and can be opened with any software capable of viewing plain text or FASTA format files (text editor software such as Word, NotePad, etc.). You may also change the file extension from.seq to.txt.
Copyright 2003 Jonathan Corbet <corbet@lwn.net>
This file is originally from the LWN.net Driver Porting series athttps://lwn.net/Articles/driver-porting/
There are numerous ways for a device driver (or other kernel component) toprovide information to the user or system administrator. One usefultechnique is the creation of virtual files, in debugfs, /proc or elsewhere.Virtual files can provide human-readable output that is easy to get atwithout any special utility programs; they can also make life easier forscript writers. It is not surprising that the use of virtual files hasgrown over the years.
Creating those files correctly has always been a bit of a challenge,however. It is not that hard to make a virtual file which returns astring. But life gets trickier if the output is long - anything greaterthan an application is likely to read in a single operation. Handlingmultiple reads (and seeks) requires careful attention to the reader’sposition within the virtual file - that position is, likely as not, in themiddle of a line of output. The kernel has traditionally had a number ofimplementations that got this wrong.
The 2.6 kernel contains a set of functions (implemented by Alexander Viro)which are designed to make it easy for virtual file creators to get itright.
The seq_file interface is available via <linux/seq_file.h>. There arethree aspects to seq_file:
- An iterator interface which lets a virtual file implementationstep through the objects it is presenting.
- Some utility functions for formatting objects for output withoutneeding to worry about things like output buffers.
- A set of canned file_operations which implement most operations onthe virtual file.
We’ll look at the seq_file interface via an extremely simple example: aloadable module which creates a file called /proc/sequence. The file, whenread, simply produces a set of increasing integer values, one per line. Thesequence will continue until the user loses patience and finds somethingbetter to do. The file is seekable, in that one can do something like thefollowing:
Then concatenate the output files out1 and out2 and get the rightresult. Yes, it is a thoroughly useless module, but the point is to showhow the mechanism works without getting lost in other details. (Thosewanting to see the full source for this module can find it athttps://lwn.net/Articles/22359/).
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:
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: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. SEQ_START_TOKEN has no special meaning to the core seq_filecode. It is provided as a convenience for a start()
funciton tocommunicate with the next() and show() functions.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:
The next() function should set
*pos
to a value that start()
can useto find the new location in the sequence. When the iterator is beingstored in the private data area, rather than being reinitialized on eachstart()
, it might seem sufficient to simply set *pos
to any non-zerovalue (zero always tells start()
to restart the sequence). This is notsufficient due to historical problems.Historically, many next() functions have not updated
*pos
atend-of-file. If the value is then used by start()
to initialise theiterator, this can result in corner cases where the last entry in thesequence is reported twice in the file. In order to discourage this bugfrom being resurrected, the core seq_file code now produces a warning ifa next() function does not change the value of *pos
. Consequently anext() function must change the value of *pos
, and of course mustset it to a non-zero value.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:Finally, the show() function should format the object currently pointed toby the iterator for output. The example module’s show() function is:
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:
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 like
printk()
, but which requires the seq_file pointer as an argument.For straight character output, the following functions may be used:
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:
Here, path indicates the file of interest, and esc is a set of characterswhich should be escaped in the output. A call to
seq_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:
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:
Here, the call to
seq_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 to
seq_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.: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.:
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:
There is also a seq_release_private() which passes the contents of theseq_file private field to
kfree()
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:
And that is pretty much it.
seq_list¶
If your file will be iterating through a linked list, you may find theseroutines useful:
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:
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 of
seq_release()
in the file_operations structureto avoid a memory leak.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
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:
Open Seq File
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.
How To Open Seq File
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.
File Extension Hus
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
If you only need a single function entry (call) to produce all the desired proc-fs output, just use single_open() and single_release().
How To Open Rsm 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