Techwizz/kernel-fxtec-pro1x
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

update procfs-guide doc of read_func

Browse source 
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>
This commit is contained in:
C. Scott Ananian 2007-07-15 23:41:13 -07:00 committed by Linus Torvalds
parent f489592597
commit 6b86e854f7
1 changed files with 63 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

82
Documentation/DocBook/procfs-guide.tmpl
View file

@ -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.