[RFC][v6][PATCH 9/9]: Document clone_with_pids() syscall

[Sukadev Bhattiprolu]

Thanks for the review. Will fix the typos.

Randy Dunlap [randy.dunlap at oracle.com] wrote:
| > +Example:
| > +
| > +	struct pid_set pid_set { 3, {0, 99, 177} };
| > +	void *child_stack = malloc(STACKSIZE);
| > +
| > +	/* set up child_stack, like with clone() */
| > +	rc = clone_with_pids(clone_flags, child_stack, NULL, NULL, &pid_set);
| > +
| > +	if (rc < 0) {
| > +		perror("clone_with_pids()");
| > +		exit(1);
| > +	}
| 
| What happens when one of the pids is busy?  Say the last one in the
| example above [177].  Are the first 2 children already cloned
| or are all pids checked for availability before cloning?

Only _one_ one child process is created (on success). With nested pid
namespaces a process is known by different pids (or pid numbers to be
precise) - one in each pid namespace.

(BTW, looks like we did not document pid-namespaces in the Documentation/
But please see the CLONE_NEWPID section of a recent version of clone(2)).

In short, the above clone_with_pids() tries to create a single child process
with the given pids.

| If the latter, is there a race there?
| and what value is returned?

There is no race - bc just a single process is being created.

If any of the pids are not available, the child process is not created
and the system call returns -EBUSY (if the user requested say 99 and 99
is in use by another process)