diff options
Diffstat (limited to 'Documentation/DocBook')
-rw-r--r-- | Documentation/DocBook/procfs-guide.tmpl | 82 |
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. |