From: Christian Brauner <christian.brauner@ubuntu.com>
Date: Fri, 15 Dec 2017 16:35:07 +0000 (+0100)
Subject: namespace: comment lxc_{raw_}clone()
X-Git-Tag: lxc-2.0.10~452
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3d3691a3a1da0490fc77ab634ff29ac24e9fafbc;p=thirdparty%2Flxc.git

namespace: comment lxc_{raw_}clone()

Signed-off-by: Christian Brauner <christian.brauner@ubuntu.com>
---

diff --git a/src/lxc/namespace.h b/src/lxc/namespace.h
index 3779ee767..871e81e1a 100644
--- a/src/lxc/namespace.h
+++ b/src/lxc/namespace.h
@@ -112,7 +112,57 @@ int clone(int (*fn)(void *), void *child_stack,
 	/* pid_t *ptid, struct user_desc *tls, pid_t *ctid */ );
 #endif
 
+/**
+ * lxc_clone() - create a new process
+ *
+ * - allocate stack:
+ *   This function allocates a new stack the size of page and passes it to the
+ *   kernel.
+ *
+ * - support all CLONE_*flags:
+ *   This function supports all CLONE_* flags. If in doubt or not sufficiently
+ *   familiar with process creation in the kernel and interactions with libcs
+ *   this function should be used.
+ *
+ * - pthread_atfork() handlers depending on libc:
+ *   Whether this function runs pthread_atfork() handlers depends on the
+ *   corresponding libc wrapper. glibc currently does not run pthread_atfork()
+ *   handlers but does not guarantee that they are not. Other libcs might or
+ *   might not run pthread_atfork() handlers. If you require guarantees please
+ *   refer to the lxc_raw_clone() function below.
+ *
+ * - should call lxc_raw_getpid():
+ *   The child should use lxc_raw_getpid() to retrieve its pid.
+ */
 extern pid_t lxc_clone(int (*fn)(void *), void *arg, int flags);
+
+/**
+ * lxc_raw_clone() - create a new process
+ *
+ * - fork() behavior:
+ *   This function returns 0 in the child and > 0 in the parent.
+ *
+ * - copy-on-write:
+ *   This function does not allocate a new stack and relies on copy-on-write
+ *   semantics.
+ *
+ * - supports subset of ClONE_* flags:
+ *   lxc_raw_clone() intentionally only supports a subset of the flags available
+ *   to the actual system call. Please refer to the implementation what flags
+ *   cannot be used. Also, please don't assume that just because a flag isn't
+ *   explicitly checked for as being unsupported that it is supported. If in
+ *   doubt or not sufficiently familiar with process creation in the kernel and
+ *   interactions with libcs this function should be used.
+ *
+ * - no pthread_atfork() handlers:
+ *   This function circumvents - as much as this this is possible - any libc
+ *   wrappers and thus does not run any pthread_atfork() handlers. Make sure
+ *   that this is safe to do in the context you are trying to call this
+ *   function.
+ *
+ * - must call lxc_raw_getpid():
+ *   The child must use lxc_raw_getpid() to retrieve its pid.
+ */
 extern pid_t lxc_raw_clone(unsigned long flags);
 
 extern int lxc_namespace_2_cloneflag(char *namespace);