Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1759389AbXFUUst (ORCPT ); Thu, 21 Jun 2007 16:48:49 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1758838AbXFUUsh (ORCPT ); Thu, 21 Jun 2007 16:48:37 -0400 Received: from wireless-243.media.mit.edu ([18.85.18.243]:44033 "EHLO localhost.localdomain" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1758591AbXFUUsf (ORCPT ); Thu, 21 Jun 2007 16:48:35 -0400 X-Greylist: delayed 2228 seconds by postgrey-1.27 at vger.kernel.org; Thu, 21 Jun 2007 16:48:35 EDT Date: Thu, 21 Jun 2007 16:11:35 -0400 (EDT) From: "C. Scott Ananian" To: linux-kernel@vger.kernel.org Subject: [PATCH] update procfs-guide doc of read_func Message-ID: X-GPG-FINGRPRINT: 6ED80418 - D62F 6DEB F5AC 91F7 7197 A212 8A62 ED98 6ED8 0418 X-GPG-FINGRPRINT: 85AD9EED - ADC0 4908 9167 DFD7 FA04 1AEE 09E8 44B0 X-GPG-PUBLIC_KEY: http://cscott.net/publickey.asc MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 5911 Lines: 131 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. --scott Echelon KUGOWN COBRA JANE Mk 48 PANCHO mustard MKSEARCH RUCKUS fissionable ( http://cscott.net/ ) diff -ruHpN -X dontdiff linux-2.6.22-rc5-orig/Documentation/DocBook/procfs-guide.tmpl linux-2.6.22-rc5/Documentation/DocBook/procfs-guide.tmpl --- linux-2.6.22-rc5-orig/Documentation/DocBook/procfs-guide.tmpl 2007-06-16 22:09:12.000000000 -0400 +++ linux-2.6.22-rc5/Documentation/DocBook/procfs-guide.tmpl 2007-06-21 14:12:22.000000000 -0400 @@ -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. - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/