<commit_before>The seq_file interface

	Copyright 2003 <NAME> <<EMAIL>>
	This file is originally from the LWN.net Driver Porting series at
	http://lwn.net/Articles/driver-porting/


There are numerous ways for a device driver (or other kernel component) to
provide information to the user or system administrator.  One useful
technique is the creation of virtual files, in debugfs, /proc or elsewhere.
Virtual files can provide human-readable output that is easy to get at
without any special utility programs; they can also make life easier for
script writers. It is not surprising that the use of virtual files has
grown 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 a
string. But life gets trickier if the output is long - anything greater
than an application is likely to read in a single operation.  Handling
multiple reads (and seeks) requires careful attention to the reader's
position within the virtual file - that position is, likely as not, in the
middle of a line of output. The kernel has traditionally had a number of
implementations 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 it
right.

The seq_file interface is available via <linux/seq_file.h>. There are
three aspects to seq_file:

     * An iterator interface which lets a virtual file implementation
       step through the objects it is presenting.

     * Some utility functions for formatting objects for output without
       needing to worry about things like output buffers.

     * A set of canned file_operations which implement most operations on
       the virtual file.

We'll look at the seq_file interface via an extremely simple example: a
loadable module which creates a file called /proc/sequence. The file, when
read, simply produces a set of increasing integer values, one per line. The
sequence will continue until the user loses patience and finds something
better to do. The file is seekable, in that one can do something like the
following:

    dd if=/proc/sequence of=out1 count=1
    dd if=/proc/sequence skip=1 out=out2 count=1

Then concatenate the output files out1 and out2 and get the right
result. Yes, it is a thoroughly useless module, but the point is to show
how the mechanism works without getting lost in other details.  (Those
wanting to see the full source for this module can find it at
http://lwn.net/Articles/22359/).

<commit_msg>Doc: seq_file.txt fix wrong dd command example.<commit_after>The seq_file interface

	Copyright 2003 <NAME> <<EMAIL>>
	This file is originally from the LWN.net Driver Porting series at
	http://lwn.net/Articles/driver-porting/


There are numerous ways for a device driver (or other kernel component) to
provide information to the user or system administrator.  One useful
technique is the creation of virtual files, in debugfs, /proc or elsewhere.
Virtual files can provide human-readable output that is easy to get at
without any special utility programs; they can also make life easier for
script writers. It is not surprising that the use of virtual files has
grown 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 a
string. But life gets trickier if the output is long - anything greater
than an application is likely to read in a single operation.  Handling
multiple reads (and seeks) requires careful attention to the reader's
position within the virtual file - that position is, likely as not, in the
middle of a line of output. The kernel has traditionally had a number of
implementations that got this wrong.

The 2.6 kernel contains a set of functions (implemented by <NAME>)
which are designed to make it easy for virtual file creators to get it
right.

The seq_file interface is available via <linux/seq_file.h>. There are
three aspects to seq_file:

     * An iterator interface which lets a virtual file implementation
       step through the objects it is presenting.

     * Some utility functions for formatting objects for output without
       needing to worry about things like output buffers.

     * A set of canned file_operations which implement most operations on
       the virtual file.

We'll look at the seq_file interface via an extremely simple example: a
loadable module which creates a file called /proc/sequence. The file, when
read, simply produces a set of increasing integer values, one per line. The
sequence will continue until the user loses patience and finds something
better to do. The file is seekable, in that one can do something like the
following:

    dd if=/proc/sequence of=out1 count=1
    dd if=/proc/sequence skip=1 of=out2 count=1

Then concatenate the output files out1 and out2 and get the right
result. Yes, it is a thoroughly useless module, but the point is to show
how the mechanism works without getting lost in other details.  (Those
wanting to see the full source for this module can find it at
http://lwn.net/Articles/22359/).


{'fraction_non_alphanumeric': 0.03773950067737565, 'fraction_numerical': 0.0069672924327462745, 'mean_word_length': 4.01747572815534, 'pattern_counts': {'":': 0, '<': 12, '<?xml version=': 0, '>': 12, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3416975', 'n_tokens_mistral': 1302, 'n_tokens_neox': 1233, 'n_words': 797}