From cfa37a7b1131abbab2e7d339b451f5f0e3198cc8 Mon Sep 17 00:00:00 2001 From: rsc Date: Sat, 10 Apr 2004 18:53:55 +0000 Subject: Lots of man pages. --- man/man3/exec.3 | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 man/man3/exec.3 (limited to 'man/man3/exec.3') 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 +.br +.B #include +.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. -- cgit v1.2.3