=head1 NAME

Linux::Clone - an interface to the linux clone, unshare, setns, pivot_root and kcmp syscalls

=head1 SYNOPSIS

 use Linux::Clone;

=head1 DESCRIPTION

This module exposes the linux clone(2), unshare(2) and related syscalls to
Perl.

=over 4

=item $retval = unshare $flags

The following CLONE_ flag values (without CLONE_ prefix) are supported for
unshare, if found, in this release. See the documentation for unshare(2)
for more info on what they do:

   Linux::Clone::FILES
   Linux::Clone::FS
   Linux::Clone::NEWNS   (in unshare, implies FS)
   Linux::Clone::VM      (in unshare, implies SIGHAND)
   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.

   Linux::Clone::unshare Linux::Clone::NEWNET
      and "unshare: $!";
   system "ifconfig -a";

Example: unshare the network namespace, initialise the loopback interface,
create a veth interface pair, put one interface into the parent processes
namespace (use ifconfig -a from another shell), configure the other
interface with 192.168.99.2 -> 192.168.99.1 and start a shell.

   use Linux::Clone;

   # unshare our network namespace
   Linux::Clone::unshare Linux::Clone::NEWNET
     and "unshare: $!";

   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

      # move veth_master to our parent process' namespace
      ip link set veth_master netns $ppid

      # configure the local interface
      ip link set veth_slave up
      ip addr add 192.168.99.2/32 dev veth_slave
      ip route add 192.168.99.1/32 dev veth_slave
   ";

   print <<EOF;
   say hi to your new network namespace, use exit to return.

   try this from another shell to get networking up:

   ip link set veth_master up
   ip addr add 192.168.99.1/32 dev veth_master
   ip route add 192.168.99.2/32 dev veth_master

   EOF
   system "bash";

Example: unshare the filesystem namespace and make a confusing bind mount
only visible to the current process.

   use Linux::Clone;

   Linux::Clone::unshare Linux::Clone::NEWNS
      and die "unshare: $!";

   # now bind-mount /lib over /etc and ls -l /etc - scary
   system "mount -n --bind /lib /etc";
   system "ls -l /etc";

=item $retval = Linux::Clone::clone $coderef, $stacksize, $flags[, $ptid, $tls, $ctid]

Clones a new process as specified via C<$flags> and calls C<$coderef>
without any arguments (a closure might help you if you need to pass
arguments without global variables). The return value from coderef is
returned to the system.

The C<$stacksize> specifies how large a stack to allocate for the
child. If it is C<0>, then a default stack size (currently 4MB) will be
allocated. There is currently no way to free this area again in the child.

C<$ptid>, if specified, will receive the thread id, C<$tls>, if specified,
must contain a C<struct user_desc> and C<$ctid> is currently totally
unsupported and must not be specified.

Since this call basically bypasses both perl and your libc (for example,
C<$$> might reflect the parent I<or> child pid in the child), you need to
be very careful when using this call, which means you should probably have
a very good understanding of perl memory management and how fork and clone
work.

The following flags are supported for clone, in addition to all flags
supported by C<unshare>, above, and a signal number. When in doubt, refer
to the clone(2) manual page.

   Linux::Clone::PTRACE
   Linux::Clone::VFORK
   Linux::Clone::SETTLS         (not yet implemented)
   Linux::Clone::PARENT_SETTID  (not yet implemented)
   Linux::Clone::CHILD_SETTID   (not yet implemented)
   Linux::Clone::CHILD_CLEARTID (not yet implemented)
   Linux::Clone::DETACHED
   Linux::Clone::UNTRACED
   Linux::Clone::IO

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
with that.

This is the glibc clone call, it cannot be used to emulate fork.

Example: do a fork-like clone, sharing nothing, slightly confusing perl
and your libc, and exit immediately.

   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::NEUTS>, 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>.


=back

=cut

package Linux::Clone;

# use common::sense;

BEGIN {
   our $VERSION = '1.2';

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);
}

1;

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut