1 files changed, 159 insertions, 0 deletions
diff --git a/man/man3/exec.3 b/man/man3/exec.3
new file mode 100644
index 00000000..5ce9583a
--- /dev/null
+++ b/man/man3/exec.3
@@ -0,0 +1,159 @@
+.TH EXEC 3
+.SH NAME
+exec, execl, _clock, _privates, _nprivates \- execute a file
+.SH SYNOPSIS
+.B #include <u.h>
+.br
+.B #include <libc.h>
+.PP
+.nf
+.B
+int exec(char *name, char* argv[])
+.PP
+.B
+int execl(char *name, ...)
+.PP
+.B
+long	*_clock;
+.PP
+.B
+void	**_privates;
+.PP
+.B
+int	_nprivates;
+.fi
+.SH DESCRIPTION
+.I Exec
+and
+.I execl
+overlay the calling process with the named file, then
+transfer to the entry point of the image of the file.
+.PP
+.I Name
+points to the name of the file
+to be executed; it must not be a directory, and the permissions
+must allow the current user to execute it
+(see
+.IR stat (2)).
+It should also be a valid binary image, as defined in the
+.IR a.out (6)
+for the current machine architecture,
+or a shell script
+(see
+.IR rc (1)).
+The first line of a
+shell script must begin with
+.L #!
+followed by the name of the program to interpret the file
+and any initial arguments to that program, for example
+.IP
+.EX
+#!/bin/rc
+ls | mc
+.EE
+.PP
+When a C program is executed,
+it is called as follows:
+.IP
+.EX
+void main(int argc, char *argv[])
+.EE
+.PP
+.I Argv
+is a copy of the array of argument pointers passed to
+.IR exec ;
+that array must end in a null pointer, and
+.I argc
+is the number of elements before the null pointer.
+By convention, the first argument should be the name of
+the program to be executed.
+.I Execl
+is like
+.I exec
+except that
+.I argv
+will be an array of the parameters that follow
+.I name
+in the call.  The last argument to
+.I execl
+must be a null pointer.
+.PP
+For a file beginning
+.BR #! ,
+the arguments passed to the program
+.RB ( /bin/rc
+in the example above) will be the name of the file being
+executed, any arguments on the
+.B #!
+line, the name of the file again,
+and finally the second and subsequent arguments given to the original
+.I exec
+call.
+The result honors the two conventions of a program accepting as argument
+a file to be interpreted and
+.B argv[0]
+naming the file being
+executed.
+.PP
+Most attributes of the calling process are carried
+into the result; in particular,
+files remain open across
+.I exec
+(except those opened with
+.B OCEXEC
+OR'd
+into the open mode; see
+.IR open (2));
+and the working directory and environment
+(see
+.IR env (3))
+remain the same.
+However, a newly
+.I exec'ed
+process has no notification handler
+(see
+.IR notify (2)).
+.PP
+When the new program begins, the global cell
+.B _clock
+is set to the address of a cell that keeps approximate time
+expended by the process at user level.
+The time is measured in milliseconds but is updated at
+a system-dependent lower rate.
+This clock is typically used by the profiler but is available
+to all programs.
+.PP
+The global cell
+.B _privates
+points to an array of
+.B _nprivates
+elements of per-process private data.
+This storage is private for each process, even if the processes share data segments.
+.PP
+The above conventions apply to C programs; the raw system
+interface to the new image is as follows:
+the word pointed to by the stack pointer is
+.BR argc ;
+the words beyond that are the zeroth and subsequent elements
+of
+.BR argv ,
+followed by a terminating null pointer; and
+the return register (e.g.
+.B R0
+on the 68020) contains the address of the clock.
+.SH SOURCE
+.B /sys/src/libc/9syscall
+.br
+.B /sys/src/libc/port/execl.c
+.SH SEE ALSO
+.IR prof (1),
+.IR intro (2),
+.IR stat (2)
+.SH DIAGNOSTICS
+If these functions fail, they return and set
+.IR errstr .
+There can be no return from a successful
+.I exec
+or
+.IR execl ;
+the calling image is lost.