[src/trunk]: src/lib/libc/sys Manual page for clone(2).

[thorpej <thorpej%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7bf97db71e88
branches:  trunk
changeset: 512786:7bf97db71e88
user:      thorpej <thorpej%NetBSD.org@localhost>
date:      Tue Jul 17 03:05:31 2001 +0000

description:
Manual page for clone(2).

diffstat:

 lib/libc/sys/clone.2 |  162 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 162 insertions(+), 0 deletions(-)

diffs (166 lines):

diff -r b53728337631 -r 7bf97db71e88 lib/libc/sys/clone.2
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/sys/clone.2      Tue Jul 17 03:05:31 2001 +0000
@@ -0,0 +1,162 @@
+.\"    $NetBSD: clone.2,v 1.1 2001/07/17 03:05:31 thorpej Exp $
+.\"
+.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jason R. Thorpe.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd July 16, 2001
+.Dt CLONE 2
+.Os
+.Sh NAME
+.Nm clone
+.Nd spawn new process with options
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.Fd #include <sched.h>
+.Ft pid_t
+.Fn clone "int (*func)" "void *arg" "void *stack" "int flags" "void *arg"
+.Ft pid_t
+.Fn __clone "int (*func)" "void *arg" "void *stack" "int flags" "void *arg"
+.Sh DESCRIPTION
+The
+.Nm
+system call (and associated library support code) creates a new process
+in a way that allows the caller to specify several options for the new
+process creation.
+.Pp
+Unlike
+.Xr fork 2
+or
+.Xr vfork 2 ,
+in which the child process returns to the call site,
+.Nm
+causes the child process to begin execution at the function specified
+by
+.Ar func .
+The argument
+.Ar arg
+is passed to the entry point, as a means for the parent to provide
+context to the child.  The stack pointer for the child process will
+be set to
+.Ar stack .
+Note that the
+.Nm
+interface requires that the application know the stack direction
+for the architecture, and that the caller initialize the
+.Ar stack
+argument as appropriate for the stack direction.
+.Pp
+The
+.Ar flags
+argument specifies several options that control how the child process
+is created.  The lower 8 bits of
+.Ar flags
+specify the signal that is to be sent to the parent when the child
+exits.  The following flags may also be specified by bitwise-or'ing
+them with the signal value:
+.Bl -tag -width "CLONE_SIGHAND"
+.It Dv CLONE_VM
+Share the virtual address space with the parent.  The address
+space is shared in the same way as
+.Xr vfork 2 .
+.It Dv CLONE_FS
+Share the
+.Dq file system information
+with the parent.  This include the current working directory and file
+creation mask.
+.It Dv CLONE_FILES
+Share the file descriptor table with the parent.
+.It Dv CLONE_SIGHAND
+Share the signal handler set with the parent.  Note that the signal mask
+is never shared between the parent and the child, even if
+.Dv CLONE_SIGHAND
+is set.
+.El
+.Pp
+The 
+.Nm
+call returns the pid of the child in the parent's context.  The child
+is provided no return value, since it begins execution at a different
+address.
+.Pp
+If the child process's entry point returns, the value it returns
+is passed to
+.Xr _exit 2 ,
+and the child process exits.  Note that if the child process wants
+to exit directly, it should use
+.Xr _exit 2 ,
+and not
+.Xr exit 3 ,
+since
+.Xr exit 3
+will flush and close standard I/O channels, and thereby corrupt the
+parent process's standard I/O data structures (even with
+.Xr fork 2
+it is wrong to call
+.Xr exit 3
+since buffered data would then be flushed twice).
+.Pp
+Note that
+.Nm
+is not intended to be used for new native
+.Nx
+applications.  It is provided as a means to port software
+originally written for the Linux operating system to
+.Nx .
+.Sh RETURN VALUES and ERRORS
+Same as for
+.Xr fork 2 .
+.Sh SEE ALSO
+.Xr chdir 2 ,
+.Xr chroot 2 ,
+.Xr fork 2 ,
+.Xr vfork 2 ,
+.Xr sigaction 2 ,
+.Xr sigprocmask 2 ,
+.Xr umask 2 ,
+.Xr wait 2
+.Sh BUGS
+The
+.Nx
+implentation of
+.Nm
+does not implement the
+.Dv CLONE_PID
+option that is present in the Linux implementation.
+.Sh HISTORY
+The
+.Fn clone
+function call appeared in
+.Nx 1.6 .
+It is compatible with the Linux function call of the same name.