diff options
Diffstat (limited to 'sys/man/2/exec')
| -rwxr-xr-x | sys/man/2/exec | 200 |
1 files changed, 200 insertions, 0 deletions
diff --git a/sys/man/2/exec b/sys/man/2/exec new file mode 100755 index 000000000..5c5e79669 --- /dev/null +++ b/sys/man/2/exec @@ -0,0 +1,200 @@ +.TH EXEC 2 +.SH NAME +exec, execl, _privates, _nprivates, _tos \- execute a file +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.nf +.B +void* exec(char *name, char* argv[]) +.PP +.B +void* execl(char *name, ...) +.PP +.B +void **_privates; +.PP +.B +int _nprivates; +.PP +.B +#include <tos.h> +.PP +.ft L +typedef struct Tos Tos; +struct Tos { + struct { ... } prof; /* profiling data */ + uvlong cyclefreq; /* cycle clock frequency */ + vlong kcycles; /* kernel cycles */ + vlong pcycles; /* process cycles (kernel + user) */ + ulong pid; /* process id */ + ulong clock; /* profiling clock */ + /* top of stack is here */ +}; +.PP +.B +extern Tos *_tos; +.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 +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 +When the new program begins, the global pointer +.B _tos +is set to the address of a structure +that holds information +allowing accurate time keeping and clock reading in user space. +These data are updated by the kernel during of the life of the process, +including across +.IR rfork s +and +.IR exec s. +If there is a user-space accessible fast clock (a processor +cycle counter), +.B cyclefreq +will be set to its frequency in Hz. +.B Kcycles +.RB ( pcycles ) +counts the number of cycles +this process has spent in kernel mode +(kernel and user mode). +.B Pid +is the current process's id. +.B Clock +is the user-profiling clock (see +.IR prof (1)). +Its 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 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 information. +.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 to the calling process from a successful +.I exec +or +.IR execl ; +the calling image is lost. +.SH BUGS +There is a large but finite limit on the size of an argment list, +typically around 409,600 bytes. +The kernel constant +.B TSTKSIZ +controls this. |