Skip to contentSkip to conversation

Improve capget manpage

PATCH In review Andi Kleen 2 participants 4 messages Jan 26, 2009 – Jan 27, 2009 3 messages not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

Andi Kleen

author
#0 lore raw

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
#2 lore raw
In reply to a message not in the archive

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
author
#4 lore raw
In reply to a message not in the archive
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

#6 lore raw
In reply to a message not in the archive

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 at
git:// 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