From 3d5f459509b614a918829519ee965703800bc7fd Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Tue, 21 Mar 2006 05:42:30 +0000
Subject: [PATCH] Various rewordings and updates to 2.6.16 reality.

---
 man2/unshare.2 | 59 ++++++++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 19 deletions(-)

diff --git a/man2/unshare.2 b/man2/unshare.2
index 00fe3f3d8..dfc78cc28 100644
--- a/man2/unshare.2
+++ b/man2/unshare.2
@@ -62,7 +62,9 @@ or
 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, 
 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
 .\" flags of the same name.
-This flag has the same effect as the
+This flag has the 
+.I same 
+effect as the
 .BR clone (2)
 .B CLONE_NEWNS
 flag.
@@ -72,25 +74,37 @@ Specifying this flag automatically implies
 .B CLONE_FS
 as well.
 .\" As at 2.6.16, the following forced implications also apply,
-.\" although CLONE_THREAD and CLONE_SIGHAND are not yet implemented.
+.\" although the relevant flags are not yet implemented.
 .\" If CLONE_THREAD is set force CLONE_VM.
 .\" If CLONE_VM is set, force CLONE_SIGHAND. 
 .\" If CLONE_SIGHAND is set and signals are also being shared 
 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
-.TP
-.B CLONE_VM
-Reverse the effect of the
-.BR clone (2)
-.B CLONE_VM
-flag.
-.RB ( CLONE_VM
-is also implicitly set by
-.BR vfork (2),
-and can be reversed using this
-.BR unshare ()
-flag.)
-Unshare virtual memory, so that the calling process no 
-longer shares its virtual address space with any other process.
+.\"
+.\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented.
+.\" .TP
+.\" .B CLONE_VM
+.\" Reverse the effect of the
+.\" .BR clone (2)
+.\" .B CLONE_VM
+.\" flag.
+.\" .RB ( CLONE_VM
+.\" is also implicitly set by
+.\" .BR vfork (2),
+.\" and can be reversed using this
+.\" .BR unshare ()
+.\" flag.)
+.\" Unshare virtual memory, so that the calling process no 
+.\" longer shares its virtual address space with any other process.
+.PP
+Specifying any other bits in
+.I flags
+is likely to cause compatibility problems if the corresponding
+.B CLONE_* 
+values are implemented in future kernels.
+Avoid doing this.
+.\" FIXME . Check if a later kernel (e.g., 2.6.17) makes explicit
+.\" checks to prevent unimplemented bits being set in 'flags'.
+.\"
 .PP
 If 
 .I flags
@@ -137,13 +151,20 @@ In particular, as at kernel 2.6.16,
 .BR unshare () 
 does not implement flags that reverse the effects of
 .BR CLONE_SIGHAND ,
-.\" However we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
+.\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 .\" was not specified when doing clone(); i.e., unsharing
 .\" signal handlers is permitted if we are not actually
 .\" sharing signal handlers.   mtk
 .BR CLONE_SYSVSEM ,
-or 
-.BR CLONE_THREAD .
+.BR CLONE_THREAD ,
+or
+.\" FIXME . check future kernel versions (e.g., 2.6.17)
+.\" to see if CLONE_VM gets implemented.
+.BR CLONE_VM .
+.\" However, as at 2.6.16, we can do unshare(CLONE_VM) if CLONE_VM
+.\" was not specified when doing clone(); i.e., unsharing
+.\" virtual memory is permitted if we are not actually
+.\" sharing virtual memory.   mtk
 Such functionality may be added in the future, if required.
 .\"
 .\"9) Future Work