summaryrefslogtreecommitdiff
path: root/Documentation/DocBook
diff options
context:
space:
mode:
authorC. Scott Ananian <cscott@laptop.org>2007-07-16 10:41:13 +0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-07-16 20:05:48 +0400
commit6b86e854f71600c809536502a0efa9d4e384fb23 (patch)
tree25696d6d1aa803547c525f90345bca85d5cc3ed2 /Documentation/DocBook
parentf4895925976977aaeda26ee2a603a99f17db500b (diff)
downloadlinux-6b86e854f71600c809536502a0efa9d4e384fb23.tar.xz
update procfs-guide doc of read_func
The procfs-guide claims that 'the parameter start doesn't seem to be used anywhere in the kernel'. This is out of date. In linux/fs/proc/generic.c we find a very nice description of the parameters to read_func. The appended patch replaces the bogus description with this (as far as I know) accurate one. Cc: "Randy.Dunlap" <rdunlap@xenotime.net> Cc: "Eric W. Biederman" <ebiederm@xmission.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r--Documentation/DocBook/procfs-guide.tmpl82
1 files changed, 63 insertions, 19 deletions
diff --git a/Documentation/DocBook/procfs-guide.tmpl b/Documentation/DocBook/procfs-guide.tmpl
index 45cad23efefa..2de84dc195a8 100644
--- a/Documentation/DocBook/procfs-guide.tmpl
+++ b/Documentation/DocBook/procfs-guide.tmpl
@@ -352,49 +352,93 @@ entry->write_proc = write_proc_foo;
<funcsynopsis>
<funcprototype>
<funcdef>int <function>read_func</function></funcdef>
- <paramdef>char* <parameter>page</parameter></paramdef>
+ <paramdef>char* <parameter>buffer</parameter></paramdef>
<paramdef>char** <parameter>start</parameter></paramdef>
<paramdef>off_t <parameter>off</parameter></paramdef>
<paramdef>int <parameter>count</parameter></paramdef>
- <paramdef>int* <parameter>eof</parameter></paramdef>
+ <paramdef>int* <parameter>peof</parameter></paramdef>
<paramdef>void* <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The read function should write its information into the
- <parameter>page</parameter>. For proper use, the function
- should start writing at an offset of
- <parameter>off</parameter> in <parameter>page</parameter> and
- write at most <parameter>count</parameter> bytes, but because
- most read functions are quite simple and only return a small
- amount of information, these two parameters are usually
- ignored (it breaks pagers like <literal>more</literal> and
- <literal>less</literal>, but <literal>cat</literal> still
- works).
+ <parameter>buffer</parameter>, which will be exactly
+ <literal>PAGE_SIZE</literal> bytes long.
</para>
<para>
- If the <parameter>off</parameter> and
- <parameter>count</parameter> parameters are properly used,
- <parameter>eof</parameter> should be used to signal that the
+ The parameter
+ <parameter>peof</parameter> should be used to signal that the
end of the file has been reached by writing
<literal>1</literal> to the memory location
- <parameter>eof</parameter> points to.
+ <parameter>peof</parameter> points to.
</para>
<para>
- The parameter <parameter>start</parameter> doesn't seem to be
- used anywhere in the kernel. The <parameter>data</parameter>
+ The <parameter>data</parameter>
parameter can be used to create a single call back function for
several files, see <xref linkend="usingdata"/>.
</para>
<para>
- The <function>read_func</function> function must return the
- number of bytes written into the <parameter>page</parameter>.
+ The rest of the parameters and the return value are described
+ by a comment in <filename>fs/proc/generic.c</filename> as follows:
</para>
+ <blockquote>
+ <para>
+ You have three ways to return data:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Leave <literal>*start = NULL</literal>. (This is the default.)
+ Put the data of the requested offset at that
+ offset within the buffer. Return the number (<literal>n</literal>)
+ of bytes there are from the beginning of the
+ buffer up to the last byte of data. If the
+ number of supplied bytes (<literal>= n - offset</literal>) is
+ greater than zero and you didn't signal eof
+ and the reader is prepared to take more data
+ you will be called again with the requested
+ offset advanced by the number of bytes
+ absorbed. This interface is useful for files
+ no larger than the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set <literal>*start</literal> to an unsigned long value less than
+ the buffer address but greater than zero.
+ Put the data of the requested offset at the
+ beginning of the buffer. Return the number of
+ bytes of data placed there. If this number is
+ greater than zero and you didn't signal eof
+ and the reader is prepared to take more data
+ you will be called again with the requested
+ offset advanced by <literal>*start</literal>. This interface is
+ useful when you have a large file consisting
+ of a series of blocks which you want to count
+ and return as wholes.
+ (Hack by Paul.Russell@rustcorp.com.au)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set <literal>*start</literal> to an address within the buffer.
+ Put the data of the requested offset at <literal>*start</literal>.
+ Return the number of bytes of data placed there.
+ If this number is greater than zero and you
+ didn't signal eof and the reader is prepared to
+ take more data you will be called again with the
+ requested offset advanced by the number of bytes
+ absorbed.
+ </para>
+ </listitem>
+ </orderedlist>
+ </blockquote>
+
<para>
<xref linkend="example"/> shows how to use a read call back
function.