--- Linux-Clone/Clone.pm	2011/11/28 05:43:03	1.1
+++ Linux-Clone/Clone.pm	2022/09/03 23:47:02	1.6
@@ -1,6 +1,6 @@
 =head1 NAME
 
-Linux::Clone - an interface to the linux clone(2) and unshare(2) syscalls
+Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls
 
 =head1 SYNOPSIS
 
@@ -8,8 +8,8 @@
 
 =head1 DESCRIPTION
 
-This module exposes the linux clone(2) and unshare(2) syscalls to
-Perl.
+This module exposes the linux clone(2), unshare(2) and some related
+syscalls to Perl.
 
 =over 4
 
@@ -26,16 +26,20 @@
    Linux::Clone::THREAD  (in unshare, implies VM, SIGHAND)
    Linux::Clone::SIGHAND
    Linux::Clone::SYSVSEM
+   Linux::Clone::NEWUSER (in unshare, implies CLONE_THREAD)
+   Linux::Clone::NEWPID
    Linux::Clone::NEWUTS
    Linux::Clone::NEWIPC
    Linux::Clone::NEWNET
+   Linux::Clone::NEWCGROUP
 
 Example: unshare the network namespace and prove that by calling ifconfig,
-showing only an unconfigured lo interface.
+showing only the unconfigured lo interface.
 
    Linux::Clone::unshare Linux::Clone::NEWNET
       and "unshare: $!";
-   system "ifconfig -a";
+   Linux::Clone::configure_loopback;
+   system "ifconfig";
 
 Example: unshare the network namespace, initialise the loopback interface,
 create a veth interface pair, put one interface into the parent processes
@@ -48,13 +52,11 @@
    Linux::Clone::unshare Linux::Clone::NEWNET
      and "unshare: $!";
 
+   Linux::Clone::configure_loopback;
+
    my $ppid = getppid;
 
    system "
-      # configure loopback interface
-      ip link set lo up
-      ip route add 127.0.0.0/8 dev lo
-
       # create veth pair
       ip link add name veth_master type veth peer name veth_slave
 
@@ -87,7 +89,7 @@
    Linux::Clone::unshare Linux::Clone::NEWNS
       and die "unshare: $!";
 
-   # now bind-mount /lib over /etc and ls -l /etc - scary
+   # now bind-mount /lib over /etc and ls -l /etc - looks scary
    system "mount -n --bind /lib /etc";
    system "ls -l /etc";
 
@@ -122,11 +124,11 @@
    Linux::Clone::PARENT_SETTID  (not yet implemented)
    Linux::Clone::CHILD_SETTID   (not yet implemented)
    Linux::Clone::CHILD_CLEARTID (not yet implemented)
+   Linux::Clone::PIDFD          (not yet implemented)
    Linux::Clone::DETACHED
    Linux::Clone::UNTRACED
-   Linux::Clone::NEWUSER
-   Linux::Clone::NEWPID
    Linux::Clone::IO
+   Linux::Clone::CSIGNAL exit signal mask
 
 Note that for practical reasons you basically must not use
 C<Linux::Clone::VM> or C<Linux::Clone::VFORK>, as perl is unlikely to cope
@@ -139,6 +141,38 @@
 
    my $pid = Linux::Clone::clone sub { warn "in child"; 77 }, 0, POSIX::SIGCHLD;
 
+=item Linux::Clone::setns $fh_or_fd[, $nstype]
+
+Calls setns(2) on the file descriptor (or file handle) C<$fh_or_fd>. If
+C<$nstype> is missing, then C<0> is used.
+
+The argument C<$nstype> can be C<0>, C<Linux::Clone::NEWIPC>,
+C<Linux::Clone::NEWNET>, C<Linux::Clone::NEWUTS>, C<Linux::Clone::NEWCGROUP>,
+C<Linux::Clone::NEWNS>, C<Linux::Clone::NEWPID> or C<Linux::Clone::NEWUSER>.
+
+=item Linux::Clone::pivot_root $new_root, $old_root
+
+Calls pivot_root(2) - refer to its manpage for details.
+
+=item Linux::Clone::kcmp $pid1, $pid2, $type[, $idx1, $idx2]
+
+Calls kcmp(2) - refer to its manpage for details on operations.
+
+The following C<$type> constants are available if the kcmp syscall number
+was available during compilation:
+
+C<Linux::Clone::KCMP_FILE>, C<Linux::Clone::KCMP_VM>, C<Linux::Clone::KCMP_FILES>,
+C<Linux::Clone::KCMP_FS>, C<Linux::Clone::KCMP_SIGHAND>, C<Linux::Clone::KCMP_IO> and
+C<Linux::Clone::KCMP_SYSVSEM>.
+
+=item Linux::Clone::configure_loopback
+
+Configures a working loopback interface (basically, does the equivalent of
+"ifconfig lo up" which automatically adds ipv4/ipv6 addresses and routes),
+which can be useful to get a network namespace going.
+
+Dies on error and returns nothing.
+
 =back
 
 =cut
@@ -148,12 +182,17 @@
 # use common::sense;
 
 BEGIN {
-   our $VERSION = '0.01';
+   our $VERSION = '1.3';
 
    require XSLoader;
    XSLoader::load (__PACKAGE__, $VERSION);
 }
 
+sub configure_loopback() {
+   siocsifflags "lo"
+      and die "Linux::Clone::configure_looopback: unable to bring up loopback interface: $!\n";
+}
+
 1;
 
 =head1 AUTHOR