Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 6b86e854 authored by C. Scott Ananian's avatar C. Scott Ananian Committed by Linus Torvalds
Browse files

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: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent f4895925

Documentation/DocBook/procfs-guide.tmpl

+63 −19
Original line number Diff line number Diff line
@@ -352,48 +352,92 @@ 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>.

      </para>

        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