From 6b86e854f71600c809536502a0efa9d4e384fb23 Mon Sep 17 00:00:00 2001 From: "C. Scott Ananian" Date: Sun, 15 Jul 2007 23:41:13 -0700 Subject: [PATCH] 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" Cc: "Eric W. Biederman" Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- Documentation/DocBook/procfs-guide.tmpl | 82 +++++++++++++++++++------ 1 file 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; int read_func - char* page + char* buffer char** start off_t off int count - int* eof + int* peof void* data The read function should write its information into the - page. For proper use, the function - should start writing at an offset of - off in page and - write at most count 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 more and - less, but cat still - works). + buffer, which will be exactly + PAGE_SIZE bytes long. - If the off and - count parameters are properly used, - eof should be used to signal that the + The parameter + peof should be used to signal that the end of the file has been reached by writing 1 to the memory location - eof points to. + peof points to. - The parameter start doesn't seem to be - used anywhere in the kernel. The data + The data parameter can be used to create a single call back function for several files, see . - The read_func function must return the - number of bytes written into the page. + The rest of the parameters and the return value are described + by a comment in fs/proc/generic.c as follows: +
+ + You have three ways to return data: + + + + + Leave *start = NULL. (This is the default.) + Put the data of the requested offset at that + offset within the buffer. Return the number (n) + of bytes there are from the beginning of the + buffer up to the last byte of data. If the + number of supplied bytes (= n - offset) 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. + + + + + Set *start 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 *start. 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) + + + + + Set *start to an address within the buffer. + Put the data of the requested offset at *start. + 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. + + + +
+ shows how to use a read call back function. -- GitLab