243 system manual pages should live with the software

Reviewed by: garrett@nexenta.com
Reviewed by: gwr@nexenta.com
Reviewed by: trisk@opensolaris.org
Approved by: gwr@nexenta.com

--HG--
extra : rebase_source : 0c599d0bec0dc8865fbba67721a7a6cd6b1feefb

1 files changed, 186 insertions, 0 deletions

diff --git a/usr/src/man/man2/vfork.2 b/usr/src/man/man2/vfork.2
new file mode 100644
index 0000000000..c93b666fc5
--- /dev/null
+++ b/usr/src/man/man2/vfork.2
@@ -0,0 +1,186 @@
+'\" te
+.\" Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright 1989 AT&T.
+.\" Copyright (c) 1980 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement  specifies the terms and conditions for redistribution.
+.TH vfork 2 "13 Dec 2006" "SunOS 5.11" "System Calls"
+.SH NAME
+vfork, vforkx \- spawn new process in a virtual memory efficient way
+.SH SYNOPSIS
+.LP
+.nf
+#include <unistd.h>
+
+\fBpid_t\fR \fBvfork\fR(\fBvoid\fR);
+.fi
+
+.LP
+.nf
+#include <sys/fork.h>
+
+\fBpid_t\fR \fBvforkx\fR(\fBint\fR \fIflags\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBvfork()\fR and \fBvforkx()\fR functions create a new process without
+fully copying the address space of the old process. These functions are useful
+in instances where the purpose of a \fBfork\fR(2) operation is to create a new
+system context for an \fBexecve()\fR operation (see \fBexec\fR(2)).
+.sp
+.LP
+Unlike with the \fBfork()\fR function, the child process borrows the parent's
+memory and thread of control until a call to \fBexecve()\fR or an exit (either
+abnormally or by a call to \fB_exit()\fR (see \fBexit\fR(2)). Any modification
+made during this time to any part of memory in the child process is reflected
+in the parent process on return from \fBvfork()\fR or \fBvforkx()\fR. The
+parent process is suspended while the child is using its resources.
+.sp
+.LP
+In a multithreaded application,  \fBvfork()\fR and \fBvforkx()\fR borrow only
+the thread of control that called \fBvfork()\fR or \fBvforkx()\fR in the
+parent; that is, the child contains only one thread. The use of \fBvfork()\fR
+or \fBvforkx()\fR in multithreaded applications, however, is unsafe due to race
+conditions that can cause the child process to become deadlocked and
+consequently block both the child and parent process from execution
+indefinitely.
+.sp
+.LP
+The \fBvfork()\fR and \fBvforkx()\fR functions can normally be used the same
+way as \fBfork()\fR and \fBforkx()\fR, respectively. The calling procedure,
+however, should not return while running in the child's context, since the
+eventual return from \fBvfork()\fR or \fBvforkx()\fR in the parent would be to
+a stack frame that no longer exists. The \fB_exit()\fR function should be used
+in favor of \fBexit\fR(3C) if unable to perform an \fBexecve()\fR operation,
+since \fBexit()\fR will invoke all functions registered by \fBatexit\fR(3C) and
+will flush and close standard I/O channels, thereby corrupting the parent
+process's standard I/O data structures. Care must be taken in the child process
+not to modify any global or local data that affects the behavior of the parent
+process on return from \fBvfork()\fR or \fBvforkx()\fR, unless such an effect
+is intentional.
+.sp
+.LP
+Unlike \fBfork()\fR and \fBforkx()\fR, fork handlers are not run when
+\fBvfork()\fR and \fBvforkx()\fR are called.
+.sp
+.LP
+The \fBvfork()\fR and \fBvforkx()\fR functions are deprecated. Their sole
+legitimate use as a prelude to an immediate call to a function from the
+\fBexec\fR family can be achieved safely by \fBposix_spawn\fR(3C) or
+\fBposix_spawnp\fR(3C).
+.SS "Fork Extensions"
+.sp
+.LP
+The \fBvforkx()\fR function accepts a \fIflags\fR argument consisting of a
+bitwise inclusive-OR of zero or more of the following flags, which are defined
+in the header \fB<sys/fork.h>\fR:
+.br
+.in +2
+\fBFORK_NOSIGCHLD\fR
+.in -2
+.br
+.in +2
+\fBFORK_WAITPID\fR
+.in -2
+.sp
+.LP
+See \fBfork\fR(2) for descriptions of these flags. If the \fIflags\fR argument
+is 0, \fBvforkx()\fR is identical to \fBvfork()\fR.
+.SH RETURN VALUES
+.sp
+.LP
+Upon successful completion, \fBvfork()\fR and \fBvforkx()\fR return  \fB0\fR to
+the child process and returns the process ID of the child process to the parent
+process. Otherwise, \fB\(mi1\fR is returned to the parent process, no child
+process is created, and \fBerrno\fR is set to indicate the error.
+.SH ERRORS
+.sp
+.LP
+The \fBvfork()\fR and \fBvforkx()\fR functions will fail if:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEAGAIN\fR\fR
+.ad
+.RS 10n
+.rt  
+The system-imposed limit on the total number of processes under execution
+(either system-quality or by a single user) would be exceeded. This limit is
+determined when the system is generated.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBENOMEM\fR\fR
+.ad
+.RS 10n
+.rt  
+There is insufficient swap space for the new process.
+.RE
+
+.sp
+.LP
+The \fBvforkx()\fR function will fail if:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fIflags\fR argument is invalid.
+.RE
+
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+Interface StabilityObsolete
+_
+MT-LevelUnsafe
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBioctl\fR(2), \fBatexit\fR(3C),
+\fBexit\fR(3C), \fBposix_spawn\fR(3C), \fBposix_spawnp\fR(3C),
+\fBsignal.h\fR(3HEAD), \fBwait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
+.SH NOTES
+.sp
+.LP
+To avoid a possible deadlock situation, processes that are children in the
+middle of a \fBvfork()\fR or \fBvforkx()\fR are never sent \fBSIGTTOU\fR or
+\fBSIGTTIN\fR signals; rather, output or ioctls are allowed and input attempts
+result in an \fBEOF\fR indication.
+.sp
+.LP
+To forestall parent memory corruption due to race conditions with signal
+handling, \fBvfork()\fR and \fBvforkx()\fR treat signal handlers in the child
+process in the same manner as the \fBexec\fR(2) functions: signals set to be
+caught by the parent process are set to the default action (\fBSIG_DFL\fR) in
+the child process (see \fBsignal.h\fR(3HEAD)). Any attempt to set a signal
+handler in the child before \fBexecve()\fR to anything other than \fBSIG_DFL\fR
+or \fBSIG_IGN\fR is disallowed and results in setting the handler to
+\fBSIG_DFL\fR.
+.sp
+.LP
+On some systems, the implementation of \fBvfork()\fR and \fBvforkx()\fR cause
+the parent to inherit register values from the child. This can create problems
+for certain optimizing compilers if \fB<unistd.h>\fR is not included in the
+source calling \fBvfork()\fR or if \fB<sys/fork.h>\fR is not included in the
+source calling \fBvforkx()\fR.