How is pivot_root intended to be used?

[Steven Stewart-Gallus <sstewartgallus00@mylangara.bc.ca>]

Hello,

I am not confused about how I can currently use pivot_root for
containers on my kernel (version 3.13). Currently a sequence like:

    if (-1 == syscall(__NR_pivot_root, ".", ".")) {
        perror("pivot_root");
        return EXIT_FAILURE;
    }

    if (-1 == umount2(".", MNT_DETACH)) {
        perror("umount");
        return EXIT_FAILURE;
    }

    /* pivot_root() may or may not affect its current working
     * directory.  It is therefore recommended to call chdir("/")
     * immediately after pivot_root().
     *
     * - http://man7.org/linux/man-pages/man2/pivot_root.2.html
     */
    if (-1 == chdir("/")) {
        perror("chdir");
        return EXIT_FAILURE;
    }

works. However, I am completely and totally confused about how the
pivot_root system call is intended to be used here and have absolutely
no idea if this will work in the future. This concerns me because I
don't want my program to potentially develop silent security bugs on
future versions of the Linux kernel.

Some information about the context. I am sandboxing a program just
after it has done a fork, unshared the mount namespace, setup a
sandbox directory and changed into it. If you just want to look at the
code, the actual code is avaliable at
https://gitorious.org/linted/linted/source/b25685ba4762bfb794c8f36ae74276d32d2b0ca8:src/spawn/spawn.c.

Thank you,
Steven Stewart-Gallus