Improve capget manpage
PATCH 1/1 Improve capget manpage
While writing a little program using capset
I found the capset manpage quite light on crucial
details and I had to resort to RTFS.
This patch improves the points I found unclear
and also moves one misplaced paragraph around.
-Andi
capget.2 renamed from capget.2-o +30 -14
@@ -6,6 +6,7 @@ .\" Modified 2008-04-28, morgan of kernel.org .\" Update in line with addition of file capabilities and .\" 64-bit capability sets in kernel 2.6.2[45]. +.\" Modified 2009-01-26, andi kleen .\" .TH CAPGET 2 2008-07-14 "Linux" "Linux Programmer's Manual" .SH NAME
@@ -36,7 +37,8 @@ but the kernel API is likely to change and use of these functions (in particular the format of the .I cap_user_*_t -types) is subject to change with each kernel revision. +types) is subject to extension with each kernel revision, +but old programs will keep working. .sp The portable interfaces are .BR cap_set_proc (3)
@@ -73,19 +75,19 @@ .fi .in -4n .sp -The calls will fail with the error -.BR EINVAL , -and set the -.I version -field of -.I hdrp -to the kernel preferred value of -.B _LINUX_CAPABILITY_VERSION_? -when an unsupported -.I version -value is specified. -In this way, one can probe what the current -preferred capability revision is. +.I effective, permitted, inheritable +are bitmasks of the capabilities defined in +.I capability(7). +Note the +.I CAP_* +defines are bit indexes and need to be shifted up before oring into +the bitfields. +To define the structures for passing to the syscall you have to use the +.I struct __user_cap_header_struct +and +.I struct __user_cap_data_struct +names because the typedefs are only pointers. + Kernels prior to 2.6.25 prefer 32-bit capabilities with version .BR _LINUX_CAPABILITY_VERSION_1 ,
@@ -154,6 +156,20 @@ On error, \-1 is returned, and .I errno is set appropriately. + +The calls will fail with the error +.BR EINVAL , +and set the +.I version +field of +.I hdrp +to the kernel preferred value of +.B _LINUX_CAPABILITY_VERSION_? +when an unsupported +.I version +value is specified. +In this way, one can probe what the current +preferred capability revision is. .SH ERRORS .TP .B EFAULT
Signature · 5 lines
ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only. -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 20090126202942.GA8753-3rXA9MLqAseW/qJFnhkgxti2O/[email protected]
Hi Andi,
Quoted 4 lines · Andi Kleen
While writing a little program using capset I found the capset manpage quite light on crucial details and I had to resort to RTFS.
Yes, I've always thought that page was a little thin, but had never got to checking the details.
Quoted 2 lines
This patch improves the points I found unclear and also moves one misplaced paragraph around.
Thanks. I applied this for man-pages-3.18.
Cheers,
Michael
Quoted 78 lines
capget.2 2009-01-26 21:26:24.000000000 +0100 renamed from capget.2-o 2009-01-26 21:19:13.000000000 +0100 +30
-15@@ -6,6 +6,7 @@ .\" Modified 2008-04-28, morgan of kernel.org .\" Update in line with addition of file capabilities and .\" 64-bit capability sets in kernel 2.6.2[45]. +.\" Modified 2009-01-26, andi kleen .\" .TH CAPGET 2 2008-07-14 "Linux" "Linux Programmer's Manual" .SH NAME@@ -36,7 +37,8 @@ but the kernel API is likely to change and use of these functions (in particular the format of the .I cap_user_*_t -types) is subject to change with each kernel revision. +types) is subject to extension with each kernel revision, +but old programs will keep working. .sp The portable interfaces are .BR cap_set_proc (3)@@ -73,19 +75,19 @@ .fi .in -4n .sp -The calls will fail with the error -.BR EINVAL , -and set the -.I version -field of -.I hdrp -to the kernel preferred value of -.B _LINUX_CAPABILITY_VERSION_? -when an unsupported -.I version -value is specified. -In this way, one can probe what the current -preferred capability revision is. +.I effective, permitted, inheritable +are bitmasks of the capabilities defined in +.I capability(7). +Note the +.I CAP_* +defines are bit indexes and need to be shifted up before oring into +the bitfields. +To define the structures for passing to the syscall you have to use the +.I struct __user_cap_header_struct +and +.I struct __user_cap_data_struct +names because the typedefs are only pointers. + Kernels prior to 2.6.25 prefer 32-bit capabilities with version .BR _LINUX_CAPABILITY_VERSION_1 ,@@ -154,6 +156,20 @@ On error, \-1 is returned, and .I errno is set appropriately. + +The calls will fail with the error +.BR EINVAL , +and set the +.I version +field of +.I hdrp +to the kernel preferred value of +.B _LINUX_CAPABILITY_VERSION_? +when an unsupported +.I version +value is specified. +In this way, one can probe what the current +preferred capability revision is. .SH ERRORS .TP .B EFAULT --ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only.
Signature · 9 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): cfd18e0f0901261644w1b6291d9m49c19c9962844c40-JsoAwUIsXosN+BqQ9rBEUg@public.gmane.org
Quoted 10 lines · Michael Kerrisk
Hi Andi,
Quoted 4 lines · Andi Kleen
While writing a little program using capset
I found the capset manpage quite light on crucial
details and I had to resort to RTFS.Yes, I've always thought that page was a little thin, but had never got to checking the details.
It's still not very good and could need some clarifications and a better introduction.
-Andi
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 20090127082630.GW15750-qrUzlfsMFqo/[email protected]
Andrew,
Quoted 9 lines · Andi Kleen
Quoted 8 lines · Michael Kerrisk
Hi Andi,
Quoted 4 lines · Andi Kleen
While writing a little program using capset
I found the capset manpage quite light on crucial
details and I had to resort to RTFS.
Quoted 5 lines
Quoted 2 lines
Yes, I've always thought that page was a little thin, but had never got to checking the details.
It's still not very good and could need some clarifications and a better introduction.
Any chance you could take a look at this page (current version atgit:// below), to see if you could come up with some quick improvements?
Cheers,
Michael
Signature · 9 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html