EXEC(2) EXEC(2)
NAME
exec, execl, _privates, _nprivates, _tos - execute a file
SYNOPSIS
#include <u.h>
#include <libc.h>
void* exec(char *name, char* argv[])
void* execl(char *name, ...)
void **_privates;
int _nprivates;
#include <tos.h>
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 */
};
extern Tos *_tos;
DESCRIPTION
Exec and execl overlay the calling process with the named
file, then transfer to the entry point of the image of the
file.
Name points to the name of the file to be executed; it must
not be a directory, and the permissions must allow the cur-
rent user to execute it (see stat(2)). It should also be a
valid binary image, as defined in the a.out(6) for the cur-
rent machine architecture, or a shell script (see rc(1)).
The first line of a shell script must begin with `#!' fol-
lowed by the name of the program to interpret the file and
any initial arguments to that program, for example
#!/bin/rc
ls | mc
When a C program is executed, it is called as follows:
void main(int argc, char *argv[])
Page 1 Plan 9 (printed 11/17/24)
EXEC(2) EXEC(2)
Argv is a copy of the array of argument pointers passed to
exec; that array must end in a null pointer, and 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. Execl is like exec except that argv will be an
array of the parameters that follow name in the call. The
last argument to execl must be a null pointer.
For a file beginning #!, the arguments passed to the program
(/bin/rc in the example above) will be the name of the file
being executed, any arguments on the #! line, the name of
the file again, and finally the second and subsequent argu-
ments given to the original exec call. The result honors
the two conventions of a program accepting as argument a
file to be interpreted and argv[0] naming the file being
executed.
Most attributes of the calling process are carried into the
result; in particular, files remain open across exec (except
those opened with OCEXEC OR'd into the open mode; see
open(2)); and the working directory and environment (see
env(3)) remain the same. However, a newly exec'ed process
has no notification handler (see notify(2)).
The global cell _privates points to an array of _nprivates
elements of per-process private data. This storage is pri-
vate for each process, even if the processes share data seg-
ments.
When the new program begins, the global pointer _tos is set
to the address of a structure that holds information allow-
ing 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 rforks and execs. If there is
a user-space accessible fast clock (a processor cycle
counter), cyclefreq will be set to its frequency in Hz.
Kcycles (pcycles) counts the number of cycles this process
has spent in kernel mode (kernel and user mode). Pid is the
current process's id. Clock is the user-profiling clock
(see 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 pro-
grams.
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 argc; the words beyond that are
the zeroth and subsequent elements of argv, followed by a
terminating null pointer; and the return register (e.g. R0
on the 68020) contains the address of the clock information.
SOURCE
Page 2 Plan 9 (printed 11/17/24)
EXEC(2) EXEC(2)
/sys/src/libc/9syscall
/sys/src/libc/port/execl.c
SEE ALSO
prof(1), intro(2), stat(2)
DIAGNOSTICS
If these functions fail, they return and set errstr. There
can be no return to the calling process from a successful
exec or execl; the calling image is lost.
BUGS
There is a large but finite limit on the size of an argment
list, typically around 409,600 bytes. The kernel constant
TSTKSIZ controls this.
Page 3 Plan 9 (printed 11/17/24)