[PATCH][git pull] uaccess: add example to copy_word_from_user incomment

[Steven Rostedt]

Ingo,

Please pull the latest tip/tracing/ftrace tree, which can be found at:

  git://git.kernel.org/pub/scm/linux/kernel/git/rostedt/linux-2.6-trace.git
tip/tracing/ftrace


Steven Rostedt (1):
      uaccess: add example to copy_word_from_user in comment

----
 lib/uaccess.c |   39 ++++++++++++++++++++++++++++++++++++++-
 1 files changed, 38 insertions(+), 1 deletions(-)
---------------------------
commit bdec54d5f42a6e702a35687ab110751968c9a4d9
Author: Steven Rostedt <srostedt@xxxxxxxxxx>
Date:   Wed Feb 25 17:14:40 2009 -0500

    uaccess: add example to copy_word_from_user in comment
    
    Andrew Morton suggested an example of use for copy_word_from_user.
    This patch adds an example in the kernel doc of the function.
    It also clears up what is returned.
    
    Reported-by: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
    Signed-off-by: Steven Rostedt <srostedt@xxxxxxxxxx>

diff --git a/lib/uaccess.c b/lib/uaccess.c
index 5b9a4ac..2dda756 100644
--- a/lib/uaccess.c
+++ b/lib/uaccess.c
@@ -30,8 +30,45 @@
  * Note, if skip is not set, and white space exists at the beginning
  *  it will return immediately.
  *
+ * Example of use:
+ *
+ *  in user space a write(fd, "foo  bar zot", 12) is done. We want to
+ *  read three words.
+ *
+ *  len = 12;  - length of user buffer
+ *  ret = copy_word_from_user(buf, ubuf, 100, len, @copied, 1);
+ *    ret will equal 4 ("foo " read)
+ *    buf will contain "foo"
+ *    copied will equal 3 ("foo" copied)
+ *    Note, @skip could be 1 or zero and the same would have happened
+ *          since there was no leading white space.
+ *
+ *  len -= ret;  - 4 bytes was read
+ *  read = ret;
+ *  ret = copy_word_from_user(buf, ubuf+read, 100, len, @copied, 1);
+ *    ret will equal 5 (" bar " read, notice the double space between
+ *                       foo and bar in the original write.)
+ *    buf will contain "bar"
+ *    copied will equal 3 ("bar" copied)
+ *    Note, @skip is 1, if it was zero the results would be different.
+ *          (see below)
+ *
+ *  len -= ret; - 5 bytes read
+ *  read += ret;
+ *  ret = copy_word_from_user(buf, ubuf+read, 100, len, @copied, 1);
+ *   ret = -EAGAIN (no space after "zot")
+ *   buf will contain "zot"
+ *   copied will equal 3 ("zot" copied)
+ *
+ * If the second copy_word_from_user above had 0 for @skip, where we
+ * did not want to skip leading white space (" bar zot")
+ *   ret will equal 1 (" " read)
+ *   buf will not be modified
+ *   copied will equal 0 (nothing copied).
+ *
  * Returns:
- *  The number of bytes read from user space
+ *  The number of bytes read from user space (@from). This may or may not
+ *  be the same as what was copied into @to.
  *
  *  -EAGAIN, if we copied a word successfully, but never hit
  *    ending white space. The number of bytes copied will be the same

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/