aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorC. Scott Ananian <cscott@laptop.org>2007-07-16 02:41:13 -0400
committerLinus Torvalds <torvalds@woody.linux-foundation.org>2007-07-16 12:05:48 -0400
commit6b86e854f71600c809536502a0efa9d4e384fb23 (patch)
tree25696d6d1aa803547c525f90345bca85d5cc3ed2 /Documentation
parentf4895925976977aaeda26ee2a603a99f17db500b (diff)
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')
-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;
352 <funcsynopsis> 352 <funcsynopsis>
353 <funcprototype> 353 <funcprototype>
354 <funcdef>int <function>read_func</function></funcdef> 354 <funcdef>int <function>read_func</function></funcdef>
355 <paramdef>char* <parameter>page</parameter></paramdef> 355 <paramdef>char* <parameter>buffer</parameter></paramdef>
356 <paramdef>char** <parameter>start</parameter></paramdef> 356 <paramdef>char** <parameter>start</parameter></paramdef>
357 <paramdef>off_t <parameter>off</parameter></paramdef> 357 <paramdef>off_t <parameter>off</parameter></paramdef>
358 <paramdef>int <parameter>count</parameter></paramdef> 358 <paramdef>int <parameter>count</parameter></paramdef>
359 <paramdef>int* <parameter>eof</parameter></paramdef> 359 <paramdef>int* <parameter>peof</parameter></paramdef>
360 <paramdef>void* <parameter>data</parameter></paramdef> 360 <paramdef>void* <parameter>data</parameter></paramdef>
361 </funcprototype> 361 </funcprototype>
362 </funcsynopsis> 362 </funcsynopsis>
363 363
364 <para> 364 <para>
365 The read function should write its information into the 365 The read function should write its information into the
366 <parameter>page</parameter>. For proper use, the function 366 <parameter>buffer</parameter>, which will be exactly
367 should start writing at an offset of 367 <literal>PAGE_SIZE</literal> bytes long.
368 <parameter>off</parameter> in <parameter>page</parameter> and
369 write at most <parameter>count</parameter> bytes, but because
370 most read functions are quite simple and only return a small
371 amount of information, these two parameters are usually
372 ignored (it breaks pagers like <literal>more</literal> and
373 <literal>less</literal>, but <literal>cat</literal> still
374 works).
375 </para> 368 </para>
376 369
377 <para> 370 <para>
378 If the <parameter>off</parameter> and 371 The parameter
379 <parameter>count</parameter> parameters are properly used, 372 <parameter>peof</parameter> should be used to signal that the
380 <parameter>eof</parameter> should be used to signal that the
381 end of the file has been reached by writing 373 end of the file has been reached by writing
382 <literal>1</literal> to the memory location 374 <literal>1</literal> to the memory location
383 <parameter>eof</parameter> points to. 375 <parameter>peof</parameter> points to.
384 </para> 376 </para>
385 377
386 <para> 378 <para>
387 The parameter <parameter>start</parameter> doesn't seem to be 379 The <parameter>data</parameter>
388 used anywhere in the kernel. The <parameter>data</parameter>
389 parameter can be used to create a single call back function for 380 parameter can be used to create a single call back function for
390 several files, see <xref linkend="usingdata"/>. 381 several files, see <xref linkend="usingdata"/>.
391 </para> 382 </para>
392 383
393 <para> 384 <para>
394 The <function>read_func</function> function must return the 385 The rest of the parameters and the return value are described
395 number of bytes written into the <parameter>page</parameter>. 386 by a comment in <filename>fs/proc/generic.c</filename> as follows:
396 </para> 387 </para>
397 388
389 <blockquote>
390 <para>
391 You have three ways to return data:
392 </para>
393 <orderedlist>
394 <listitem>
395 <para>
396 Leave <literal>*start = NULL</literal>. (This is the default.)
397 Put the data of the requested offset at that
398 offset within the buffer. Return the number (<literal>n</literal>)
399 of bytes there are from the beginning of the
400 buffer up to the last byte of data. If the
401 number of supplied bytes (<literal>= n - offset</literal>) is
402 greater than zero and you didn't signal eof
403 and the reader is prepared to take more data
404 you will be called again with the requested
405 offset advanced by the number of bytes
406 absorbed. This interface is useful for files
407 no larger than the buffer.
408 </para>
409 </listitem>
410 <listitem>
411 <para>
412 Set <literal>*start</literal> to an unsigned long value less than
413 the buffer address but greater than zero.
414 Put the data of the requested offset at the
415 beginning of the buffer. Return the number of
416 bytes of data placed there. If this number is
417 greater than zero and you didn't signal eof
418 and the reader is prepared to take more data
419 you will be called again with the requested
420 offset advanced by <literal>*start</literal>. This interface is
421 useful when you have a large file consisting
422 of a series of blocks which you want to count
423 and return as wholes.
424 (Hack by Paul.Russell@rustcorp.com.au)
425 </para>
426 </listitem>
427 <listitem>
428 <para>
429 Set <literal>*start</literal> to an address within the buffer.
430 Put the data of the requested offset at <literal>*start</literal>.
431 Return the number of bytes of data placed there.
432 If this number is greater than zero and you
433 didn't signal eof and the reader is prepared to
434 take more data you will be called again with the
435 requested offset advanced by the number of bytes
436 absorbed.
437 </para>
438 </listitem>
439 </orderedlist>
440 </blockquote>
441
398 <para> 442 <para>
399 <xref linkend="example"/> shows how to use a read call back 443 <xref linkend="example"/> shows how to use a read call back
400 function. 444 function.