[PATCH] ptrace: Clarify PTRACE_GETREGSET/PTRACE_SETREGSET documentation in uapi header

[Pedro Alves]

The current comments don't explicitly state in plain words that
iov.len must be set to the buffer's length prior to the ptrace call.
A user might get confused and leave that uninitialized.

In the ptrace_regset function (snippet below) we see that the buffer
length has to be a multiple of the slot/register size for the given
NT_XXX_TYPE:

        if (!regset || (kiov->iov_len % regset->size) != 0)
                return -EINVAL;

Note regset->size is the size of each slot/register in the set, not
the size of the whole set.

And then, we see here:

 kiov->iov_len = min(kiov->iov_len,
                            (__kernel_size_t) (regset->n * regset->size));

that the kernel takes care of capping the requested length to the size
of the whole regset.

Signed-off-by: Pedro Alves <palves@xxxxxxxxxx>
Reported-by: Anshuman Khandual <khandual@xxxxxxxxxxxxxxxxxx>
---
 include/uapi/linux/ptrace.h | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/include/uapi/linux/ptrace.h b/include/uapi/linux/ptrace.h
index cf1019e..30836b9 100644
--- a/include/uapi/linux/ptrace.h
+++ b/include/uapi/linux/ptrace.h
@@ -39,12 +39,17 @@
  * payload are exactly the same layout.
  *
  * This interface usage is as follows:
- *	struct iovec iov = { buf, len};
+ *	struct iovec iov = { buf, len };
  *
  *	ret = ptrace(PTRACE_GETREGSET/PTRACE_SETREGSET, pid, NT_XXX_TYPE, &iov);
  *
- * On the successful completion, iov.len will be updated by the kernel,
- * specifying how much the kernel has written/read to/from the user's iov.buf.
+ * On entry, iov describes the buffer's address and length.  The buffer's length
+ * must be a multiple of the size of a single register in the register set.  The
+ * kernel never reads or writes more than iov.len, and caps the buffer length to
+ * the register set's size.  In other words, the kernel reads or writes
+ * min(iov.len, regset size).  On successful completion, iov.len is updated by
+ * the kernel, specifying how much the kernel has read from / written to the
+ * user's iov.buf.
  */
 #define PTRACE_GETREGSET	0x4204
 #define PTRACE_SETREGSET	0x4205
-- 
1.9.0


--
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/